Jakarta Authentication

THIS DOCUMENT IS PROVIDED "AS IS," AND THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

THE COPYRIGHT HOLDERS AND THE ECLIPSE FOUNDATION WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of the copyright holders or the Eclipse Foundation may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

As described above, there are two types of authentication modules. A client authentication module implements the ClientAuthModule interface and is invoked (indirectly) by a message processing runtime at points 1 and 4 (that is, secureRequest and validateResponse) in the message processing model. A server authentication module implements the ServerAuthModule interface and is invoked (indirectly) by a message processing runtime at points 2 and 3 (that is, validateRequest and secureResponse) in the message processing model.

When an authentication module is invoked at the identified message processing points, it is provided access to the request and response messages (as appropriate to the point in the interaction) and proceeds to secure or validate them as appropriate. For example, when secureRequest is invoked on a client authentication module, the module may attach a user name and password to the request message. Similarly, when validateRequest is called, the server authentication module may extract a user name and password from the message and validate them against a user database. Note that authentication modules are responsible for securing or validating messages, while the message processing runtime remains responsible for transport of messages and invocation of the corresponding application level processing.

A message processing runtime invokes client authentication modules by interacting with a client authentication context object, and server authentication modules by interacting with a server authentication context object. An authentication context object is an implementation of either the ClientAuthContext or ServerAuthContext interface as defined by this specification. A message processing runtime may acquire the authentication context objects that it uses to invoke authentication modules by interacting with an authentication context configuration object. An authentication context configuration object is an implementation of either the ClientAuthConfig or ServerAuthConfig interface as defined by this specification.

An authentication context is responsible for constructing, initializing, and coordinating the invocation of one or more encapsulated authentication modules. If the context implementation supports the configuration of multiple authentication modules within a context (for example, as sufficient alternatives), the context coordinates the invocation of the authentication modules on behalf of both the message processing runtime and the authentication modules.

A client message processing runtime interacts with an implementation of the ClientAuthContext interface to invoke the authentication modules of the context to perform message processing at points 1 and 4 (secureRequest and validateResponse) of the message processing model. Similarly, a server message processing runtime interacts with an implementation of the ServerAuthContext interface to invoke the modules of the context to perform message processing at points 2 and 3 (validateRequest and secureResponse) of the message processing model.

An authentication context configuration object serves a message processing runtime as the source of authentication contexts pertaining to the messages of an application at a messaging layer. The context configuration implementation is responsible for returning authentication context objects that encapsulate authentication module invocations sufficient to satisfy the security policy configured for an application message. A message processing runtime may use a representation of the message being processed to obtain the corresponding authentication context from the appropriate authentication context configuration object.

A client authentication context configuration object implements the ClientAuthConfig interface and provides ClientAuthContext objects for use by a message processing runtime at points 1 and 4 (secureRequest and validateResponse) in the message processing model. A server authentication context configuration object implements the ServerAuthConfig interface and provides ServerAuthContext objects for use by a message processing runtime at points 2 and 3 (validateRequest and secureResponse) in the message processing model.

A message processing runtime may acquire authentication context configuration objects by interacting with a provider of authentication context configuration objects.

An authentication context configuration provider is an implementation of the AuthConfigProvider interface. An authentication context configuration provider serves as a source of authentication context configuration objects, where as noted above, each configuration object serves as the source of authentication contexts pertaining to the messages of an application at a messaging layer.

An authentication context configuration provider embodies the implementation of a message authentication configuration mechanism. Each such configuration mechanism encapsulates the message authentication processing pertaining to applications in configuration objects that return context objects that coordinate the invocation of pluggable authentication modules to perform message authentication on behalf of the corresponding applications.

The AuthConfigFactory class serves as the catalog or registry of authentication context providers available for use by a runtime. A message processing runtime may interact with the factory to obtain or establish the provider registered for an application context and messaging layer.

Request and response messages are Java representations of the corresponding protocol messages, and are passed to authentication modules through an implementation of the MessageInfo interface which provides common methods for accessing protocol specific messages.

