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.

This profile does NOT impose any profile specific requirements on authentication context identifiers. As defined in Section 2.1.3, the authentication context identifier used in the call to getAuthContext must be equivalent to the value that would be acquired by calling getAuthContextID with the MessageInfo that will be used in the call to validateRequest.

A null value may be passed as the Subject argument in the getAuthContext call.

If the runtime is a Jakarta Authorization compatible Jakarta Servlet container, the properties argument passed in all calls to getAuthContext must contain the key-value pair shown in the following table.

When the runtime is not a Jakarta Authorization compatible Jakarta Servlet container, the properties argument used in all calls to getAuthContext must not include a jakarta.security.jacc.PolicyContext key-value pair, and a null value may be passed for the properties argument.

Each ServerAuthContext obtained through getAuthContext must initialize its encapsulated ServerAuthModule objects with a non-null value for requestPolicy. The encapsulated authentication modules may be initialized with a null value for responsePolicy.

The requestPolicy used to initialize the authentication modules of the ServerAuthContext must be constructed such that the value obtained by calling isMandatory on the requestPolicy accurately reflects whether (that is, true return value) or not (that is, false return value) authentication is required to access the web resource corresponding to the HttpServletRequest to which the ServerAuthContext will be applied. The message processing runtime is responsible for determining if authentication is required and must convey the results of its determination as described in Section 3.9.1.

Calling getTargetPolicies on the request MessagePolicy must return an array containing at least one TargetPolicy whose ProtectionPolicy will be interpreted by the modules of the context to mean that the source of the corresponding targets within the message is to be authenticated. To that end, calling the getID method on the ProtectionPolicy must return one of the following values:

The messageInfo argument used in the call to validateRequest must have been initialized by the runtime such that its getRequestMessage and getResponseMessage methods will return the HttpServletRequest and HttpServletResponse objects corresponding to the messages (respectively) being processed by the runtime. This must be the case even when the target of the request is a static page (that is, not a Servlet).

A new clientSubject must be instantiated and passed in the call to validateRequest.

As described in Section 3.9, the profile requires that validateRequest be called on every request that satisfies the corresponding connection requirements (and to which the Jakarta Servlet container security model applies). As such, validateRequest will be called either before the service invocation (to establish the caller identity) or after the service invocation (when a multi-message dialog is required to secure the response). The module implementation is responsible for recording any state and performing any processing required to differentiate these two different types of calls to validateRequest.

The requirements defined in this section must be fulfilled by a message processing runtime, when (at point (2) in the messaging model, validateRequest returns AuthStatus.SUCCESS. The requirements must also be fulfilled by HttpServletRequest.authenticate when its call to validateRequest returns AuthStatus.SUCCESS. In both cases, the HttpServletRequest must be modified as necessary to ensure that the Principal returned by getUserPrincipal and the String returned by getRemoteUser correspond, respectively, to the Principal established by validateRequest (via the CallerPrincipalCallback) and to the String obtained by calling getName on the established Principal footnote:Except when getUserPrincipal returns null; in which case the value returned by getRemoteUser must be null]. Both cases, must also ensure that the value returned by calling getAuthType on the HttpServletRequest is consistent in terms of being null or non-null with the value returned by getUserPrincipal.

When getAuthType is to return a non-null value, the Map of the MessageInfo object used in the call to validateRequest must be consulted to determine if it contains an entry for the key identified in Table 3-5 . If the Map contains an entry for the key, the corresponding value must be obtained from the Map and established as the getAuthType return value. If the Map does not contain an entry for the key, and an auth-method is defined in the login-config element of the deployment descriptor for the web application, the value from the auth-method must be established as the getAuthType return value. If the Map does not contain an entry for the key, and the deployment descriptor does not define an auth-method, a product defined default non-null value must be established as the getAuthType return value, and the same default value need not be used for both cases.

If a non-null Principal was established by validateRequest (via the CallerPrincipalCallback), the Map of the MessageInfo object used in the call to validateRequest must be consulted to determine if it contains an entry for the key identified in Table 3-6 . If the Map contains an entry for the key, the authentication session machinery of the container must be used to create (or update) a container authentication session to represent the caller Principal, authType, and the additional container authentication state established by the call to validateRequest. The resulting container authentication session must be bound to the HttpServletResponse such that the container will be able to restore the caller authentication results on subsequent calls to the application.

