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.
      Since:
      4.0

    • 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 WebResourcePermission(String, String).
      methods - HTTP methods to check for whether the caller has access to the web resource using one of those methods. If no methods are provided, this method will return true only if the caller can access the resource using all HTTP methods
      Returns:
      true if the caller has access to the web resource using one of the given methods, or using all supported HTTP methods, if no method is provided. Otherwise returns false.

    • 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