Authentication Modules that operate on messages for a specific protocol (for example, SOAP messages) are expected to be configured for and called from an appropriate message processing runtime (for example, a SOAP message processing runtime).

When an authentication module is initialized within an authentication context, it is passed policy information that specifies what authentication guarantees the module is to enforce when securing or validating request and response messages within that context. Policy information is conveyed by the authentication context to the authentication module in the form of MessagePolicy objects. Two separate MessagePolicy objects are passed to the module through its initialize method: One defines the message authentication policy to be applied to the request message, and the other defines the message authentication policy to be applied to the response.

A message authentication policy can be targeted at specific parts of the related message or to the message as a whole, and conveys the high level authentication guarantees that must be enforced by the modules of a context. The policy may specify, for example, that the source of a request must be authenticated. The mechanisms by which a module enforces the guarantees, or, in other words, how the module enforces the guarantees is up to the module.

Authentication modules should be implemented such that they may be invoked concurrently and such that they are able to apply and establish independent security identities for concurrent invocations. To this end, modules should rely on their invocation parameters and the callbacks supported by the CallbackHandler with which they were initialized to obtain any information required to establish the invocation context for which they were invoked.

In a multi-message authentication scenario, it is the responsibility of the authentication modules involved in the authentication to tie together or correlate the messages that comprise the authentication exchange. In addition to message correlation to tie together the messages required to complete an authentication, message correlation may also be employed post-authentication such that a prior authentication result or session may be applied to a subsequent invocation. Modules are expected to perform their message correlation function based on the parameters of their invocation and with the benefit of any additional facilities provided by the invoking runtime (for example, through their CallbackHandler).

To assist modules in performing their correlation function, calls made to validateResponse must be made with the same messageInfo object used in the call to secureRequest (or validateResponse) that elicited the response. Similarly, calls made to secureResponse must be made with the same messagInfo object that was passed to validateRequest (for the corresponding request message). Modules are also expected to avail themselves of persisted state management facilities (for example, jakarta.servlet.http.HttpSession facilities) provided by the invoking runtime. The use of such facilities prior to authentication may increase the system’s susceptibility to a denial-of-service attack, and their use by authentication modules should be considered in that regard.

For security mechanisms or protocols where message correlation is dependent on the content of exchanged messages, it is the responsibility of the authentication modules to ensure that the required correlation information is inserted in the exchanged messages. For security mechanisms where message correlation is dependent on context external to the exchanged messages, such as the transport connection or session on which messages are received, the authentication modules will be dependent on correlation related facilities provided by the runtime.

This version of this specification does not define the interfaces by which runtimes present correlation facilities to authentication modules.

Authentication modules may require security information from the message processing environment that invoked them. For example, a ClientAuthModule may require access to the client’s key pair to sign requests made on behalf of the client. The client’s keys would typically have been configured as part of the client application itself. Likewise, a ServerAuthModule may require access to the server’s key pair to sign responses from the server. The server’s keys would typically be configured as part of the server.

To access cryptographic keys or other external security credentials configured as part of the encompassing runtime, an authentication module is provided with a CallbackHandler (at initialization). The CallbackHandler is provided by the encompassing runtime and serves to provide the authentication module with access to facilities of the encompassing runtime.

The module can ask the CallbackHandler to handle requests for security information needed by the module to perform its message authentication processing.

When an authentication module is invoked to validate a message, it is passed a Subject object to receive the credentials of the source of the message and a separate Subject object to represent the credentials of the recipient of the message (such that they are available to validate the message). When an authentication module is invoked to validate a message, it communicates the message source or caller authentication identity to its calling runtime (for example, container) through (that is, by modifying) the Subject associated with the source of the message.

Authentication modules may rely on the Subjects as well as the CallbackHandler, described in Section 1.1.8, to obtain the security information necessary to secure or validate messages. When an authentication module is invoked to secure a message, it is passed a Subject object that may convey the credentials of the source of the message (such that they are available to secure the request).

Authentication modules and authentication contexts return AuthStatus values to characterize the outcome of their message processing. When an AuthStatus value is returned, its value represents the logical result of the module processing and indicates that the module has established a corresponding request or response message within the MessageInfo parameter exchanged with the runtime.

