Package 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 secureResponse(MessageInfoContext, javax.security.auth.Subject) method.

    Since:
    2.0.0
    See Also:
    ServerAuthModule, MessageInfo, Subject

    • 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