Package jakarta.security.enterprise.authentication.mechanism.http

Interface HttpAuthenticationMechanism

  • All Known Implementing Classes:
    HttpAuthenticationMechanismWrapper
    public interface HttpAuthenticationMechanism
    HttpAuthenticationMechanism is a mechanism for obtaining a caller's credentials in some way, using the HTTP protocol where necessary.

    This is used to help in securing Jakarta Servlet endpoints, including endpoints that may be build on top of Jakarta Servlets like Jakarta RESTful Web Services endpoints and Jakarta Faces views. It specifically is not used for endpoints such as remote Jakarta Enterprise Beans or (Jakarta Messaging) message driven beans.

    A HttpAuthenticationMechanism is essentially a Jakarta Servlet specific and CDI enabled version of the ServerAuthModule that adheres to the Servlet Container Profile. See the Jakarta Authentication spec for further details on this.

    Implementations of this class can notify the Jakarta Servlet container about a successful authentication by using the HttpMessageContext.notifyContainerAboutLogin(java.security.Principal, java.util.Set) method.

    Implementations are expected and encouraged to delegate the actual credential validation and/or retrieval of the caller name with optional groups to an IdentityStore. This is however not required and implementations can either do the validation checks for authentication completely autonomously, or delegate only certain aspects of the process to the store (e.g. use the store only for retrieving the groups an authenticated user is in).

    • Method Detail

      • validateRequest

        AuthenticationStatus validateRequest​(HttpServletRequest request,
                                     HttpServletResponse response,
                                     HttpMessageContext httpMessageContext)
                              throws AuthenticationException
        Authenticate an HTTP request.

        This method is called in response to an HTTP client request for a resource, and is always invoked before any Filter or HttpServlet. Additionally this method is called in response to HttpServletRequest.authenticate(HttpServletResponse)

        Note that by default this method is always called for every request, independent of whether the request is to a protected or non-protected resource, or whether a caller was successfully authenticated before within the same HTTP session or not.

        A CDI/Interceptor spec interceptor can be used to prevent calls to this method if needed. See AutoApplySession and RememberMe for two examples.

        Parameters:
        request - contains the request the client has made
        response - contains the response that will be send to the client
        httpMessageContext - context for interacting with the container
        Returns:
        the completion status of the processing performed by this method
        Throws:
        AuthenticationException - when the processing failed

      • secureResponse

        default AuthenticationStatus secureResponse​(HttpServletRequest request,
                                            HttpServletResponse response,
                                            HttpMessageContext httpMessageContext)
                                     throws AuthenticationException
        Secure the response, optionally.

        This method is called to allow for any post processing to be done on the request, and is always invoked after any Filter or HttpServlet.

        Note that this method is only called when a (Servlet) resource has indeed been invoked, i.e. if a previous call to validateRequest that was invoked before any Filter or HttpServlet returned SUCCESS.

        Parameters:
        request - contains the request the client has made
        response - contains the response that will be send to the client
        httpMessageContext - context for interacting with the container
        Returns:
        the completion status of the processing performed by this method
        Throws:
        AuthenticationException - when the processing failed

      • cleanSubject

        default void cleanSubject​(HttpServletRequest request,
                          HttpServletResponse response,
                          HttpMessageContext httpMessageContext)
        Remove mechanism specific principals and credentials from the subject and any other state the mechanism might have used.

        This method is called in response to HttpServletRequest.logout() and gives the authentication mechanism the option to remove any state associated with an earlier established authenticated identity. For example, an authentication mechanism that stores state within a cookie can send remove that cookie here.

        Parameters:
        request - contains the request the client has made
        response - contains the response that will be send to the client
        httpMessageContext - context for interacting with the container