Interface SecurityContext
-
public interface SecurityContext
The SecurityContext provides an access point for programmatic security; an injectable type that is intended to be used by application code to query and interact with Jakarta Security.Unless otherwise indicated, this type must be usable in all Jakarta EE containers, specifically the Jakarta Servlet and Jakarta Enterprise Beans containers.
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description AuthenticationStatus
authenticate(HttpServletRequest request, HttpServletResponse response, AuthenticationParameters parameters)
Signal to the container (programmatically trigger) that it should start or continue a web/HTTP based authentication dialog with the caller.Principal
getCallerPrincipal()
Retrieve the platform-specificjava.security.Principal
that represents the name of authenticated caller, or null if the current caller is not authenticated.<T extends Principal>
Set<T>getPrincipalsByType(Class<T> pType)
Retrieve all Principals of the given type from the authenticated caller's Subject, or an empty set if the current caller is not authenticated, or if the specified type isn't found in the Subject.boolean
hasAccessToWebResource(String resource, String... methods)
Checks whether the caller has access to the provided "web resource" using the given methods, as specified by section 13.8 of the Servlet specification.boolean
isCallerInRole(String role)
Checks whether the authenticated caller is included in the specified logical application "role".
-
-
-
Method Detail
-
getCallerPrincipal
Principal getCallerPrincipal()
Retrieve the platform-specificjava.security.Principal
that represents the name of authenticated caller, or null if the current caller is not authenticated.- Returns:
- Principal representing the name of the current authenticated user, or null if not authenticated.
-
getPrincipalsByType
<T extends Principal> Set<T> getPrincipalsByType(Class<T> pType)
Retrieve all Principals of the given type from the authenticated caller's Subject, or an empty set if the current caller is not authenticated, or if the specified type isn't found in the Subject.This can be used to retrieve application-specific Principals when the platform's representation of the caller uses a different principal type.
The returned Set is not backed by the Subject's internal Principal Set. A new Set is created and returned for each method invocation. Modifications to the returned Set will not affect the internal Principal Set.
- Type Parameters:
T
- The actual type represented by thepType
argument- Parameters:
pType
- Class object representing the type of Principal to return.- Returns:
- Set of Principals of the given type, or an empty set.
-
isCallerInRole
boolean isCallerInRole(String role)
Checks whether the authenticated caller is included in the specified logical application "role". If the caller is not authenticated, this always returnsfalse
.This method can not be used to test for roles that are mapped to specific named Jakarta Servlets or named Jakarta Enterprise Beans. For a Servlet an example of this would be the
role-name
nested in asecurity-role-ref
element nested in aservlet
element inweb.xml
.Should code in either such Jakarta Servlet or Jakarta Enterprise Bean wish to take such mapped (aka referenced, linked) roles into account, the facilities for that specific container should be used instead. For instance for Servlet that would be
HttpServletRequest.isUserInRole(String)
and for Jakarta Enterprise Beans that would bejakarta.ejb.SessionContext#isCallerInRole(String)
.- Parameters:
role
- aString
specifying the name of the logical application role- Returns:
true
if the authenticated caller is in the given role, false if the caller is not authentication or is not in the given role.
-
hasAccessToWebResource
boolean hasAccessToWebResource(String resource, String... methods)
Checks whether the caller has access to the provided "web resource" using the given methods, as specified by section 13.8 of the Servlet specification.A caller has access if the web resource is either not protected (constrained), or when it is protected by a role and the caller is in that role.
- Parameters:
resource
- the name of the web resource to test access for. This is aURLPatternSpec
that identifies the application specific web resources to which the permission pertains. For a full specification of this pattern seeWebResourcePermission(String, String)
.methods
- one or more methods to check for whether the caller has access to the web resource using one of those methods.- Returns:
true
if the caller has access to the web resource using one of the given methods,false
otherwise.
-
authenticate
AuthenticationStatus authenticate(HttpServletRequest request, HttpServletResponse response, AuthenticationParameters parameters)
Signal to the container (programmatically trigger) that it should start or continue a web/HTTP based authentication dialog with the caller.Programmatically triggering means that the container responds as if the caller had attempted to access a constrained resource and acts by invoking a configured authentication mechanism (such as the
HttpAuthenticationMechanism
).Whether the authentication dialog is to be started or continued depends on the (logical) state of the authentication dialog. If 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 started. A new dialog can be forced to be started regardless of one being in progress or not by providing a value of
true
for theAuthenticationParameters.newAuthentication
parameter with this call.This method requires an
HttpServletRequest
andHttpServletResponse
argument to be passed in, and can therefore only be used in a valid Servlet context.- Parameters:
request
- TheHttpServletRequest
associated with the current web resource invocation.response
- TheHttpServletResponse
associated with the givenHttpServletRequest
.parameters
- The parameters that are provided along with a programmatic authentication request, for instance the credentials. collected by the application for continuing an authentication dialog.- Returns:
- The state of the authentication mechanism after being triggered by this call
-
-