org.forgerock.caf.authentication.api

Interface AsyncServerAuthModule

All Known Implementing Classes:

JwtSessionModule, OpenIdConnectModule

public interface AsyncServerAuthModule

An asynchronous interface counterpart for the ServerAuthModule. Responsible for validating and securing request and response messages.

Implementations of this interface must be thread-safe as instances may be used processes concurrent requests. If the module needs to store any state for a single request it should store the state in the MessageInfoContext so that it can be retrieved later for the in the AsyncServerAuthModule.secureResponse(MessageInfoContext, javax.security.auth.Subject) method.

Since:

2.0.0

See Also:

ServerAuthModule, MessageInfo, Subject

Method Summary

Modifier and Type	Method and Description
Promise<Void,AuthenticationException>	cleanSubject(MessageInfoContext messageInfo, Subject clientSubject) Removes any method specific principals and credentials from the client subject.
String	getModuleId() Gets the ID of the module to be used in creating authentication audit logs to uniquely identify the authentication module and its outcome when processing a request message.
Collection<Class<?>>	getSupportedMessageTypes() Gets the Collection of Class objects of the message types supported by the module.
void	initialize(javax.security.auth.message.MessagePolicy requestPolicy, javax.security.auth.message.MessagePolicy responsePolicy, CallbackHandler handler, Map<String,Object> options) Initialize this module with request and response message policies to enforce, a CallbackHandler, and any module specific configuration properties.
Promise<javax.security.auth.message.AuthStatus,AuthenticationException>	secureResponse(MessageInfoContext messageInfo, Subject serviceSubject) Secures the outgoing response message.
String	toString() A short but useful description of this authentication context.
Promise<javax.security.auth.message.AuthStatus,AuthenticationException>	validateRequest(MessageInfoContext messageInfo, Subject clientSubject, Subject serviceSubject) Validates the incoming request message.

Method Detail

getModuleId

String getModuleId()

Gets the ID of the module to be used in creating authentication audit logs to uniquely identify the authentication module and its outcome when processing a request message.

Returns:

The ID of the module.

initialize

void initialize(javax.security.auth.message.MessagePolicy requestPolicy,
                javax.security.auth.message.MessagePolicy responsePolicy,
                CallbackHandler handler,
                Map<String,Object> options)
         throws AuthenticationException

Initialize this module with request and response message policies to enforce, a CallbackHandler, and any module specific configuration properties.

The request policy and the response policy must not both be null.

Parameters:

requestPolicy - The request policy this module must enforce, or null.

responsePolicy - The response policy this module must enforce, or null.

handler - CallbackHandler used to request information.

options - A Map of module-specific configuration properties.

Throws:

AuthenticationException - when module initialization fails, including for the case where the options argument contains elements that are not supported by the module.

getSupportedMessageTypes

Collection<Class<?>> getSupportedMessageTypes()

Gets the Collection of Class objects of the message types supported by the module.

Returns:

A Collection of Class objects, with at least on element defining the message type(s) supported by the module.

validateRequest

Promise<javax.security.auth.message.AuthStatus,AuthenticationException> validateRequest(MessageInfoContext messageInfo,
                                                                                        Subject clientSubject,
                                                                                        Subject serviceSubject)

Validates the incoming request message.

Parameters:

messageInfo - The message context info for this request.

clientSubject - A Subject that represents the subject of this request.

serviceSubject - A Subject that represents the subject for the server or null. It may be used to secure the message response.

Returns:

A Promise that will be completed, as some point in the future, with either a successful value or a failure value.

A successfully completed Promise will contain an AuthStatus representing the completion status of the message processing. See ServerAuth.validateRequest( javax.security.auth.message.MessageInfo, Subject, Subject) for the allowed AuthStatus values.

A failed completed Promise will contain an AuthenticationException when the message processing failed without establishing a failure response message in the MessageContextInfo.

See Also:

AuthStatus, ServerAuth.validateRequest( javax.security.auth.message.MessageInfo, Subject, Subject)

secureResponse

Promise<javax.security.auth.message.AuthStatus,AuthenticationException> secureResponse(MessageInfoContext messageInfo,
                                                                                       Subject serviceSubject)

Secures the outgoing response message.

Parameters:

messageInfo - The message context info for this request.

serviceSubject - A Subject that represents the subject for the server or null. It may be used to secure the message response.

Returns:

A Promise that will be completed, as some point in the future, with either a successful value or a failure value.

A successfully completed Promise will contain an AuthStatus representing the completion status of the processing. See ServerAuth.secureResponse( javax.security.auth.message.MessageInfo, Subject) for the allowed AuthStatus values. Note AuthStatus.SEND_CONTINUE is not supported by this interface

A failed completed Promise will contain an AuthenticationException when the message processing failed without establishing a failure response message in the MessageContextInfo.

See Also:

AuthStatus, ServerAuth.secureResponse( javax.security.auth.message.MessageInfo, Subject)

cleanSubject

Promise<Void,AuthenticationException> cleanSubject(MessageInfoContext messageInfo,
                                                   Subject clientSubject)

Removes any method specific principals and credentials from the client subject.

Parameters:

messageInfo - The message context info for this request.

clientSubject - A Subject that represents the subject of this request.

Returns:

A Promise that will be completed, as some point in the future, with either a successful value or a failure value. A successfully completed Promise will contain no value and a failed completed Promise will contain an AuthenticationException if an error occurs during the Subject processing.

See Also:

ServerAuth.cleanSubject( javax.security.auth.message.MessageInfo, Subject)

toString

String toString()

A short but useful description of this authentication context. Description should include at least the ID of this module and optionally configuration details.

Overrides:

toString in class Object