The authentication type and session registration properties are callback properties^[14] and are intended to provide a way for an authentication module to request a corresponding service from its encompassing runtime. As such, all authentication modules must ensure that they do not inadvertently relay these properties should they be included in their input MessageInfo arguments.

When an application calls HttpServletRequest.authenticate, HttpServletRequest.login, or HttpServletRequest.logout, the container implementation of the called method must determine (as defined in Section 3.7) if there is an AuthConfigProvider configured for the application context and layer. If not, the called method must proceed to perform the required authenticate, login, or logout functionality without further reliance on this sub-profile.

If an AuthConfigProvider is determined to be configured, the called method must proceed to obtain the corresponding ServerAuthConfig also as defined in Section 3.7.

As described in Section 2.1.1, the called method may reuse the results of a previous AuthConfigProvider determination and ServerAuthConfig acquisition (such as that performed by the message processing runtime) during its processing of the servlet request within which the authenticate, login, or logout method is being called.

The container implementation of login must throw a ServletException which may convey that the exception was caused by an incompatibility between the login method and the configured authentication mechanism.

If authenticate is called in the context of a call it made to validateRequest, it must not recall validateRequest, but must perform the container authentication processing that it performs when it determines that an AuthConfigProvider is not configured for the application context and layer.

Otherwise, authenticate must acquire the corresponding ServerAuthContext object as defined in Section 3.8 (and its subsections), while satisfying the additional requirement that the authentication context identifier used to obtain the ServerAuthContext must be the identifier that would be acquired by calling getAuthContextID with MessageInfo as defined in Section 3.9.1 and while satisfying the additional requirement that the MessageInfo map must unconditionally contain both the jakarta.security.auth.message.MessagePolicy.isMandatory key (with associated true value) and the jakarta.servlet.http.isAuthenticationRequest key (with associated true value).

Authenticate must call validateRequest on the acquired ServerAuthContext. The MessageInfo argument to the call to validateRequest must be as defined above. The clientSubject argument must be a non-null Subject and should be the Subject resulting from the call to validateRequest prior to the service invocation as described in Section 3.9.3.1. If the prior Subject is not used, A new (empty) clientSubject must be instantiated and passed in the call to validateRequest. A null value may be used for the serviceSubject.

If the call to validateRequest returns AuthStatus.SUCCESS, the authenticate method must perform the processing defined in Section 3.9.4. This processing includes establishing return values for getUserPrincipal, getRemoteUser, and getAuthType and may include the registration of the authentication results in a container authentication session^[15] Following this processing, the authenticate method must return the boolean value true, and if the calling context is configured to run-as its caller, the results of the authentication must be reflected in the run-as identity.

If the call to validateRequest throws an AuthException, the authenticate method must catch the AuthException and throw a ServletException.

If the call to validateRequest returns any value other than AuthStatus.SUCCESS, the authenticate method must return false.

If logout is called in the context of a call it made to cleanSubject, it must not recall cleanSubject, but it must perform the logout processing that it performs when it determines that an AuthConfigProvider is not configured for the application context and layer.

Otherwise, logout must acquire the corresponding ServerAuthContext object as defined in Section 3.8 (and its subsections), while satisfying the additional requirement that the authentication context identifier used to obtain the ServerAuthContext must be the identifier that would be acquired by calling getAuthContextID with MessageInfo as defined in Section 3.9.1 and while satisfying the additional requirement that the MessageInfo map must unconditionally contain the jakarta.security.auth.message.MessagePolicy.isMandatory key (with associated true value). Logout should attempt to satisfy the requirement of Section 3.9.1, that MessageInfo be initialized such that its getResponseMessage will return the HttpServletResponse, but need not do so if the response is unavailable or committed.

The container implementation of logout must call cleanSubject on the acquired ServerAuthContext. The MessageInfo argument to the call to cleanSubject must be as defined above. The clientSubject argument must be a non-null Subject and should be the Subject resulting from the most recent call to validateRequest which may have occurred either as described in Section 3.9.3.1 or as described in <<a487>. If the prior Subject is not used, a new clientSubject must be instantiated and passed in the call.

Following the return from cleanSubject, logout must perform the logout processing that it performs when it determines that an AuthConfigProvider is not configured for the application context and layer, and if the calling context is configured to run-as its caller, the results of the logout must be reflected in the run-as identity.

If HttpServletRequest.authenticate or HttpServletRequest.logout is called from within the methods of the ServerAuthContext interface (for example, from within validateRequest, secureResponse, or cleanSubject), it is the responsibility of the implementation of the ServerAuthContext to interpret the results of the call and to establish appropriate ServerAuthContext return values. This profile is silent on the details of the interpretation and mapping of return values.

