com.sun.enterprise.security.jauth

Interface ServerAuthContext

public interface ServerAuthContext

This ServerAuthContext class manages AuthModules that may be used to validate client requests. A caller typically uses this class in the following manner:

1. Retrieve an instance of this class via AuthConfig.getServerAuthContext.
2. Receive initial client request and pass it to validateRequest.
   Configured plug-in modules validate credentials present in request (for example, decrypt and verify a signature). If credentials valid and sufficient, return. Otherwise throw an AuthException.
3. Authentication complete.
   Perform authorization check on authenticated identity and, if successful, dispatch to requested service application.
4. Service application finished.
5. Invoke secureResponse.
   Configured modules secure response (sign and encrypt it, for example).
6. Send final response to client.
7. The disposeSubject method may be invoked it necessary to clean up any authentication state in the Subject.

An instance may reuse module instances it previous created. As a result a single module instance may be used to process 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.

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 validateRequest to secureResponse 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 and Description
void	disposeSubject(Subject subject, Map sharedState) Dispose of the Subject (remove Principals or credentials from the Subject object that were stored during validateRequest).
boolean	managesSessions(Map sharedState) modules manage sessions used by calling container to determine if it should delegate session management (including the mapping of requests to authentication results established from previous requests) to the underlying authentication modules of the context.
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

validateRequest

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

Authenticate a client request. (decrypt the message and verify a signature, for exmaple).

This method invokes configured modules to authenticate 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 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 input parameter.

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

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

This method invokes configured modules to secure 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 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).

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 validateRequest to secureResponse to disposeSubject.

Throws:

AuthException - if the operation failed.

managesSessions

boolean managesSessions(Map sharedState)
                 throws AuthException

modules manage sessions used by calling container to determine if it should delegate session management (including the mapping of requests to authentication results established from previous requests) to the underlying authentication modules of the context.

When this method returns true, the container should call validate on every request, and as such may depend on the invoked modules to determine when a request pertains to an existing authentication session.

When this method returns false, the container may employ is own session management functionality, and may use this functionality to recognize when an exiting request is to be interpretted in the context of an existing authentication session.

Returns:

true if the context should be allowed to manage sessions, and false if session management (if it is to occur) must be performed by the container.

Throws:

AuthException - if the operation failed.