Authentication modules and authentication contexts throw exceptions when their processing was unsuccessful and when that processing did not establish a corresponding request or response message to convey the error.

The vocabulary of AuthStatus values and exceptions returned by authentication modules, and their mapping to the message processing points at which they may be returned, is represented in the following table.

The following table describes the high level semantics associated with the status values and exceptions presented in the preceding table.

The expected behavior of runtimes in response to AuthStatus return values and AuthException exceptions is described in See What the Runtime Must Do. These behaviors may be specialized in profiles of this specification.

The message processing runtime acquires a provider of authentication context configuration objects for the relevant messaging layer and application identifier. This step is typically done once for each application, and may be accomplished as follows:

The message processing runtime acquires the authentication context configuration object for the application from the provider. This step is typically done at application deployment, and may be accomplished as follows:

or:

The resulting authentication context configuration object encapsulates all authentication contexts for the application at the layer. Its internal state will be kept up to date by the configuration system, and from this point until the application is undeployed, the configuration object represents a stable point of interaction between the runtime and the integrated authentication mechanisms for the purpose of securing the messages of the application at the layer.

A callback handler is associated with the configuration object when it is obtained from the provider. This callback handler will be passed to the authentication modules within the authentication contexts acquired from the configuration object. The runtime provides the callback handler so that the authentication modules may employ facilities of the messaging runtime (such as keying infrastructure) in their processing of application messages.

At points (1) and (2) in the message processing model, a message processing runtime creates a MessageInfo object and sets within it the message or messages being processed. The runtime uses the MessageInfo to acquire the authentication context identifier corresponding to the message from the authentication configuration object. This step is typically performed for every different ^[2] request and may be accomplished by a runtime as follows:

or:

The authentication context identifier will be used to select the authentication context with which to perform the message processing. In cases where the configuration system cannot determine the context identifier ^[3], the value null will be returned.

The authentication identifier is used to acquire an authentication context from the authentication context configuration object. The acquired authentication context encapsulates the one or more authentication modules that are to be invoked to process the identified messages. The authentication context is acquired from the authentication context configuration object as follows:

or:

The properties argument is used to pass additional initialization time properties to the authentication modules encapsulated in the authentication context. Such properties might be used to convey values specific to this use of the context by a user or with a specific service.

The Subject argument is used to make the principals and credentials of the sending entity available during the acquisition of the authentication context. If the Subject is not null, additional principals or credentials (pertaining to the sending entity) may be added (to the Subject) during the context acquisition.

Appropriate to its point of processing in the messaging model, the messaging runtime uses the MessageInfo described in Step 3 to invoke a method of the authentication context obtained in Step 4.

At point (1) in the messaging model, the`clientSubject` may contain the credentials used to secure the request, or the modules of the context may collect the client credentials including by using the callback handler passed through to them by the context. MessageInfo would contain a request message about to be sent. On successful return from the context, the runtime would extract the secured request message from messageInfo and send it.

At point (2), the clientSubject receives any principals or credentials established as a result of message validation by the authentication modules of the context. The serviceSubject may contain the credentials of the service or the modules of the context may collect the service credentials, as necessary, by using the callback handler passed to them by the context. MessageInfo would contain a received request message. On successful return from the context, the runtime may use the clientSubject to authorize and dispatch the validated request message, as appropriate.

At point (3), the serviceSubject may contain the credentials used to secure the response, or the modules of the context may collect the service credentials including by using the callback handler passed through to them by the context. The MessageInfo would contain a response message about to be sent and may also contain the corresponding request message received at point (2). On return from the context, the runtime would send the secured response message.

At point (4), the serviceSubject receives any principals or credentials established as a result of message validation by the authentication modules of the context. The clientSubject may contain the credentials of the receiving client or the modules of the context may collect the client credentials, as necessary, by using the callback handler passed to them by the context. MessageInfo would contain a received response message and may also contain the associated request message sent at point (1). On successful return from the context, the runtime may use the serviceSubject to authorize the response and would return the received message to the client, as appropriate.