Module jakarta.security.jacc

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.

NOTE: DRAFT API. SUBJECT TO CHANGE

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?