Enum AuthenticationStatus



  • public enum AuthenticationStatus
    extends java.lang.Enum<AuthenticationStatus>
    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.

    • Enum Constant Summary

      Enum Constants 
      Enum Constant Description
      NOT_DONE
      The authentication mechanism was called, but decided not to authenticate.
      SEND_CONTINUE
      The authentication mechanism was called and a multi-step authentication dialog with the caller has been started (for instance, the caller has been redirected to a login page).
      SEND_FAILURE
      The authentication mechanism was called but the caller was not successfully authenticated and therefor the caller principal will not be made available.
      SUCCESS
      The authentication mechanism was called and the caller was successfully authenticated.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static AuthenticationStatus valueOf​(java.lang.String name)
      Returns the enum constant of this type with the specified name.
      static AuthenticationStatus[] values​()
      Returns an array containing the constants of this enum type, in the order they are declared.
      • Methods inherited from class java.lang.Enum

        clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
    • Enum Constant Detail

      • NOT_DONE

        public static final AuthenticationStatus NOT_DONE
        The authentication mechanism was called, but decided not to authenticate. This status would be typically returned in pre-emptive security; the authentication mechanism is called, but authentication is optional and would only take place when for instance a specific request header is present.
      • SEND_CONTINUE

        public static final AuthenticationStatus SEND_CONTINUE
        The authentication mechanism was called and a multi-step authentication dialog with the caller has been started (for instance, the caller has been redirected to a login page). Simply said authentication is "in progress". Calling application code (if any) should not write to the response when this status is received.
      • SUCCESS

        public static final AuthenticationStatus SUCCESS
        The authentication mechanism was called and the caller was successfully authenticated. After the Java EE server has processed this outcome, the caller principal is available.
      • SEND_FAILURE

        public static final AuthenticationStatus SEND_FAILURE
        The authentication mechanism was called but the caller was not successfully authenticated and therefor the caller principal will not be made available.

        Note that this status should be used to indicate a logical problem (such as a credential not matching or a caller ID that can not be found). Exceptions should be used for system level problems (such as a database connection timing out).

    • Method Detail

      • values

        public static AuthenticationStatus[] values​()
        Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
        for (AuthenticationStatus c : AuthenticationStatus.values())
            System.out.println(c);
        
        Returns:
        an array containing the constants of this enum type, in the order they are declared
      • valueOf

        public static AuthenticationStatus valueOf​(java.lang.String name)
        Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
        Parameters:
        name - the name of the enum constant to be returned.
        Returns:
        the enum constant with the specified name
        Throws:
        java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
        java.lang.NullPointerException - if the argument is null