com.sun.enterprise.security.jauth

Interface ClientAuthModule

public interface ClientAuthModule

This interface describes a module that can be configured for a ClientAuthContext. The main purpose of this module is to secure requests and to validate received responses.

A module implementation must assume it may be used to issue different requests as different clients. It is the module implementation's responsibility to properly store and restore any state as necessary. A module that does not need to do so may remain completely stateless.

Modules are passed a shared state Map that can be used to save state across a sequence of calls from secureRequest to validateResponse to disposeSubject. The same Map instance is guaranteed to be passed to all methods in the call sequence. Furthermore, it should be assumed that each call sequence is passed its own unique shared state Map instance.

Version:

%I%, %G%

Method Summary

Modifier and Type	Method and Description
void	disposeSubject(Subject subject, Map sharedState) Dispose of the Subject.
void	initialize(AuthPolicy requestPolicy, AuthPolicy responsePolicy, CallbackHandler handler, Map options) Initialize this module with a policy to enforce, a CallbackHandler, and administrative options.
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

initialize

void initialize(AuthPolicy requestPolicy,
                AuthPolicy responsePolicy,
                CallbackHandler handler,
                Map options)

Initialize this module with a policy to enforce, a CallbackHandler, and administrative options.

Either the the request policy or the response policy (or both) must be non-null.

Parameters:

requestPolicy - the request policy this module is to enforce, which may be null.

responsePolicy - the response policy this module is to enforce, which may be null.

handler - CallbackHandler used to request information from the caller.

options - administrative options.

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.

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.

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.

Parameters:

subject - Subject instance 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.