Java EE Security API Specification

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119, "Key words for use in RFCs to Indicate Requirement Levels" [RFC2119].

Other documents referenced by this specification are identified by name on first use, and thereafter by a short abbreviation. The "Bibliography" section at the end of this document provides full references.

The authors would like to thank the JSR-375 Expert Group and Contributors, and, in particular, Arjan Tijms, whose contributions were critical to the success of the JSR.

We would also like to thank Alex Kosowski for his work putting together the original JSR-375 proposal, submitting it to the JCP, recruiting a diverse and highly-qualified expert group, and leading the initial development and specification efforts. Without Alex, there would be no JSR-375.

Lastly, we would like to acknowledge Ron Monzillo, and the various expert groups he has led or worked with over the years, for putting in place the foundational security APIs and SPIs upon which JSR-375 is built.

A common understanding of security-related terms is helpful for discussion or specification of security APIs. To that end, we incorporate by reference the excellent Apache Shiro Terminology [SHIROTERM], and define some additional terms used in this document.

The following general requirements are defined by this specification.

A web application consists of resources that can be accessed by any number of callers, who are initially unknown to the application. Callers make themselves known to the application through the process of authentication.

During authentication, the caller presents proof of identity — a token or credential of some kind — which the application (or container) then validates. If the proof is valid, the application (or container) establishes the caller’s identity, then proceeds to the authorization step, in which it determines whether the caller has permission to access the requested resources.

In some cases (for example, username/password authentication) the interaction between the caller and the application is simple. In other cases, a lengthier dialog is required — an application may send a random nonce to the caller, which must then use that nonce in the construction of an authentication token, or there may be interactions with a third party that vouches for the caller’s identity, or the authenticity of the provided credential.

The Java EE Platform already specifies mechanisms for authenticating users of web applications. JSR-340, "Java Servlet Specification", version 3.1 [SERVLET31] specifies a declarative mechanism for configuring an application to provide BASIC, DIGEST, FORM, or CERT authentication, with authentication performed automatically by the container based on the application’s configuration, which, in the case of FORM authentication, can include custom form pages.

In addition, [JASPIC] specifies a general-purpose mechanism for securing messages sent between Java EE clients and servers. JASPIC defines an SPI called ServerAuthModule, which enables development of authentication modules to handle any credential type, or engage in interaction of arbitrary complexity with clients and third parties. [JASPIC] also defines the Servlet Container Profile, which specifies how JASPIC mechanisms, including ServerAuthModules, are integrated with the servlet container.

While both existing mechanisms are important and useful, each has limitations from the point of view of an application developer. The servlet container’s login-config mechanism is limited to the auth-method types defined by [SERVLET31] — it doesn’t support other credential types, or complex interactions with callers. It also relies on unspecified container mechanisms to associate identity stores with applications. There is no way for an application to ensure that callers are authenticated against the desired identity store, or, indeed, against any identity store.

JASPIC, by way of contrast, is extremely flexible and powerful, but is also complex. Writing an AuthModule, and arranging for the web container to use it for authentication, is a non-trivial exercise. Additionally, there is no declarative configuration syntax for JASPIC, and there is no well-defined mechanism for a container to override an application’s programmatically-registered AuthModule. A container can choose to register its own AuthModule, or to remove one registered by an application, but JASPIC will always use the most-recently-registered module — the outcome is dependent on the order in which the application and the container attempt to register their respective modules.

The HttpAuthenticationMechanism interface is designed to capitalize on the strengths of existing authentication mechanisms, while mitigating the corresponding limitations. It is essentially a simplified, servlet-container-specific version of the JASPIC ServerAuthModule interface, retaining that interface’s flexibility and power, but reducing the cost of implementation. An HttpAuthenticationMechanism is a CDI bean, and is therefore made available to the container automatically by CDI. The container is responsible for placing the HttpAuthenticationMechanism in service.

An application MAY supply its own HttpAuthenticationMechanism, if desired. The servlet container MUST provide several default HttpAuthenticationMechanism implementations, which an application can select and configure via standard annotations. The container MAY also provide additional mechanisms beyond those required by this specification. The rules governing how the container selects an HttpAuthenticationMechanism, and how it is placed in service, are described in the "Installation and Configuration" section of this chapter. The required default mechanisms, and corresponding annotations, are described in the "Annotations and Built-In HttpAuthenticationMechanism Beans" section.

The HttpAuthenticationMechanism interface defines three methods that align closely with the methods defined by the JASPIC ServerAuth interface. The primary distinction is syntactic; unlike JASPIC, HttpAuthenticationMechanism is specified for the servlet container only, and can therefore reference servlet types in its method signatures. Only the validateRequest() method must be implemented; default behaviors are specified for the other two methods.

