Package: AuthenticationStatus

AuthenticationStatus

name	instruction	branch	complexity	line	method
static {...}	M: 27 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 5 C: 0 0%	M: 1 C: 0 0%

Coverage

1: /*
2: * Copyright (c) 2015, 2020 Oracle and/or its affiliates. All rights reserved.
3: *
4: * This program and the accompanying materials are made available under the
5: * terms of the Eclipse Public License v. 2.0, which is available at
6: * http://www.eclipse.org/legal/epl-2.0.
7: *
8: * This Source Code may also be made available under the following Secondary
9: * Licenses when the conditions for such availability set forth in the
10: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
11: * version 2 with the GNU Classpath Exception, which is available at
12: * https://www.gnu.org/software/classpath/license.html.
13: *
14: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
15: */
16:
17: package jakarta.security.enterprise;
18:
19: import jakarta.servlet.http.HttpServletRequest;
20:
21: import jakarta.security.enterprise.authentication.mechanism.http.HttpAuthenticationMechanism;
22:
23: /**
24: * The AuthenticationStatus is used as a return value by primarily
25: * the {@link HttpAuthenticationMechanism} to indicate the result (status)
26: * of the authentication process.
27: *
28: * <p>
29: * For the result from {@link HttpAuthenticationMechanism#validateRequest(jakarta.servlet.http.HttpServletRequest, jakarta.servlet.http.HttpServletResponse, jakarta.security.enterprise.authentication.mechanism.http.HttpMessageContext)}
30: * an AuthenticationStatus must be transformed by the Jakarta EE server into the corresponding Jakarta Authentication <code>AuthStatus</code>
31: * according to the following rules:
32: *
33: * <ul>
34: * <li> AuthenticationStatus.NOT_DONE to AuthStatus.SUCCESS </li>
35: * <li> AuthenticationStatus.SEND_CONTINUE to AuthStatus.SEND_CONTINUE </li>
36: * <li> AuthenticationStatus.SUCCESS to AuthStatus.SUCCESS </li>
37: * <li> AuthenticationStatus.SEND_FAILURE to AuthStatus.SEND_FAILURE </li>
38: * </ul>
39: *
40: * <p>
41: * After the transformation as outlined above the transformed result has to be processed by the Jakarta EE server as
42: * specified by the Servlet Container Profile of the Jakarta Authentication spec.
43: *
44: * <p>
45: * <b>Implementation note:</b> while the Jakarta Authentication Servlet Container Profile is the authoritative
46: * source on how to process the <code>AuthStatus.SUCCESS</code> result and this specification puts no constraints
47: * of any kind on that, the expectation is that Jakarta EE servers in practice will mainly look at the
48: * result being <code>AuthStatus.SUCCESS</code> or not <code>AuthStatus.SUCCESS</code>. Simply said, if the result is
49: * <code>AuthStatus.SUCCESS</code> the authenticated identity (if any) must be set (established) for the current HTTP request,
50: * otherwise not.
51: *
52: * <p>
53: * The return value of {@link SecurityContext#authenticate(jakarta.servlet.http.HttpServletRequest, jakarta.servlet.http.HttpServletResponse, jakarta.security.enterprise.authentication.mechanism.http.AuthenticationParameters)}
54: * , which is also of type AuthenticationStatus, strongly relates to the outcome of the <code>HttpAuthenticationMechanism#validateRequest</code>
55: * method as described above, but must be transformed by the Jakarta EE server from the corresponding outcome of the
56: * {@link HttpServletRequest#authenticate(jakarta.servlet.http.HttpServletResponse)} call as follows:
57: *
58: * <ul>
59: * <li> <code>true</code> to <code>AuthenticationStatus.SUCCESS</code> </li>
60: * <li> <code>false</code> to <code>[last status]</code> (see below) </li>
61: * <li> <code>ServletException</code> or <code>IOException</code> to <code>AuthenticationStatus.SEND_FAILURE</code> </li>
62: * </ul>
63: *
64: * <p>
65: * When an <code>HttpAuthenticationMechanism</code> was used <code>[last status]</code> must be
66: * the value returned by <code>HttpAuthenticationMechanism#validateRequest</code>.
67: *
68: * <p>
69: * When a Jakarta Authentication ServerAuthModule (SAM) was used and an <code>HttpAuthenticationMechanism</code>
70: * was <em>not</em> used Jakarta EE servers are encouraged, but not required, to set <code>[last status]</code>
71: * to the value returned by <code>ServerAuthModule#validateRequest</code> transformed as follows:
72: *
73: * <ul>
74: * <li> AuthStatus.SEND_CONTINUE to AuthenticationStatus.SEND_CONTINUE </li>
75: * <li> AuthStatus.SUCCESS to AuthenticationStatus.SUCCESS </li>
76: * <li> AuthStatus.SEND_FAILURE to AuthenticationStatus.SEND_FAILURE </li>
77: * <li> (all other outcomes) to AuthenticationStatus.NOT_DONE </li>
78: * </ul>
79: *
80: * <p>
81: * When a Jakarta EE Server proprietary identity store equivalent was used and an
82: * <code>HttpAuthenticationMechanism</code> was <em>not</em> used
83: * Jakarta EE servers are encouraged, but not required, to set <code>[last status]</code> to a value
84: * that logically corresponds to the description of each enum constant of AuthenticationStatus. This outcome
85: * should never be depended on by application code as being portable.
86: *
87: * <p>
88: * Application code calling <code>SecurityContext#authenticate</code> is expected to act on all possible
89: * values of AuthenticationStatus.
90: *
91: */
92: public enum AuthenticationStatus {
93:
94: /**
95: * The authentication mechanism was called, but decided not to authenticate.
96: * This status would be typically returned in pre-emptive security; the authentication
97: * mechanism is called, but authentication is optional and would only take place when for
98: * instance a specific request header is present.
99: */
100: NOT_DONE,
101:
102: /**
103: * The authentication mechanism was called and a multi-step authentication dialog with the caller
104: * has been started (for instance, the caller has been redirected to a login page). Simply said
105: * authentication is "in progress". Calling application code (if any) should not write to the response
106: * when this status is received.
107: */
108: SEND_CONTINUE,
109:
110: /**
111: * The authentication mechanism was called and the caller was successfully authenticated. After the
112: * Jakarta EE server has processed this outcome, the caller principal is available.
113: */
114: SUCCESS,
115:
116: /**
117: * The authentication mechanism was called but the caller was <em>not</em> successfully authenticated and
118: * therefore the caller principal will not be made available.
119: * <p>
120: * Note that this status should be used to indicate a logical problem (such as a credential not matching or a caller
121: * ID that can not be found). Exceptions should be used for system level problems (such as a database connection timing out).
122: */
123: SEND_FAILURE
124: }