The Jakarta EE JNDI component namespaces (java:global, java:app, java:module, java:comp) MUST be made available to code running in the context of a call to validateRequest, secureResponse and cleanSubject on the acquired ServerAuthContext.

A practical use case for this is obtaining (application scoped) data sources, which a ServerAuthModule could use to validate credentials.

Example:

The CDI built-in scopes according to "2.4.1. Built-in scope types" of the CDI specification MUST be made available to code running in the context of a call to validateRequest, secureResponse and cleanSubject on the acquired ServerAuthContext.

A practical use case for this is obtaining application scoped identity stores, which a ServerAuthModule could use to validate credentials.

Example:

Note that it is a non-requirement that a ServerAuthModule is itself a CDI managed bean, and as such it is not required that services such as injection using the @Inject annotation are available to a ServerAuthModule. It is only required that programmatic lookup such as shown in the example above works correctly.

This profile does NOT impose any profile specific requirements on authentication context identifiers. As defined in Section 2.1.3, the authentication context identifier used in the call to getAuthContext must be equivalent to the value that would be acquired by calling getAuthContextID with the MessageInfo that will be used in the corresponding call to secureRequest (by a client runtime) or validateRequest (by a server runtime).

Each authentication context object obtained through getAuthContext must initialize its encapsulated authentication modules with a non-null requestPolicy and/or a non-null responsePolicy, such that at least one of requestPolicy or responsePolicy is not null.

The application context identifier used by a client-runtime to acquire the `AuthConfigProvider`and ClientAuthConfig objects pertaining to the client side processing of a web service invocation shall begin with a client scope identifier that identifies the client. If the client-runtime may host multiple client applications, then the client scope identifier must differentiate among the client applications deployed within the runtime. In runtimes where applications are differentiated by unambiguous application identifiers, an application identifier may be used as the client scope identifier. Where application identifiers are not defined or suitable, the location (for example, its file path) of the client archive from which the invocation will originate may be used as the client scope identifier.

In addition to its client scope identifier, the application context identifier must include a client reference to the service. If a service reference is defined for the invocation (for example, by using a WebServiceRef annotation as defined in the Jakarta XML Web Services specifications), the client reference to the service must be the name value of the service reference. If a service reference was not defined for the invocation, the client reference to the service must be the web service URL.

A client application context identifier must be the String value composed by concatenating the client scope identifier, a blank separator character, and the client reference to the service.

The following are examples of client application context identifiers.

Systems or administrators that register AuthConfigProvider objects with specific client-side application context identifiers must have an ability to determine the client scope identifier and the client reference for which they wish to perform the registration.

Unless the client runtime is embedded in a server runtime (for example, an invocation of a web service by a servlet running in a Servlet container), the CallbackHandler passed to ClientAuthModule.initialize must support the following callbacks:

In either event, the CallbackHandler must also support the requirements in Section 4.5

If a non-null AuthConfigProvider`is returned (by the call to getConfigProvider), the messaging runtime must call `getClientAuthConfig on the provider to obtain the authentication context configuration object pertaining to the application context at the layer. The layer and appContext arguments of the call to getClientAuthConfig must be the same as those used to acquire the provider, and the handler argument must be as defined in Section 4.8.2 for a client runtime.

The getAuthContext calls made on the ClientAuthConfig (obtained by calling getClientAuthConfig) must satisfy the requirements defined in the following subsections.

A client runtime, after having prepared (except for security) the SOAP request message to be sent to the service, is operating at point (1) in the message processing model defined by this specification. A client runtime that has received a SOAP response message, and that has not yet performed any transformations on the response message, is operating at point (4) in the message processing model defined by this specification.

If the client runtime obtained a non-null ClientAuthContext by using the authentication context identifier corresponding to the request message, then at point (1) in the message processing model, the runtime must call secureRequest on the ClientAuthContext, and at point (4) the runtime must call validateResponse on the ClientAuthContext.

When processing a one-way application message exchange pattern, the runtime must not proceed to point (4) unless the return value from secureRequest (or a from validateResponse) is AuthStatus.SEND_CONTINUE.

The application context identifier used by a server-runtime to acquire the AuthConfigProvider and ServerAuthConfig objects pertaining to the endpoint side processing of an invocation shall be the String value constructed by concatenating a host name, a blank separator character, and the path^[18] component of the service endpoint URI corresponding to the webservice.