Each method performs the same function as the corresponding ServerAuth method. At runtime, the methods will be invoked by a container-supplied ServerAuthModule that serves as a wrapper, or container, for the HttpAuthenticationMechanism. The container-supplied ServerAuthModule translates the method parameters passed to it, invokes the HttpAuthenticationMechanism method, and returns the resulting status to its caller. The behavior of the HttpAuthenticationMechanism methods should therefore be functionally equivalent to the behavior specified by the JASPIC Servlet Container Profile for the equivalent ServerAuthModule methods.

Summarized, this means:

The validateRequest() method is provided to allow a caller to authenticate. An implementation of this method can inspect the HTTP request to extract a credential or other information, or it can write to the HTTP response to, for example, redirect a caller to an OAuth provider, or return an error response. After a credential has been obtained and validated, the result of the validation can be communicated to the container using the HttpMessageContext parameter, which is described in more detail below.

The secureResponse() method is provided to allow post processing on the response generated by a servlet and/or servlet filter, such as encrypting it.

The cleanSubject() is provided to allow for cleanup after a caller is logged out. For example, an authentication mechanism that stores state within a cookie can remove that cookie here.

The HttpMessageContext interface defines methods that an HttpAuthenticationMechanism can invoke to communicate with the JASPIC ServerAuthModule (bridge module) that invokes it. The container MUST provide an implementation of the interface that supports the necessary container integrations.

The HttpMessageContextWrapper class implements a wrapper can be used, in a manner similar to HttpServletRequestWrapper, to provide custom behavior.

See javadoc for a detailed description of HttpMessageContext and HttpMessageContextWrapper. See below for more on the JASPIC bridge module.

An HttpAuthenticationMechanism must be a CDI bean, and is therefore visible to the container through CDI if it is packaged in a bean archive, which generally includes Java EE modules and application archives, as well as other archives and classes that are not part of an application, but are required by the Java EE specification to be visible to applications. See the CDI specification for details on bean archives and bean discovery. An HttpAuthenticationMechanism is assumed to be normal scoped.

It MUST be possible for the definition of an HttpAuthenticationMechanism to exist within the application archive. Alternatively such definition MAY also exists outside the application archive, for example in a jar added to the classpath of an application server.

An application packages its own HttpAuthenticationMechanism by including in a bean archive that is part of the application. Alternatively, it may select and configure one of the container’s built-in mechanisms using the corresponding annotation, as described in the "Annotations and Built-In HttpAuthenticationMechanism Beans" section below.

The container decides which HttpAuthenticationMechanism to place in service using the following rules:

The container MUST use JASPIC when placing an HttpAuthenticationMechanism in service. The container MUST supply a "bridge" ServerAuthModule that integrates HttpAuthenticationMechanism with JASPIC. The bridge module MUST look up the correct HttpAuthenticationMechanism using CDI, then delegate to the HttpAuthenticationMechanism when the bridge module’s methods are invoked. Since the method signatures and return values of the two interfaces are similar, but not the same, the bridge module MUST convert back and forth.

When an HttpAuthenticationMechanism is placed in service, the container MUST supply a bridge ServerAuthModule and the necessary supporting modules (AuthContext, AuthConfig, AuthConfigProvider), and arrange for the AuthConfigProvider to be registered with the JASPIC AuthConfigFactory, such that the bridge module is registered for the application context.

When an HttpAuthenticationMechanism is placed in service, the container MUST NOT register any AuthConfigProvider other than the one corresponding to the bridge ServerAuthModule. Given the nature of JASPIC, however, it’s possible that some other entity could register a different AuthConfigProvider after the container has registered the bridge module’s AuthConfigProvider. The container is NOT REQUIRED to prevent this.

A Java EE container MUST support built-in beans for the following HttpAuthenticationMechanism types, to be made available via configuration:

All of these beans MUST have the qualifier @Default and the scope @ApplicationScoped, as defined by the CDI specification.

All of the built-in beans MUST support authentication using IdentityStore, described in Chapter 3, "Identity Store", but MAY fall-back to container-specific methods if no IdentityStore is available.

See also the "Implementation Notes" section of this chapter.

The annotations are defined as shown in the following sections.

An HttpAuthenticationMechanism is a CDI bean, as defined by JSR-346, "Contexts and Dependency Injection for the Java EE platform", version 1.2 [CDI12].

