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).
Modifier and Type | Method and Description |
---|---|
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.
|
default AuthenticationStatus |
secureResponse(HttpServletRequest request,
HttpServletResponse response,
HttpMessageContext httpMessageContext)
Secure the response, optionally.
|
AuthenticationStatus |
validateRequest(HttpServletRequest request,
HttpServletResponse response,
HttpMessageContext httpMessageContext)
Authenticate an HTTP request.
|
AuthenticationStatus validateRequest(HttpServletRequest request, HttpServletResponse response, HttpMessageContext httpMessageContext) throws AuthenticationException
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.
request
- contains the request the client has maderesponse
- contains the response that will be send to the clienthttpMessageContext
- context for interacting with the containerAuthenticationException
- when the processing faileddefault AuthenticationStatus secureResponse(HttpServletRequest request, HttpServletResponse response, HttpMessageContext httpMessageContext) throws AuthenticationException
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.
request
- contains the request the client has maderesponse
- contains the response that will be send to the clienthttpMessageContext
- context for interacting with the containerAuthenticationException
- when the processing faileddefault void cleanSubject(HttpServletRequest request, HttpServletResponse response, HttpMessageContext httpMessageContext)
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.
request
- contains the request the client has maderesponse
- contains the response that will be send to the clienthttpMessageContext
- context for interacting with the containerCopyright © 2019 Eclipse Foundation.
Use is subject to license terms.