Module jakarta.security

Package jakarta.security.enterprise

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

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.
Set<String>	getAllDeclaredCallerRoles()	A list of all static (declared) application roles that the authenticated caller is in or the empty list if the caller is either not authenticated or is not in any declared role.
Principal	getCallerPrincipal()	Retrieve the platform-specific java.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 Details

getCallerPrincipal

Principal getCallerPrincipal()

Retrieve the platform-specific java.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 the pType 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 returns false.

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 a security-role-ref element nested in a servlet element in web.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 be jakarta.ejb.SessionContext#isCallerInRole(String).

Parameters:

role - a String 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.

getAllDeclaredCallerRoles

Set<String> getAllDeclaredCallerRoles()

A list of all static (declared) application roles that the authenticated caller is in or the empty list if the caller is either not authenticated or is not in any declared role.

A static (declared) role is a role that is declared upfront in the application, for example via the jakarta.annotation.security.DeclareRoles annotation, and is discovered during startup.

Next to the declared roles, it's possible that the underlying authorization system optionally works with a potentially infinite set of dynamic roles. Such dynamic (undeclared) roles ARE NOT contained in the set returned by this method.

Returns:

A list of all static (declared) roles the current caller is in, or the empty list if that caller is not authenticated or has no static (declared) roles.

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 a URLPatternSpec that identifies the application specific web resources to which the permission pertains. For a full specification of this pattern see

invalid reference

jakarta.security.jacc.WebResourcePermission#WebResourcePermission(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 the AuthenticationParameters.newAuthentication parameter with this call.

This method requires an HttpServletRequest and HttpServletResponse argument to be passed in, and can therefore only be used in a valid Servlet context.

Parameters:

request - The HttpServletRequest associated with the current web resource invocation.

response - The HttpServletResponse associated with the given HttpServletRequest.

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