Package com.sun.enterprise.security.jauth

Interface ClientAuthContext

public interface ClientAuthContext

This ClientAuthContext class manages AuthModules that may be used to secure requests made as a client. A caller typically uses this class in the following manner:

1. Retrieve an instance of this class via AuthConfig.getClientAuthContext.
2. Invoke secureRequest.
   ClientAuthContext implementation invokes configured plug-in modules. Modules attach credentials to initial request object (for example, a username and password), and/or secure the request (for example, sign and encrypt the request).
3. Issue request.
4. Receive response and pass it to validateResponse.
   ClientAuthContext implementation invokes configured plug-in modules. Modules verify or decrypt response as necessary.
5. The disposeSubject method may be invoked if necessary to clean up any authentication state in the Subject.

An instance may reuse module instances it previously created. As a result a single module instance may be used to issue different requests as different clients. It is the module implementation's responsibility to properly store and restore any necessary state. A module that does not need to do so may remain completely stateless.

Instances of this class have custom logic to determine what modules to invoke, and in what order. In addition, this custom logic may control whether subsequent modules are invoked based on the success or failure of previously invoked modules.

The caller is responsible for passing in a state Map that can be used by underlying modules to save state across a sequence of calls from secureRequest to validateResponse to disposeSubject. The same Map instance must be passed to all methods in the call sequence. Furthermore, each call sequence should be passed its own unique shared state Map instance.

Version:

%I%, %G%

See Also:

AuthConfig, SOAPAuthParam

Method Summary

Modifier and Type	Method	Description
void	disposeSubject(Subject subject, Map sharedState)	Dispose of the Subject (remove Principals or credentials from the Subject object that were stored during validateResponse).
void	secureRequest(AuthParam param, Subject subject, Map sharedState)	Secure a request message.
void	validateResponse(AuthParam param, Subject subject, Map sharedState)	Validate received response.

Method Detail

secureRequest

void secureRequest(AuthParam param,
                   Subject subject,
                   Map sharedState)
            throws AuthException

Secure a request message.

Attach authentication credentials to an initial request, sign/encrypt a request, or respond to a server challenge, for example.

This method invokes configured modules to secure the request.

Parameters:

param - an authentication parameter that encapsulates the client request and server response objects.

subject - the subject may be used by configured modules to obtain Principals and credentials necessary to secure the request, or null. If null, the module may use a CallbackHandler to obtain any information necessary to secure the request.

sharedState - a Map for modules to save state across a sequence of calls from secureRequest to validateResponse to disposeSubject.

Throws:

AuthException - if the operation failed.

validateResponse

void validateResponse(AuthParam param,
                      Subject subject,
                      Map sharedState)
               throws AuthException

Validate received response.

Validation may include verifying signature in response, or decrypting response contents, for example.

This method invokes configured modules to validate the response.

Parameters:

param - an authentication parameter that encapsulates the client request and server response objects.

subject - the subject may be used by configured modules to store the Principals and credentials related to the identity validated in the response.

sharedState - a Map for modules to save state across a sequence of calls from secureRequest to validateResponse to disposeSubject.

Throws:

AuthException - if the operation failed.

disposeSubject

void disposeSubject(Subject subject,
                    Map sharedState)
             throws AuthException

Dispose of the Subject (remove Principals or credentials from the Subject object that were stored during validateResponse).

This method invokes configured modules to dispose the Subject.

Parameters:

subject - the subject to be disposed.

sharedState - a Map for modules to save state across a sequence of calls from secureRequest to validateResponse to disposeSubject.

Throws:

AuthException - if the operation failed.