The methods defined by the HttpAuthenticationMechanism closely map to the methods and semantics of a ServerAuthModule, as defined by the Servlet Container Profile of [JASPIC]. (But an HttpAuthenticationMechanism is itself not a ServerAuthModule.) The servlet container MUST use JASPIC mechanisms to arrange for an HttpAuthenticationMechanism to be placed in service.

This specification mandates that when a ServerAuthModule is called by the Servlet container, CDI services (such as the BeanManager) MUST be fully available, and all scopes that are defined to be active during the service() method of a servlet, or during the doFilter() method of a servlet filter, MUST be active. Specifically this means that the request, session, and application scopes MUST be active, and that a ServerAuthModule method such as validateRequest() MUST be able to obtain a reference to the CDI BeanManager programmatically (for example, by doing a JNDI lookup), and MUST be able to use that reference to obtain a valid request-scoped, session-scoped, or application-scoped bean. This specification does not mandate that a ServerAuthModule must itself be a CDI bean, or that a ServerAuthModule must be injectable.

An HttpAuthenticationMechanism implementation is logically equivalent to a built-in authentication mechanism as defined by [SERVLET31] (i.e., HTTP Basic Authentication, HTTP Digest Authentication, Form Based Authentication, and HTTPS Client Authentication); more specifically, it corresponds to an "additional container authentication mechanism", as described in section 13.6.5 of [SERVLET31].

The BASIC and FORM authentication mechanisms as defined by this specification are logically equivalent to the similarly named authentication mechanisms in [SERVLET31], respectively sections 13.6.1, "HTTP Basic Authentication", and 13.6.3, "Form Based Authentication".

IdentityStore provides an abstraction of an identity store, which is a database or directory (store) of identity information about a population of users that includes an application’s callers. An identity store holds caller names, group membership information, and information sufficient to allow it to validate a caller’s credentials. An identity store may also contain other information, such as globally unique caller identifiers (if different from caller name), or other caller attributes.

Implementations of the IdentityStore interface are used to interact with identity stores to authenticate users (i.e., validate their credentials), and to retrieve caller groups. IdentityStore is roughly analogous to the JAAS LoginModule interface, which is often integrated into Java EE products (albeit in vendor-specific ways). Unlike LoginModule, IdentityStore is intended specifically for Java EE, and provides only credential validation and group retrieval functions (i.e., functions that require interaction with an identity store). An IdentityStore does not collect caller credentials, or manipulate Subjects.

IdentityStore is intended primarily for use by HttpAuthenticationMechanism implementations, but could in theory be used by other types of authentication mechanisms (e.g., a JASPIC ServerAuthModule, or a container’s built-in authentication mechanisms). HttpAuthenticationMechanism implementations are not required to use IdentityStore — they can authenticate users in any manner they choose — but IdentityStore will often be a useful and convenient mechanism.

A significant advantage of using HttpAuthenticationMechanism and IdentityStore over container-provided BASIC or FORM implementations is that it allows an application to control the identity stores it will authenticate against, in a standard, portable way.

An IdentityStore is expected to perform only context- and environment-independent processing (for example, verifying usernames and passwords and returning caller data). It should provide a pure {credentials in, caller data out} function. An IdentityStore should not directly interact with the caller, or attempt to examine request context or application state.

The IdentityStoreHandler interface defines a mechanism for invoking on IdentityStore to validate a user credential. An HttpAuthenticationMechanism (or other caller) should not interact directly with an IdentityStore, but instead invoke the IdentityStoreHandler to validate credentials. The IdentityStoreHandler, in turn, invokes on the IdentityStore. An IdentityStoreHandler can also orchestrate an authentication across multiple IdentityStore instances, returning an aggregated result.

A default IdentityStoreHandler implementation is supplied by the container, but applications can also supply their own implementation. The orchestration behavior of the default IdentityStoreHandler is described in the "Handling Multiple Identity Stores" section below.

The IdentityStore interface defines two methods that are used by the runtime to validate a Credential or obtain caller information:

An implementation of IdentityStore can choose to handle either or both of these methods, depending on its capabilities and configuration. It indicates which methods it handles through the set of values returned by its validationTypes() method:

This method of declaring capabilities was chosen so that an IdentityStore could be written to support both methods, but configured to support just one or the other in any particular deployment.

The full interface is shown below (without default behaviors; signatures only).

Installation of an IdentityStore depends on the CDI specification. That is, an IdentityStore is considered installed and available for usage when it’s available to the CDI runtime as an enabled Bean. An IdentityStore is assumed to be normal scoped.

It MUST be possible for the definition of an IdentityStore to exist within the application archive. Alternatively such definition MAY also exists outside the application archive, for example in a jar added to the classpath of an application server.

