Java Platform, Enterprise Edition (Java EE) 8
The Java EE Tutorial
HttpAuthenticationMechanism interface defines an SPI for writing
authentication mechanisms that can be provided with an application and
deployed using CDI. Developers can write their own implementations of
to support specific authentication token types or protocols. There are also several
built-in authentication mechanisms that perform BASIC, FORM, and Custom FORM
The built-in authentication mechanisms are enabled and configured through the use of one of the following annotations:
BasicAuthenticationMechanismDefinition — implements BASIC authentication that conforms to the behavior of the servlet container when BASIC <auth-method> is declared in web.xml.
FormAuthenticationMechanismDefinition — implements FORM authentication that conforms to the behavior of the servlet container when the FORM <auth-method> is declared in web.xml.
CustomFormAuthenticationMechanismDefinition — implements a modified version of FORM authentication in which custom handling replaces the POST to j_security_check.
An implementation of HttpAuthenticationMechanism must be a CDI bean to be
recognized and deployed at runtime, and is assumed to be normal scoped.
During bean discovery, the servlet container looks for a bean that implements
HttpAuthenticationMechanism — there should be only one per application — and,
if found, arranges for it to be deployed to authenticate the application’s callers.
The servlet container leverages JASPIC, the Java Authentication Service
Provider Interface for Containers, to deploy authentication mechanisms.
The container provides a JASPIC Server Auth Module (SAM) that can delegate to an
HttpAuthenticationMechanism, and arranges for that "bridge" SAM to be registered
with the JASPIC
AuthConfigFactory. At runtime, normal JASPIC processing invokes
the bridge SAM, which then delegates to the
perform the authentication and drive any necessary dialog with the caller, or with
third parties involved in the authentication protocol flow.
The HttpAuthenticationMechanism interface defines the following three methods,
which correspond to the three methods defined by the JASPIC ServerAuth interface.
When one of the JASPIC methods is invoked on the bridge SAM, it delegates to the
corresponding method of the
HttpAuthenticationMechanism. Although the method names
are identical, the method signatures are not; the bridge SAM maps back and forth
between the parameters passed to it by the JASPIC framework, and the parameters
expected by an
validateRequest() — validate an incoming request and authenticates the caller.
secureResponse() — (optional if default is sufficient) secure a response message.
cleanSubject() — (optional if default is sufficient) clear the provided Subject of
principals and credentials.
validateRequest() method must be implemented by an
the interface includes default implementations for secureResponse()` and
cleanSubject() that will
often be sufficient.
The following annotations can be used to add additional behaviors to an
AutoApplySession — indicates that the JASPIC
should be enabled such that the the caller’s authenticated identity is
persisted in the caller’s servlet session.
LoginToContinue — mechanism to specify properties for FORM login — login page, error page, etc. The built-in FORM authentication mechanisms use
LoginToContinue to configure the necessary parameters.
RememberMe — specifies that a
RememberMe identity store should be used to
RememberMe functionality for the authentication mechanism.