The AuthenticationStatus is used as a return value by primarily
the
HttpAuthenticationMechanism to indicate the result (status)
of the authentication process.
For the result from
HttpAuthenticationMechanism#validateRequest(javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse,javax.security.enterprise.authentication.mechanism.http.HttpMessageContext)
an AuthenticationStatus must be transformed by the Java EE server into the corresponding JASPIC (JSR 196) AuthStatus
according to the following rules:
- AuthenticationStatus.NOT_DONE to AuthStatus.SUCCESS
- AuthenticationStatus.SEND_CONTINUE to AuthStatus.SEND_CONTINUE
- AuthenticationStatus.SUCCESS to AuthStatus.SUCCESS
- AuthenticationStatus.SEND_FAILURE to AuthStatus.SEND_FAILURE
After the transformation as outlined above the transformed result has to be processed by the Java EE server as
specified by the Servlet Container Profile of the JASPIC 1.1 spec (chapter 3).
Implementation note: while the JASPIC Servlet Container Profile is the authoritative
source on how to process the AuthStatus.SUCCESS
result and this specification puts no constraints
of any kind on that, the expectation is that Java EE servers in practice will mainly look at the
result being AuthStatus.SUCCESS
or not AuthStatus.SUCCESS
. Simply said, if the result is
AuthStatus.SUCCESS
the authenticated identity (if any) must be set (established) for the current HTTP request,
otherwise not.
The return value of
SecurityContext#authenticate(javax.servlet.http.HttpServletRequest,javax.servlet.http.HttpServletResponse,javax.security.enterprise.authentication.mechanism.http.AuthenticationParameters), which is also of type AuthenticationStatus, strongly relates to the outcome of the HttpAuthenticationMechanism#validateRequest
method as described above, but must be transformed by the Java EE server from the corresponding outcome of the
HttpServletRequest#authenticate(javax.servlet.http.HttpServletResponse) call as follows:
-
true
to AuthenticationStatus.SUCCESS
-
false
to [last status]
(see below)
-
ServletException
or IOException
to AuthenticationStatus.SEND_FAILURE
When an HttpAuthenticationMechanism
was used [last status]
must be
the value returned by HttpAuthenticationMechanism#validateRequest
.
When a JASPIC ServerAuthModule (SAM) was used and an HttpAuthenticationMechanism
was not used
Java EE servers are encouraged, but not required, to set [last status]
to the value returned by
ServerAuthModule#validateRequest
transformed as follows:
- AuthStatus.SEND_CONTINUE to AuthenticationStatus.SEND_CONTINUE
- AuthStatus.SUCCESS to AuthenticationStatus.SUCCESS
- AuthStatus.SEND_FAILURE to AuthenticationStatus.SEND_FAILURE
- (all other outcomes) to AuthenticationStatus.NOT_DONE
When a Java EE Server proprietary identity store equivalent was used and an
HttpAuthenticationMechanism
was not used
Java EE servers are encouraged, but not required, to set [last status]
to a value
that logically corresponds to the description of each enum constant of AuthenticationStatus. This outcome
should never be depended on by application code as being portable.
Application code calling SecurityContext#authenticate
is expected to act on all possible
values of AuthenticationStatus.