This chapter defines a profile of the use of the interfaces defined in this specification to secure SOAP message exchanges between web services client runtimes and web service endpoint runtimes. This profile is equally applicable to SOAP versions 1.1 and 1.2.
This profile is composed of two internal profiles that partition the requirements of the profile into those that must be satisfied by client runtimes and those that must be satisfied by server runtimes. The profile-specific requirements defined in this chapter are to be considered in addition to the generic requirements defined in Chapter 2. A compatible implementation of an internal profile of this specification is an implementation that satisfies all of the requirements that apply to that profile.
The message layer value used to select the
AuthConfigProvider and ServerAuthConfig objects for this profile must be
“SOAP”.
The application context identifier (that is,
the appContext parameter value) used by a client runtime to select the
AuthConfigProvider and ClientAuthConfig objects pertaining to a
client-side application context configuration scope must be as defined
in See Client-Side Application Context
Identifier.
Similarly, the application context identifier
used by a server runtime to select the AuthConfigProvider and
ClientAuthConfig objects pertaining to an server-side application
context configuration scope must be as defined in
Server-Side Application Context Identifier.
The MessageInfo argument used in any call
made by the message processing runtime to secureRequest,
validateResponse, validateRequest, or secureResponse must have been
initialized such that any non-null objects returned by the
getRequestMessage and getResponseMessage methods of the MessageInfo are
an instanceof jakarta.xml.soap.SOAPMessage.
The getSupportedMessageTypes method of all authentication modules integrated for use with this profile must include jakarta.xml.soap.SOAPMessage.class in its return value.
The CallbackHandler passed to an
authentication module’s initialize method is determined by the handler
argument passed in the call to AuthConfigProvider.getClientAuthConfig or
getServerAuthConfig that acquired the corresponding authentication
context configuration object.
The handler argument must not be null, and the argument handler and the CallbackHandler passed to the initialize method of all authentication modules should support the following callbacks, and it must be possible to configure the runtime such that the CallbackHandler passed at module initialization supports the following callbacks (in addition to any others required to be supported by the applicable internal profile):
-
CertStoreCallback
-
PrivateKeyCallback
-
SecretKeyCallback
-
TrustStoreCallback
The argument handler and the CallbackHandler passed through to the modules must be initialized with any application context required to process the supported callbacks on behalf of the corresponding application.
The factory implementation returned by calling the getFactory method of the abstract AuthConfigFactory class must be configured such that it returns a non-null AuthConfigProvider for those application contexts for which pluggable authentication modules have been configured at the “SOAP” layer.
For each application context for which it is servicing requests, the runtime must call getConfigProvider to acquire the provider object corresponding to the layer and application context. The layer and appContext arguments to getConfigProvider must be as defined in Message Layer Identifier and Application Context Identifier respectively.
A null return value from getConfigProvider
indicates that pluggable authentication modules have not been configured
at the layer for the application context, and that the messaging runtime
must proceed to perform its SOAP message processing (for the application
context) without further reliance on this profile.
When a non-null AuthConfigProvider is
returned by the factory, the provider must have been configured with the
information required to initialize the authentication contexts for the
one or more authentication context configuration scopes, defined by
layer and application context, for which the provider is registered (at
the factory). The information typically required to initialize
authentication contexts is described by example in [a302].
When a non-null AuthConfigProvider is
returned by the factory, the messaging runtime must call getAuthContext
on the authentication context configuration object (obtained from the
provider). The authContextID argument used in the call to getAuthContext
must be the value as described in Authentication Context Identifiers.
A null return value from getAuthContext
indicates that pluggable authentication modules have not been configured
for the web service invocation within the authentication context
configuration scope, and that the runtime must proceed to perform its
SOAP message processing for this request/response without further
reliance on this profile.
Effective integration of a session-oriented
authentication mechanism for use in an authentication context
configuration scope should be expected to require configuration of the
corresponding AuthConfigProvider such that getAuthContext will return
non-null authentication context objects for all legitimate authContextID
values acquired for the corresponding scope.
This profile does NOT impose any profile specific requirements on authentication context identifiers. As defined in [a290], 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).
This section defines the requirements of this profile that must be satisfied by a runtime operating in the client role. A runtime may operate in both the client and server roles.
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.
AppContextID ::= client-scope-identfier blank client-referenceThe following are examples of client application context identifiers.
"petstoreAppID service/petstore/delivery-service"
"petstoreAppID http://localhost:8080/petstore/delivery-service/fish"
"/home/fishkeeper/petstore-client.jar service/petstore/delivery-service"
"/home/fishkeeper/petstore-client.jar http://localhost:8080/petstore/delivery-service/fish"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:
-
NameCallback
-
PasswordCallback
In either event, the CallbackHandler must also support the requirements in CallbackHandler Requirements
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 CallbackHandler Requirements 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 non-null Subject corresponding to the
client must be passed as the clientSubject in the getAuthContext call.
A null value may be passed for the properties
argument in all calls made to getAuthContext.
Each ClientAuthContext obtained through getAuthContext must initialize its encapsulated ClientAuthModule objects with requestPolicy and responsePolicy objects (or null values) that are compatible with the requirements and capabilities of the service invocation (at the service). The requirements, preferences, and capabilities of the client may be factored in the context acquisition and may effect the requestPolicy and responsePolicy objects passed to the authentication modules of the context.
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 messageInfo argument used in a call to
secureRequest must have been initialized by the runtime such that its
getRequestMessage will return the SOAP request message being processed
by the runtime.
When a corresponding call is made to
validateResponse, it must be made with the same messageInfo and
clientSubject arguments used in the corresponding call to secureRequest,
and it must have been initialized by the runtime such that its
getResponseMessage method will return the SOAP response message being
processed by the runtime.
MessageInfo Properties
This profile requires that the message processing runtime establish the following key-value pairs within the Map of the MessageInfo passed in the calls to secureRequest and validateResponse.
| key | value |
|---|---|
jakarta.xml.ws.wsdl.service |
The value of the qualified service name, represented as a javax.xml.namespace.QName. specification |
The clientSubject used in the call to
getAuthContext must be used in the call to secureRequest and for any
corresponding calls to validateResponse.
When secureRequest is called on a module that was initialized with a mandatory request policy (as defined by the return value from requestPolicy.isMandatory()), the module must only return AuthStatus.SEND_SUCCESS if it was able to completely satisfy the request policy. If the module was not able to completely satisfy the request policy, it must:
-
Return
AuthStatus.SEND_CONTINUE– If it has established an initial request (available to the runtime by calling messageInfo.getRequestMessage) that must be sent by the runtime for the request to be effectively continued and when additional message exchanges will be required to achieve successful completion of the secureRequest processing. -
Return AuthStatus.FAILURE– If it failed securing the request and only if it established a response message containing a SOAP fault element (available to the runtime by callingmessageInfo.getResponseMessage) that may be returned to the application to indicate that the request failed. -
Throw an
AuthException– If it failed securing the request and did not establishing a failure response message. The runtime may choose to return a response message containing a SOAP fault element, in which case, the runtime must define the content of the message and of the fault, and may do so based on the content of the AuthException.
When secureRequest is called on a module that
was initialized with an optional requestPolicy (that is,
requestPolicy.isMandatory() returns false), the module may attempt to
satisfy the request policy and may return AuthStatus.SEND_SUCCESS
independent of whether the policy was satisfied.
The module should NOT throw an AuthException or return AuthStatus.FAILURE. The module may initiate a security dialog, as described above for AuthStatus.SEND_CONTINUE, but should not do so if the client cannot accommodate the possibility of a failure of an optional security dialog.
When secureRequest is called on a module that was initialized with an undefined request policy (that is, requestPolicy === null), the module must return AuthStatus.SEND_SUCCESS.
validateResponse may be called either prior
to the service invocation to process a response received during the
secureRequest processing (when a multi-message dialog is required to
secure the request), or after the service invocation and during the
process of securing the response generated by the service invocation.
The module implementation is responsible for recording any state and
performing any processing required to differentiate these contexts.
validateResponse After Service Invocation
When validateResponse is called after the service invocation on a module that was initialized with a mandatory response policy (as defined by the return value from responsePolicy.isMandatory()), the module must only return AuthStatus.SUCCESS if it was able to completely satisfy the response policy. If the module was not able to completely satisfy the response policy, it must:
-
Return
AuthStatus.SEND_CONTINUE– If it has established a request (available to the runtime by calling messageInfo.getRequestMessage) that must be sent by the runtime for the response validation to be effectively continued by the client. -
Return
AuthStatus.FAILURE– If response validation failed and only if the module has established a response message containing a SOAP fault element (available to the runtime by callingmessageInfo.getResponseMessage) that may be returned to the application to indicate that the response validation failed. -
Throw an
AuthException– If response validation failed without establishing a failure response message. The runtime may choose to return a response message containing a SOAP fault element, in which case, the runtime must define the content of the message and of the fault, and may do so based on the content of the AuthException.
When validateResponse is called after the service invocation on a module that was initialized with an optional responsePolicy (that is, responsePolicy.isMandatory() returns false), the module should attempt to satisfy the response policy, but it must do so without initiating[1] additional message exchanges or interactions involving the service. Independent of whether the response policy is satisfied, the module may return AuthStatus.SUCCESS. If the module determines that an invalid or incomplete security context was used to secure the response, then the module may return AuthStatus.FAILURE, AuthStatus.SEND_CONTINUE, or throw an AuthException. The runtime must process an AuthException as described above for a response with a mandatory responsePolicy. The runtime must process any return value other than AuthStatus.SUCCESS as it would be processed if it were returned for a response with a mandatory responsePolicy.
When validateResponse is called after the
service invocation on a module that was initialized with an undefined
response policy (that is, responsePolicy == null), the module must
return AuthStatus.SUCCESS.
validateResponse Before Service Invocation
When validateResponse is called before the
service invocation[2], the module must return AuthStatus.SEND_CONTINUE if
the request dialog is to continue. This status value is used to inform
the client runtime that, to successfully complete the request
processing, it must be capable of continuing the message dialog by
processing at least one additional request/response exchange. The module
must have established (in messageInfo) a request message that will cause
the service to continue the request processing. For the request
processing to be successfully completed, the runtime must send the
request message returned by the module.
If the module returns AuthStatus.FAILURE, it
must have established a SOAP message containing a SOAP fault element as
the response in messageInfo and that may be returned to the application
to indicate that the request failed.
If the module throws an AuthException, the runtime may choose to return a response message containing a SOAP fault element, in which case, the runtime must define the content of the message and of the fault, and may do so based on the content of the AuthException.
This section defines the requirements of this profile that must be satisfied by a runtime operating in the server role. A runtime may operate in both the client and server roles.
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[3] component
of the service endpoint URI corresponding to the webservice.
AppContextID ::= hostname blank service-endpoint-uri
For example: "aquarium /petstore/delivery-service/fish"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:
-
CallerPrincipalCallback
-
GroupPrincipalCallback
-
PasswordValidationCallback
The CallbackHandler must also support the
requirements in CallbackHandler Requirements
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 CallbackHandler Requirements 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.
If the runtime is a Jakarta Authorization compatible Jakarta Enterprise Beans or
Jakarta Servlet endpoint container, the properties argument passed in all calls
to getAuthContext must contain the key-value pair shown in the following
table.
| key | value |
|---|---|
jakarta.security.jacc.PolicyContext |
The PolicyContext identifier value that the container must set to satisfy the Jakarta Authorization authorization requirements as described in “Setting the Policy Context” within the Jakarta Authorization specification |
When the runtime is not a Jakarta Authorization compatible
endpoint container, the properties argument used in all calls to
getAuthContext must not include a javax.security.jacc.PolicyContext
key-value pair, and a null value may be passed for the properties
argument.
When a non-null requestPolicy is used to
initialize the authentication modules of a ServerAuthContext, the
requestPolicy 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)
message protection within the SOAP messaging layer is required to
perform the web service invocation corresponding to the MessageInfo used
to acquire the ServerAuthContext. Similarly, the value obtained by
calling isMandatory on a non-null responsePolicy must accurately reflect
whether or not message protection is required (within the SOAP messaging
layer) on the response (if there is one) resulting from the
corresponding web service invocation
Calling getTargetPolicies on the
requestPolicy corresponding to a web service invocation for which a SOAP
layer client identity is to be established as the caller identity must
return an array containing at least one TargetPolicy for which calling
getProtectionPolicy.getID() returns one of the following values:
-
ProtectionPolicy.AUTHENTICATE_SENDER
-
ProtectionPolicy.AUTHENTICATE_CONTENT
When all of the operations of a web service
endpoint require client authentication, each ServerAuthContext acquired
for the endpoint must initialize its contained authentication modules
with a requestPolicy that includes a TargetPolicy as described above and
that mandates client authentication. When client authentication is
required for some, but not all, operations of an endpoint, the
requestPolicy used to initialize the authentication modules of a
ServerAuthContext acquired for the endpoint must include a TargetPolicy
as described above and should only mandate client authentication if
client authentication is required for all of the operations mapped to
the ServerAuthContext. When none of the operations mapped to a
ServerAuthContext require client authentication, the requestPolicy used
to initialize the authentication modules of the ServerAuthContext must
NOT mandate client authentication.
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[4] 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.
The messageInfo argument used in a call to
validateRequest must have been initialized by the runtime such that its
getRequestMessage will return the SOAP request message being processed
by the runtime.
When a corresponding call is made to
secureResponse, it must be made with the same messageInfo and
serviceSubject arguments used in the corresponding call to
validateRequest, and it must have been initialized by the runtime such
that its getResponseMessage method will return the SOAP response message
being processed by the runtime.
MessageInfo Properties
This profile does not define any properties
that must be included in the Map within the MessageInfo passed in calls
to validateRequest and secureResponse.
A new clientSubject must be instantiated and
passed in any calls made to validateRequest.
validateRequest may be called either before
the service invocation (to validate and authorize the request) 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 contexts.
validateRequest Before Service Invocation
When validateRequest is called before the
service invocation on a module initialized with a mandatory request
policy (as defined by the return value from
requestPolicy.isMandatory()), the module must only return
AuthStatus.SUCCESS if it was able to completely satisfy the request
policy. If the satisfied request policy includes a TargetPolicy element
with a ProtectionPolicy of AUTHENTICATE_SOURCE or AUTHENTICATE_CONTENT,
then the module (or its context) must employ the CallbackHandler passed
to it by the runtime to handle a CallerPrincipalCallback using the
clientSubject as argument to the callback. If more than one module of a
context uses the CallbackHandler to handle this callback, the context is
responsible for coordinating the calls such that the appropriate caller
principal value is established.
If the module was not able to completely satisfy the request policy, it must:
-
Return AuthStatus.SEND_CONTINUE – If it has established a response (available to the runtime by calling
messageInfo.getResponseMessage) that must be sent by the runtime for the request validation to be effectively continued by the client. -
Return AuthStatus.SEND_FAILURE – If the request validation failed, and when the module has established a SOAP message containing a fault element (available to the runtime by calling
messageInfo.getResponseMessage) that may be sent by the runtime to inform the client that the request failed. -
Throw an AuthException – If the request validation failed, and when the module has NOT defined a response, to be sent by the runtime. If the runtime chooses to send a response, it must define a SOAP message containing a SOAP fault element, and may use the content of the AuthException to do so.
When validateRequest is called before the
service invocation on a module that was initialized with an optional
request policy (that is, requestPolicy.isMandatory() returns false), the
module should attempt to satisfy the request policy, but it must do so
without initiating[5] additional message exchanges
or interactions involving the client. Independent of whether the request
policy is satisfied, the module may return AuthStatus.SUCCESS. If the
module returns AuthStatus.SUCCESS, and the request policy was satisfied
(and included a TargetPolicy element as described above), then the
module (or its context) must employ the CallerPrincipalCallback as
described above. If the request policy was not satisfied (and included a
TargetPolicy element as described above), and yet the module chooses to
return AuthStatus.SUCCESS, the module (or its context) must use a
CallerPrincipalCallback to establish the container’s representation of
the unauthenticated caller within the clientSubject. If the module
determines that an invalid or incomplete security context was used to
secure the request, then the module may return AuthStatus.SEND_FAILURE,
AuthStatus.SEND_CONTINUE, or throw an AuthException.If the module throws
an AuthException, or returns any value other that AuthStatus.SUCCESS,
the runtime must NOT proceed to the service invocation. The runtime must
process an AuthException as described above for a request with a
mandatory requestPolicy. The runtime must process any return value other
than AuthStatus.SUCCESS as it would be processed if it were returned for
a request with a mandatory requestPolicy.
When validateRequest is called before the
service invocation on a module that was initialized with an undefined
request policy (that is, requestPolicy == null), the module must return
AuthStatus.SUCCESS.
When validateRequest is called after the
service invocation[6], the module must return AuthStatus.SEND_SUCCESS when
the module has successfully secured the application response message and
made it available through messageInfo.getResponseMessage. For the
request to be successfully completed, the runtime must send the response
message returned by the module.
When securing of the application response message has failed, and the response dialog is to be terminated, the module must return AuthStatus.SEND_FAILURE or throw an AuthException.
If the module returns
AuthStatus.SEND_FAILURE, it must have established a SOAP message
containing a SOAP fault element as the response in messageInfo. The
runtime may choose not to send a response message, or to send a
different response message.
When the module throws an AuthException, the runtime may choose not to send a response. If the runtime sends a response, the runtime must define the content of the response.
The module must return
AuthStatus.SEND_CONTINUE if the response dialog is to continue. This
status value is used to inform the calling runtime that, to successfully
complete the response processing, it will need to be capable of
continuing the message dialog by processing at least one additional
request/response exchange (after having sent the response message
returned in messageInfo). The module must have established (in
messageInfo) a response message that will cause the client to continue
the response processing. For the response processing to be successfully
completed, the runtime must send the response message returned by the
module.
When secureResponse is called on a module
that was initialized with an undefined responsePolicy (that is,
responsePolicy == null), the module must return AuthStatus.SEND_SUCCESS.
Otherwise, the return value and AuthException semantics of
secureResponse are as defined in "validateRequest After Service Invocation"
secureResponse processing.