Package: SecurityContext

SecurityContext

Coverage

1: /*
2: * Copyright (c) 2023, 2024 Contributors to Eclipse Foundation.
3: * Copyright (c) 2015, 2022 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;
19:
20: import java.security.Principal;
21: import java.util.Set;
22:
23: import jakarta.security.enterprise.authentication.mechanism.http.AuthenticationParameters;
24: import jakarta.security.enterprise.authentication.mechanism.http.HttpAuthenticationMechanism;
25: import jakarta.servlet.http.HttpServletRequest;
26: import jakarta.servlet.http.HttpServletResponse;
27:
28: /**
29: * The SecurityContext provides an access point for programmatic security; an injectable type that is intended to be
30: * used by application code to query and interact with Jakarta Security.
31: *
32: * <p>
33: * Unless otherwise indicated, this type must be usable in all Jakarta EE containers, specifically the Jakarta Servlet
34: * and Jakarta Enterprise Beans containers.
35: *
36: */
37: public interface SecurityContext {
38:
39: /**
40: * Retrieve the platform-specific {@code java.security.Principal} that represents
41: * the name of authenticated caller, or null if the current caller is not authenticated.
42: *
43: * @return Principal representing the name of the current authenticated user, or null if not authenticated.
44: */
45: Principal getCallerPrincipal();
46:
47: /**
48: * Retrieve all Principals of the given type from the authenticated caller's Subject,
49: * or an empty set if the current caller is not authenticated, or if the specified type
50: * isn't found in the Subject.
51: * <p>
52: * This can be used to retrieve application-specific
53: * Principals when the platform's representation of the caller uses a different principal type.
54: * <p>
55: * The returned Set is not backed by the Subject's internal Principal Set.
56: * A new Set is created and returned for each method invocation.
57: * Modifications to the returned Set will not affect the internal Principal Set.
58: *
59: * @param pType Class object representing the type of Principal to return.
60: * @param <T> The actual type represented by the {@code pType} argument
61: *
62: * @return Set of Principals of the given type, or an empty set.
63: */
64: <T extends Principal> Set<T> getPrincipalsByType(Class<T> pType);
65:
66: /**
67: * Checks whether the authenticated caller is included in the specified logical <em>application</em> "role".
68: * If the caller is not authenticated, this always returns {@code false}.
69: *
70: * <p>
71: * This method <em>can not</em> be used to test for roles that are mapped to specific named Jakarta Servlets or
72: * named Jakarta Enterprise Beans. For a Servlet an example of this would be the {@code role-name} nested in a
73: * {@code security-role-ref} element nested in a {@code servlet} element in {@code web.xml}.
74: *
75: * <p>
76: * Should code in either such Jakarta Servlet or Jakarta Enterprise Bean wish to take such mapped (aka referenced, linked)
77: * roles into account, the facilities for that specific container should be used instead. For instance for Servlet that
78: * would be {@link HttpServletRequest#isUserInRole(String)} and for Jakarta Enterprise Beans that would be
79: * {@code jakarta.ejb.SessionContext#isCallerInRole(String)}.
80: *
81: * @param role a {@code String} specifying the name of the logical application role
82: * @return {@code true} if the authenticated caller is in the given role, false if the caller is not authentication or
83: * is not in the given role.
84: */
85: boolean isCallerInRole(String role);
86:
87: /**
88: * A list of all static (declared) application roles that the authenticated caller is in or the empty list if the caller is either not
89: * authenticated or is not in any declared role.
90: *
91: * <p>
92: * A static (declared) role is a role that is declared upfront in the application, for example via the {@code jakarta.annotation.security.DeclareRoles}
93: * annotation, and is discovered during startup.
94: *
95: * <p>
96: * Next to the declared roles, it's possible that the underlying authorization system optionally works with a potentially infinite set
97: * of dynamic roles. Such dynamic (undeclared) roles ARE NOT contained in the set returned by this method.
98: *
99: * @return A list of all static (declared) roles the current caller is in, or the empty list if that caller is not authenticated or has
100: * no static (declared) roles.
101: */
102: Set<String> getAllDeclaredCallerRoles();
103:
104: /**
105: * Checks whether the caller has access to the provided "web resource" using the given methods,
106: * as specified by section 13.8 of the Servlet specification.
107: *
108: * <p>
109: * A caller has access if the web resource is either not protected (constrained), or when it is protected by a role
110: * and the caller is in that role.
111: *
112: * @param resource the name of the web resource to test access for. This is a {@code URLPatternSpec} that identifies
113: * the application specific web resources to which the permission pertains. For a full specification of this pattern
114: * see {@link jakarta.security.jacc.WebResourcePermission#WebResourcePermission(String, String)}.
115: * @param methods HTTP methods to check for whether the caller has access to the web resource using one of those
116: * methods. If no methods are provided, this method will return {@code true} only if the caller can access the resource using all HTTP methods
117: *
118: * @return {@code true} if the caller has access to the web resource using one of the given methods, or using all
119: * supported HTTP methods, if no method is provided. Otherwise returns {@code false}.
120: */
121: boolean hasAccessToWebResource(String resource, String... methods);
122:
123: /**
124: * Signal to the container (programmatically trigger) that it should start or continue a web/HTTP based authentication dialog with
125: * the caller.
126: *
127: * <p>
128: * Programmatically triggering means that the container responds as if the caller had attempted to access a constrained resource
129: * and acts by invoking a configured authentication mechanism (such as the {@link HttpAuthenticationMechanism}).
130: *
131: * <p>
132: * Whether the authentication dialog is to be started or continued depends on the (logical) state of the authentication dialog. If
133: * such dialog is currently in progress, a call to this method will continue it. If such dialog is not in progress a new one will be
134: * started. A new dialog can be forced to be started regardless of one being in progress or not by providing a value of
135: * {@code true} for the {@link AuthenticationParameters#newAuthentication} parameter with this call.
136: *
137: * <p>
138: * This method requires an {@link HttpServletRequest} and {@link HttpServletResponse} argument to be passed in, and
139: * can therefore only be used in a valid Servlet context.
140: *
141: * @param request The {@code HttpServletRequest} associated with the current web resource invocation.
142: * @param response The {@code HttpServletResponse} associated with the given {@code HttpServletRequest}.
143: * @param parameters The parameters that are provided along with a programmatic authentication request, for instance the credentials.
144: * collected by the application for continuing an authentication dialog.
145: *
146: * @return The state of the authentication mechanism after being triggered by this call
147: */
148: AuthenticationStatus authenticate(HttpServletRequest request, HttpServletResponse response, AuthenticationParameters parameters);
149:
150: }