In the definition of server-side application context identifiers, this profile uses the term host name to refer to the logical host that performs the service corresponding to a service invocation. Web service invocations may be directed to a logical host using various physical or virtual host names or addresses, and a message processing runtime may be composed of multiple logical hosts. Systems or administrators that register `AuthConfigProvider`objects with specific server-side application context identifiers must have an ability to determine the hostname for which they wish to perform the registration.

The CallbackHandler passed to ServerAuthModule.initialize must support the following callbacks:

The CallbackHandler must also support the requirements in Section 4.5

If a non-null AuthConfigProvider is returned (by the call to getConfigProvider), the messaging runtime must call getServerAuthConfig on the provider to obtain the authentication context configuration object pertaining to the application context at the layer. The layer and appContext arguments of the call to getServerAuthConfig must be the same as those used to acquire the provider, and the handler argument must be as defined in Section 4.9.2 for a server runtime.

The getAuthContext calls made on the ServerAuthConfig object (obtained by calling getServerAuthConfig) must satisfy the requirements defined in the following subsections.

A server runtime that has received a SOAP request message, and that has not yet performed any transformations on the SOAP message, is operating at point (2) in the message processing model defined by this specification. A server runtime, after having prepared (except for security) a SOAP response message to be returned to the client, is operating at point (3) in the message processing model defined by this specification.

When processing a one-way application message exchange pattern, the runtime must not proceed to point (3) in the message processing model, and the runtime must only return a response message when validateRequest returns AuthStatus.SEND_CONTINUE (in which case, the response defined by validateRequest is to be returned).

If the server runtime obtained a non-null ServerAuthContext by using the authentication context identifier corresponding to the request message, then at point (2) in the message processing model, the runtime must call validateRequest on the ServerAuthContext, and at point (3) the runtime must call secureResponse on the ServerAuthContext.

If the call to validateRequest returns AuthStatus.SUCCESS, the runtime must perform any web service authorization processing^[19] required as a prerequisite to accessing the target resource. If authentication is required for the request to be authorized, the runtime must determine whether the authentication identity established in the clientSubject is authorized to access the resource. In a Jakarta Authorization compatible runtime, the identity tested for authorization must be comprised of exactly the Principal objects of the clientSubject. If the request is NOT authorized, and the message-exchange pattern is not one-way, the runtime must set within the response (within messageInfo) a SOAP fault element as defined by the runtime. If the request was determined to be authorized, it must be dispatched to the resource. Otherwise the request must NOT be dispatched and the runtime must proceed to point (3) in the message processing model (as appropriate to the message exchange pattern).

If the invocation of the resource results in an exception being thrown by the resource to the runtime and the message exchange pattern is not one-way, the runtime must set within the response (within messageInfo) a SOAP fault element as defined by the runtime. Following the resource invocation, and if the message exchange pattern is not one-way, the runtime must proceed to point (3) in the message processing model. At point (3) in the message processing model, the runtime must call secureResponse on the same ServerAuthContext used in the corresponding call to validateRequest and with the same MessageInfo object.

If the request is dispatched to the resource, and the resource was configured to run-as its caller, then for invocations originating from the resource where caller propagation is required, the identity established using the CallerPrincipalCallback must be used as the propagated identity.

This profile would employ jakarta.jms.Message as its message abstraction. Properties would be set on the Message to convey security credentials and security results.

In this profile, application contexts could be defined for JMS destinations, such that authentication configuration providers could be registered for interactions with destinations, and such that authentication context configuration objects could be defined for interactions with destinations.

A client profile could require that secureRequest be called when a Message is sent by a MessageProducer to a Destination and that validateResponse be called when a Message is received by a MessageConsumer from a Destination.

A server profile could require that validateRequest be called when a Destination receives a message from a MessageProducer, and that secureResponse be called when a Destination sends a message to a MessageConsumer.

in Section 4.9.5.4, corrected the required return value when responsePolicy == null to be AuthStatus.SEND_SUCCESS.

Changed document Identifier to Maintenance Release A. Version identifier remains unchanged at 1.0.

Clarified definition of baseline compatibility requirements to more explicitly convey that the API is intended to have more general applicability than the specific contexts of its use defined within the specification.

In javax.security.auth.message.callback.CallerPrincipalCallback, modified callback definition to allow for principal mapping to occur during the handling of the callback by the CallbackHandler.