Package com.sun.enterprise.security.jauth

Interface ServerAuthModule

public interface ServerAuthModule

This interface describes a module that can be configured for a ServerAuthContext. The main purpose of this module is to validate client requests and to secure responses back to the client.

A module implementation must assume it may be shared across different requests from different clients. It is the module implementation's responsibility to properly store and restore any state necessary to associate new requests with previous responses. 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 validateRequest to secureResponse 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	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	secureResponse(AuthParam param, Subject subject, Map sharedState)	Secure the response to the client (sign and encrypt the response, for example).
void	validateRequest(AuthParam param, Subject subject, Map sharedState)	Authenticate a client request.

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.

validateRequest

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

Authenticate a client request.

The AuthParam input parameter encapsulates the client request and server response objects. This ServerAuthModule validates the client request object (decrypts content and verifies a signature, 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 and Principals and credentials validated in the request.

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

Throws:

PendingException - if the operation is pending (for example, when a module issues a challenge). The module must have updated the response object in the AuthParam.

FailureException - if the authentication failed. The module must have updated the response object in the AuthParam.

AuthException - if the operation failed.

secureResponse

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

Secure the response to the client (sign and encrypt the response, 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 credentials needed to secure the response, or null. If null, the module may use a CallbackHandler to obtain the necessary information.

sharedState - a Map for modules to save state across a sequence of calls from validateRequest to secureResponse 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 validateRequest.

Parameters:

subject - the Subject instance to be disposed.

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

Throws:

AuthException - if the operation failed.