As described above, in the "Declaring Capabilities" section, the IdentityStore interface includes two methods, validationTypes() and priority(), that enable an IdentityStore to declare its capabilities. Those capabilities may be intrinsic — determined by the IdentityStore's implementation — or they may be determined by the IdentityStore's configuration.

A Java EE container MUST support built-in beans for the following IdentityStore types, to be configured and made available via corresponding annotations:

Each of these beans MUST have the qualifier @Default and the scope @ApplicationScoped, as defined by the CDI specification.

The built-in identity stores MUST support validating UsernamePasswordCredential. They MAY support other credential types, but are NOT REQUIRED to.

The built-in identity stores MUST check whether a SecurityManager is configured, and, if so, check whether the calling context has IdentityStorePermission, as described in Retrieving Caller Information above, before proceeding.

Note that implementations are explicitly NOT REQUIRED to provide an LDAP server or database. The requirement is only to provide IdentityStore implementations that can work with an external LDAP or database server that may be present in the operating environment.

The corresponding annotations are defined as shown in the following sections.

IdentityStore and IdentityStoreHandler implementations are CDI beans, as defined by [CDI12].

The Java EE platform defines a declarative security model for protecting application resources. The declared constraints on access are then enforced by the container. In some cases the declarative model is not sufficient; for example, when a combination of tests and constraints is needed that is more complex than the declarative model allows for. Programmatic security allows an application to perform tests and grant or deny access to resources.

This specification provides an access point for programmatic security — a security context — represented by the SecurityContext interface.

In this version of the specification, the SecurityContext MUST be available in the Servlet container and the EJB container. Application servers MAY make SecurityContext available in other containers, but are NOT REQUIRED to.

The SecurityContext interface defines two methods that allow the application to test aspects of the caller data:

The getCallerPrincipal() method retrieves the Principal representing the caller. This is the container-specific representation of the caller principal, and the type may differ from the type of the caller principal originally established by an HttpAuthenticationMechanism. This method returns null for an unauthenticated caller. (Note that this behavior differs from the behavior of EJBContext.getCallerPrincipal(), which, per JSR-345, "Enterprise JavaBeans", version 3.2 [EJB32], returns a principal with a "product-specific unauthenticated principal name" to represent an unauthenticated caller.)

The getPrincipalsByType() method retrieves all principals of the given type. This method can be used to retrieve an application-specific caller principal established during authentication. This method is primarily useful in the case that the container’s caller principal is a different type than the application caller principal, and the application needs specific information behavior available only from the application principal. This method returns an empty Set if the caller is unauthenticated, or if the requested type is not found.

Where both a container caller principal and an application caller principal are present, the value returned by getName() MUST be the same for both principals.

See the Chapter 1, "Concepts", for more information on principal handling.

The isCallerInRole() method takes a String argument that represents the role that is to be tested for. It is undefined by this specification how the role determination is made, but the result MUST be the same as if the corresponding container-specific call had been made (i.e., HttpServletRequest.isUserInRole(), EJBContext.isCallerInRole()), and MUST be consistent with the result implied by other specifications that prescribe role-mapping behavior.

The SecurityContext interface defines a method for programmatically testing access to a resource:

The hasAccessToWebResource() method determines if the caller has access to the specified web resource for the specified HTTP methods, as determined by the security constraints configured for the application. See section 13.8 of [SERVLET31] for a description of web application security constraints.

The resource parameter is an URLPatternSpec that identifies an application-specific web resource. See the javadoc for more detail.

This method can only be used to check access to resources in the current application — it cannot be called cross-application, or cross-container, to check access to resources in a different application.

As an example, consider the following Servlet definition:

And the following call to hasAccessToWebResource():

The above hasAccessToWebResource() call would return true if and only if the caller is in role "foo".

The SecurityContext interface defines a method that allows an application to programmatically trigger the authentication process:

Programmatically triggering means that the container responds as if the caller had attempted to access a constrained resource. It causes the container to invoke the authentication mechanism configured for the application. If the configured authentication mechanism is an HttpAuthenticationMechanism, then the AuthenticationParameters argument is meaningful and extended capabilities of HttpAuthenticationMechanism are available. If not, the behavior and result is as if HttpServletRequest.authenticate() were called.

The authenticate() method allows an application to signal to the container that it should start the authentication process with the caller. This method requires a HttpServletRequest and HttpServletResponse parameters to be passed in, and can therefore only be used in a valid Servlet context.

The SecurityContext implementation is a CDI bean, as defined by [CDI12].

Various specifications in Java EE provide similar or even identical methods to those provided be the SecurityContext. It is the intention of this specification to eventually supersede those methods and provide a cross-specification, platform alternative. The following gives an overview: