Package: HttpAuthenticationMechanismHandler

HttpAuthenticationMechanismHandler

name	instruction	branch	complexity	line	method
cleanSubject(HttpServletRequest, HttpServletResponse, HttpMessageContext)	M: 3 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 2 C: 0 0%	M: 1 C: 0 0%
secureResponse(HttpServletRequest, HttpServletResponse, HttpMessageContext)	M: 2 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%

Coverage

1: /*
2: * Copyright (c) 2024 Contributors to Eclipse Foundation.
3: * Copyright (c) 2015, 2020 Oracle and/or its affiliates. All rights reserved.
4: *
5: * This program and the accompanying materials are made available under the
6: * terms of the Eclipse Public License v. 2.0, which is available at
7: * http://www.eclipse.org/legal/epl-2.0.
8: *
9: * This Source Code may also be made available under the following Secondary
10: * Licenses when the conditions for such availability set forth in the
11: * Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
12: * version 2 with the GNU Classpath Exception, which is available at
13: * https://www.gnu.org/software/classpath/license.html.
14: *
15: * SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
16: */
17:
18: package jakarta.security.enterprise.authentication.mechanism.http;
19:
20: import static jakarta.security.enterprise.AuthenticationStatus.SUCCESS;
21:
22: import jakarta.enterprise.context.ApplicationScoped;
23: import jakarta.enterprise.inject.AmbiguousResolutionException;
24: import jakarta.enterprise.inject.spi.Bean;
25: import jakarta.security.enterprise.AuthenticationException;
26: import jakarta.security.enterprise.AuthenticationStatus;
27: import jakarta.servlet.Filter;
28: import jakarta.servlet.http.HttpServlet;
29: import jakarta.servlet.http.HttpServletRequest;
30: import jakarta.servlet.http.HttpServletResponse;
31:
32:
33: /**
34: * <code>HttpAuthenticationMechanismHandler</code> is a mechanism for obtaining a caller's credentials in some way,
35: * using the HTTP protocol where necessary, by consulting a set of one or more {@link HttpAuthenticationMechanism}s.
36: *
37: * <p>
38: * This is a special variant of an {@link HttpAuthenticationMechanism} intended for coordination
39: * between multiple {@link HttpAuthenticationMechanism}s. Implementations are therefore expected and
40: * encouraged to delegate actually obtaining the caller's credential to an actual {@link HttpAuthenticationMechanism}.
41: * This is however <b>not</b> required and implementations can do as they choose.
42: *
43: * <p>
44: * Implementations of Jakarta Security <b>must</b> supply a default implementation of the
45: * {@code HttpAuthenticationMechanismHandler}. This implementation must be {@link ApplicationScoped} and this implementation
46: * <b>must</b> behave as described below:
47: *
48: * <ol>
49: * <li> Before servicing any calls as defined by this interface, the implementation must (implicitly) check if there is more
50: * than one enabled bean of type {@code HttpAuthenticationMechanism} available, irrespective of any qualifiers.
51: * </li>
52: * <li> If there is more than one enabled bean of type {@code HttpAuthenticationMechanism} available, the implementation
53: * must apply the ambiguous dependency resolution rules to this set of {@linkplain Bean beans}. For instance by using
54: * {@link jakarta.enterprise.inject.spi.BeanContainer#resolve(java.util.Set)}.
55: * </li>
56: * <li>
57: * If the ambiguous dependency resolution rules fail, an {@link AmbiguousResolutionException} must be thrown (or the
58: * one thrown by {@link jakarta.enterprise.inject.spi.BeanContainer#resolve(java.util.Set)} propagated).
59: * </li>
60: * <li>
61: * If the ambiguous dependency resolution rules succeed, the implementation must remember the one resulting bean.
62: * </li>
63: * <li>
64: * When servicing any calls as defined by this interface, the implementation must call the method on the
65: * remembered {@code HttpAuthenticationMechanism} bean with the same name and arguments, and where applicable return
66: * the result from that call.
67: * </li>
68: * </ol>
69: *
70: * <p>
71: * Applications do not need to supply an {@code HttpAuthenticationMechanismHandler} unless application-specific
72: * behavior is desired.
73: *
74: * @since 4.0
75: */
76: public interface HttpAuthenticationMechanismHandler {
77:
78: /**
79: * Authenticate an HTTP request.
80: *
81: * <p>
82: * This method is called in response to an HTTP client request for a resource, and is always invoked
83: * <strong>before</strong> any {@link Filter} or {@link HttpServlet}. Additionally this method is called
84: * in response to {@link HttpServletRequest#authenticate(HttpServletResponse)}
85: *
86: * <p>
87: * Note that by default this method is <strong>always</strong> called for every request, independent of whether
88: * the request is to a protected or non-protected resource, or whether a caller was successfully authenticated
89: * before within the same HTTP session or not.
90: *
91: * <p>
92: * A CDI/Interceptor spec interceptor can be used to prevent calls to this method if needed.
93: * See {@link AutoApplySession} and {@link RememberMe} for two examples.
94: *
95: * @param request contains the request the client has made
96: * @param response contains the response that will be send to the client
97: * @param httpMessageContext context for interacting with the container
98: * @return the completion status of the processing performed by this method
99: * @throws AuthenticationException when the processing failed
100: */
101: AuthenticationStatus validateRequest(HttpServletRequest request, HttpServletResponse response, HttpMessageContext httpMessageContext) throws AuthenticationException;
102:
103: /**
104: * Secure the response, optionally.
105: *
106: * <p>
107: * This method is called to allow for any post processing to be done on the request, and is always invoked
108: * <strong>after</strong> any {@link Filter} or {@link HttpServlet}.
109: *
110: * <p>
111: * Note that this method is only called when a (Servlet) resource has indeed been invoked, i.e. if a previous call
112: * to <code>validateRequest</code> that was invoked before any {@link Filter} or {@link HttpServlet} returned SUCCESS.
113: *
114: * @param request contains the request the client has made
115: * @param response contains the response that will be send to the client
116: * @param httpMessageContext context for interacting with the container
117: * @return the completion status of the processing performed by this method
118: * @throws AuthenticationException when the processing failed
119: */
120: default AuthenticationStatus secureResponse(HttpServletRequest request, HttpServletResponse response, HttpMessageContext httpMessageContext) throws AuthenticationException {
121: return SUCCESS;
122: }
123:
124: /**
125: * Remove mechanism specific principals and credentials from the subject and any other state the mechanism
126: * might have used.
127: *
128: * <p>
129: * This method is called in response to {@link HttpServletRequest#logout()} and gives the authentication mechanism
130: * the option to remove any state associated with an earlier established authenticated identity. For example, an
131: * authentication mechanism that stores state within a cookie can send remove that cookie here.
132: *
133: * @param request contains the request the client has made
134: * @param response contains the response that will be send to the client
135: * @param httpMessageContext context for interacting with the container
136: */
137: default void cleanSubject(HttpServletRequest request, HttpServletResponse response, HttpMessageContext httpMessageContext) {
138: httpMessageContext.cleanClientSubject();
139: }
140:
141: }