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.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      java.security.PermissionCollection getPermissionCollection​(javax.security.auth.Subject subject)
      Returns a collection of at least all declared permissions associated with the caller principal contained in the @{subject} parameter.
      default boolean implies​(java.security.Permission permissionToBeChecked)
      This method checks whether the permission represented by the @{permissionToBeChecked} parameter is granted to the anonymous (unauthenticated) caller principal.
      default boolean implies​(java.security.Permission permissionToBeChecked, java.util.Set<java.security.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​(java.security.Permission permissionToBeChecked, javax.security.auth.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​(java.security.Permission permissionToBeChecked, javax.security.auth.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​(java.security.Permission permissionToBeChecked)
      This method checks whether the permission represented by the @{permissionToBeChecked} parameter is excluded by this policy.
      default boolean isUnchecked​(java.security.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 Detail

      • implies

        default boolean implies​(java.security.Permission permissionToBeChecked,
                                javax.security.auth.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​(java.security.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​(java.security.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​(java.security.Permission permissionToBeChecked,
                                      javax.security.auth.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

        java.security.PermissionCollection getPermissionCollection​(javax.security.auth.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​(java.security.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​(java.security.Permission permissionToBeChecked,
                                java.util.Set<java.security.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?