[[a502]]
== SOAP Profile 

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.

[[a505]]
=== Message Layer Identifier

The message layer value used to select the
`AuthConfigProvider` and ServerAuthConfig objects for this profile must be
“SOAP”.

[[a507]]
=== Application Context Identifier

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 link:jaspic.html#a537[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
<<a603>>.

[[a510]]
=== Message Requirements

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.

=== Module Requirements

The getSupportedMessageTypes method of all
authentication modules integrated for use with this profile must include
jakarta.xml.soap.SOAPMessage.class in its return value.

[[a514]]
=== CallbackHandler Requirements

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.

=== AuthConfigProvider Requirements

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 <<a505>> and <<a507>> 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.

[[a526]]
=== Authentication Context Requirements

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 <<a531>>.

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.

[[a531]]
==== Authentication Context Identifiers

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).

==== MessagePolicy Requirements

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.

=== Requirements for Client Runtimes

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.

[[a537]]
==== Client-Side Application Context Identifier

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-reference
```

The 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.

[[a549]]
==== CallbackHandler Requirements

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 <<a514>>

==== AuthConfigProvider 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 <<a549>> for a client runtime.

[[a556]]
==== Authentication Context Requirements

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

===== getAuthContext Subject

A non-null Subject corresponding to the
client must be passed as the clientSubject in the `getAuthContext`  call.

===== Module Initialization Properties

A null value may be passed for the properties
argument in all calls made to `getAuthContext`.

===== MessagePolicy Requirements

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.

[[a564]]
==== Message Processing Requirements

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`.

[[a568]]
===== MessageInfo Requirements

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.


[caption="Table {doc-part}-{counter:table-number} ", title="Client MessageInfo Map Properties"]
[.center, width=95%]
[%header,cols="30%,70%"] 
|===
a| [.small]#+++<font size=".8em">key</font>+++#
a| [.small]#+++<font size=".8em">value</font>+++#

a| [.small]#+++<font size=".8em">jakarta.xml.ws.wsdl.service</font>+++#
| The value of the qualified service name,
represented as a javax.xml.namespace.QName. 
specification
|===


===== Subject Requirements

The `clientSubject` used in the call to
`getAuthContext` must be used in the call to `secureRequest` and for any
corresponding calls to `validateResponse`.

[[a580]]
===== secureRequest Processing

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 calling
`messageInfo.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 Processing

`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.

[[a590]]
*_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
calling `messageInfo.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 initiatingfootnote:[The module may continue, or refresh an authentication dialog that has already been initiated (perhaps by the client) in the request, but it must not start an authentication dialog for a request which has not yet been associated with authentication information (as understood by the module).] 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 invocationfootnote:[Occurs when the module is challenged by the server during secureRequest processing.], 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.

=== Requirements for Server Runtimes

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.

[[a603]]
==== Server-Side Application Context Identifier

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 pathfootnote:[For an http or https schema, the path must be the corresponding component of the "generic URI" syntax (that is, <scheme>://<authority><path>?<query>) described in section 3. of RFC 2396 "Uniform Resource Identifiers (URI): Generic Syntax". If the service is implemented as a Servlet, the path must begin with the context-path.] 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.

[[a608]]
==== CallbackHandler Requirements

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

* CallerPrincipalCallback
* GroupPrincipalCallback
* PasswordValidationCallback

The `CallbackHandler` must also support the
requirements in <<a514>>

==== AuthConfigProvider 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 <<a608>> for a server runtime.

[[a616]]
==== Authentication Context Requirements

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

[[a618]]
===== Module Initialization Properties

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.

[caption="Table {doc-part}-{counter:table-number} ", title="Jakarta Authorization Compatible Module Initialization Properties"]
[.center, width=95%]
[%header,cols="30%,70%"] 
|===
a| [.small]#+++<font size=".8em">key</font>+++#
a| [.small]#+++<font size=".8em">value</font>+++#

a| [.small]#+++<font size=".8em">jakarta.security.jacc.PolicyContext</font>+++#
| 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 `jakarta.security.jacc.PolicyContext`
key-value pair, and a null value may be passed for the `properties`
argument.

[[a626]]
===== MessagePolicy Requirements

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.

[[a632]]
==== Message Processing Requirements

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 processingfootnote:[This authorization processing would NOT be expected to include the enforcement of Servlet Auth-Constraints since they are defined at url-pattern granularity.] 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.

===== MessageInfo Requirements

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.

[[a642]]
*_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`.

===== Subject Requirements

A new `clientSubject` must be instantiated and
passed in any calls made to `validateRequest`.

===== validateRequest Processing

`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.

[[a648]]
*_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 initiatingfootnote:[The module may continue, or refresh an authentication dialog that has already been initiated (perhaps by the client) in the request, but it must not start an authentication dialog for a request which has not yet been associated with authentication information (as understood by the module).] 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.


[[a656]]*_validateRequest After Service Invocation_*

When validateRequest is called after the
service invocationfootnote:[Occurs when the module is challenged by the client during `secureResponse` processing.], 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.

[[a662]]
===== secureResponse Processing

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 <<a656, "validateRequest After Service Invocation">>