Jakarta EE 11.0.0 · jakarta.security.enterprise.authentication.mechanism.http.HttpAuthenticationMechanismHandler

HttpAuthenticationMechanismHandler is a mechanism for obtaining a caller's credentials in some way, using the HTTP protocol where necessary, by consulting a set of one or more HttpAuthenticationMechanisms.

This is a special variant of an HttpAuthenticationMechanism intended for coordination between multiple HttpAuthenticationMechanisms. Implementations are therefore expected and encouraged to delegate actually obtaining the caller's credential to an actual HttpAuthenticationMechanism. This is however not required and implementations can do as they choose.

Implementations of Jakarta Security must supply a default implementation of the HttpAuthenticationMechanismHandler. This implementation must be ApplicationScoped and this implementation must behave as described below:

Before servicing any calls as defined by this interface, the implementation must (implicitly) check if there is more than one enabled bean of type HttpAuthenticationMechanism available, irrespective of any qualifiers.
If there is more than one enabled bean of type HttpAuthenticationMechanism available, the implementation must apply the ambiguous dependency resolution rules to this set of beans. For instance by using jakarta.enterprise.inject.spi.BeanContainer#resolve(java.util.Set).
If the ambiguous dependency resolution rules fail, an AmbiguousResolutionException must be thrown (or the one thrown by jakarta.enterprise.inject.spi.BeanContainer#resolve(java.util.Set) propagated).
If the ambiguous dependency resolution rules succeed, the implementation must remember the one resulting bean.
When servicing any calls as defined by this interface, the implementation must call the method on the remembered HttpAuthenticationMechanism bean with the same name and arguments, and where applicable return the result from that call.

Applications do not need to supply an HttpAuthenticationMechanismHandler unless application-specific behavior is desired.

Method Summary

Modifier and Type	Method and Description
public default void	cleanSubject(HttpServletRequest contains the request the client has made request, HttpServletResponse contains the response that will be send to the client response, HttpMessageContext context for interacting with the container httpMessageContext) Remove mechanism specific principals and credentials from the subject and any other state the mechanism might have used.
public default AuthenticationStatus	Returns: the completion status of the processing performed by this method secureResponse(HttpServletRequest contains the request the client has made request, HttpServletResponse contains the response that will be send to the client response, HttpMessageContext context for interacting with the container httpMessageContext) Secure the response, optionally.
public AuthenticationStatus	Returns: the completion status of the processing performed by this method validateRequest(HttpServletRequest contains the request the client has made request, HttpServletResponse contains the response that will be send to the client response, HttpMessageContext context for interacting with the container httpMessageContext) Authenticate an HTTP request.

Method Detail

cleanSubject back to summary

cleanSubject	back to summary
public 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:HttpServletRequest contains the request the client has made response:HttpServletResponse contains the response that will be send to the client httpMessageContext:HttpMessageContext context for interacting with the container

public 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:HttpServletRequest: contains the request the client has made
response:HttpServletResponse: contains the response that will be send to the client
httpMessageContext:HttpMessageContext: context for interacting with the container

secureResponse back to summary

secureResponse	back to summary
public 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:HttpServletRequest contains the request the client has made response:HttpServletResponse contains the response that will be send to the client httpMessageContext:HttpMessageContext context for interacting with the container Returns:AuthenticationStatus the completion status of the processing performed by this method Exceptions AuthenticationException: when the processing failed

public 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:HttpServletRequest: contains the request the client has made
response:HttpServletResponse: contains the response that will be send to the client
httpMessageContext:HttpMessageContext: context for interacting with the container

Returns:AuthenticationStatus

the completion status of the processing performed by this method

Exceptions

AuthenticationException:: when the processing failed

validateRequest back to summary

validateRequest	back to summary
public 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:HttpServletRequest contains the request the client has made response:HttpServletResponse contains the response that will be send to the client httpMessageContext:HttpMessageContext context for interacting with the container Returns:AuthenticationStatus the completion status of the processing performed by this method Exceptions AuthenticationException: when the processing failed

public 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:HttpServletRequest: contains the request the client has made
response:HttpServletResponse: contains the response that will be send to the client
httpMessageContext:HttpMessageContext: context for interacting with the container

Returns:AuthenticationStatus

the completion status of the processing performed by this method

Exceptions

AuthenticationException:: when the processing failed

public Interface HttpAuthenticationMechanismHandler

Method Summary

Method Detail