Package jakarta.security.jacc

Interface Policy

public interface Policy
A Policy object is responsible for determining whether a caller principal (including the unauthenticated one) has permission to perform a security-sensitive operation.

A Policy uses the Subject as a holder for the caller principal. A Subject, being a "bag of principals" does not specify which of the potentially many principals represents the caller principal. As a low level artifact (aimed at Jakarta EE runtime interaction with the security system) this allows for an amount of runtime specific behaviour and optimisations.

Policies typically, but not necessarily, make use of the Permission instances hold by the PolicyConfiguration instance for a given policy context. In a Jakarta EE Servlet environment these contain the transformed security constraints as expressed by XML in web.xml, via annotations, or which are programmatically set using the Jakarta Servlet APIs.

Author:
Arjan Tijms

  • Method Summary

    Modifier and Type
    Method
    Description
    PermissionCollection
    getPermissionCollection(Subject subject)
    Returns a collection of at least all declared permissions associated with the caller principal contained in the @{subject} parameter.
    default boolean
    implies(Permission permissionToBeChecked)
    This method checks whether the permission represented by the @{permissionToBeChecked} parameter is granted to the anonymous (unauthenticated) caller principal.
    default boolean
    implies(Permission permissionToBeChecked, Set<Principal> principals)
    Returns a collection of at least all declared permissions associated with the caller principal contained in the set of principals being passed in.
    default boolean
    implies(Permission permissionToBeChecked, Subject subject)
    This method checks whether the permission represented by the @{permissionToBeChecked} parameter is granted to the caller principal within the @{subject} parameter.
    default boolean
    impliesByRole(Permission permissionToBeChecked, Subject subject)
    This method checks whether the permission represented by the @{permissionToBeChecked} parameter is granted to the caller principal within the @{subject} parameter based on one or more roles associated with that caller principal.
    default boolean
    isExcluded(Permission permissionToBeChecked)
    This method checks whether the permission represented by the @{permissionToBeChecked} parameter is excluded by this policy.
    default boolean
    isUnchecked(Permission permissionToBeChecked)
    This method checks whether the permission represented by the @{permissionToBeChecked} parameter is unchecked by this policy.
    default void
    refresh()
    Optional method; TODO: needed?

  • Method Details

    • implies

      default boolean implies(Permission permissionToBeChecked, Subject subject)
      This method checks whether the permission represented by the @{permissionToBeChecked} parameter is granted to the caller principal within the @{subject} parameter.
      Parameters:
      permissionToBeChecked - the permission this policy is going to check
      subject - holder of the (obscured) caller principal
      Returns:
      true if the caller principal has the requested permission, false otherwise

    • isExcluded

      default boolean isExcluded(Permission permissionToBeChecked)
      This method checks whether the permission represented by the @{permissionToBeChecked} parameter is excluded by this policy. Excluded means the permission is not granted to any caller.
      Parameters:
      permissionToBeChecked - the permission this policy is going to check
      Returns:
      true if the requested permission is excluded, false otherwise

    • isUnchecked

      default boolean isUnchecked(Permission permissionToBeChecked)
      This method checks whether the permission represented by the @{permissionToBeChecked} parameter is unchecked by this policy. Unchecked means the permission is granted to any caller, either authenticated or not.
      Parameters:
      permissionToBeChecked - the permission this policy is going to check
      Returns:
      true if the requested permission is unchecked, false otherwise

    • impliesByRole

      default boolean impliesByRole(Permission permissionToBeChecked, Subject subject)
      This method checks whether the permission represented by the @{permissionToBeChecked} parameter is granted to the caller principal within the @{subject} parameter based on one or more roles associated with that caller principal.
      Parameters:
      permissionToBeChecked - the permission this policy is going to check
      subject - holder of the (obscured) caller principal
      Returns:
      true if the caller principal has the requested permission, false otherwise

    • getPermissionCollection

      PermissionCollection getPermissionCollection(Subject subject)
      Returns a collection of at least all declared permissions associated with the caller principal contained in the @{subject} parameter.

      Policies can represent remote authorization systems which may not be able to provide all permissions, and there for this method cannot guarantee all permissions are indeed returned. The policy should however return at least all permissions which are declared or set within a Jakarta EE application. Examples of such permissions are the permissions transformed from the Jakarta Servlet security constraints expression in @{web.xml}, via annotations or programmatically using the Jakarta Servlet API.

      Parameters:
      subject - holder of the (obscured) caller principal
      Returns:
      a collection of permissions associated with the caller principal

    • implies

      default boolean implies(Permission permissionToBeChecked)
      This method checks whether the permission represented by the @{permissionToBeChecked} parameter is granted to the anonymous (unauthenticated) caller principal.
      Parameters:
      permissionToBeChecked - the permission this policy is going to check
      Returns:
      true if the anonymous caller principal has the requested permission, false otherwise

    • implies

      default boolean implies(Permission permissionToBeChecked, Set<Principal> principals)
      Returns a collection of at least all declared permissions associated with the caller principal contained in the set of principals being passed in.

      Policies can represent remote authorization systems which may not be able to provide all permissions, and there for this method cannot guarantee all permissions are indeed returned. The policy should however return at least all permissions which are declared or set within a Jakarta EE application. Examples of such permissions are the permissions transformed from the Jakarta Servlet security constraints expression in @{web.xml}, via annotations or programmatically using the Jakarta Servlet API.

      Parameters:
      permissionToBeChecked - the permission this policy is going to check
      principals - collection containing the (obscured) caller principal
      Returns:
      a collection of permissions associated with the caller principal

    • refresh

      default void refresh()
      Optional method; TODO: needed?