com.broadleafcommerce.data.tracking.core.policy

Annotation Type Policy

@Retention(value=RUNTIME)
 @Target(value=METHOD)
 @Documented
public @interface Policy

Used to annotate a method that should be validated against one or more policies before the method is allowed to execute. Makes use of a backing PolicyEvaluator to make policy determinations.

In Trackable implementations, TrackableEntityPolicyEvaluator is used in concert with TrackablePolicyUtils used to perform the actual policy validation business logic.

Implementations can disable policy validation altogether by setting the 'broadleaf.common.policy.validation.enforce' property to false. Implementations can also customize, or replace, the out-of-the-box PolicyEvaluator behavior by providing their own instances of the PolicyEvaluator and/or PolicyUtils interfaces.

See PolicyOverride for more customization options regarding altering policy configuration declared in Broadleaf from the codebase of an extending platform.

Author:

Jeff Fischer

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
IdentityType[]	identityTypes One of more possible user identity types.
OperationType[]	operationTypes One or more possible valid operation types.
String	ownerIdentifier For use with the OWNER IdentityType and a business domain that implements the Owned interface, this overrides the global owner identifier key at the method level.
int	ownerIdentifierParam The position (0 based) of the method parameter that represents the owner's identifier.
int	param The position (0 based) of the object parameter for which policies are checked.
PermissionMatchingStrategy	permissionMatchingStrategy When multiple permissionRoots() are specified this controls how the final built authorities are validated for this annotation.
String[]	permissionRoots The permission roots to check.

Element Detail

param

public abstract int param

The position (0 based) of the object parameter for which policies are checked. This is generally an entity object parameter. This can be ignored for uses of Policy that are not concerned with validating a method parameter. Policy validation generally includes checking the GrantedAuthority instances on the current Authentication against permissionRoots() for applicability, as well as validation of any other information available in the current context. Additional contextual information is often included in a method parameter, as is the case with the ContextInfo method parameter in Trackable implementations.

A value of -1 (the default) indicates that object validation should be ignored.

Returns:

The position of the object parameter for which policies are checked

Default:

-1

permissionRoots

public abstract String[] permissionRoots

The permission roots to check. Can be left blank if the backing PolicyEvaluator implementation uses another approach to determine the current permission requirements. Permissions are generally constructed by combination of these roots with operationTypes() and compared against current user granted authorities.

If multiple roots are specified, this delegates to the final permissionMatchingStrategy() to determine how they are handled.

Returns:

One or more permission names to check

Default:

""

operationTypes

public abstract OperationType[] operationTypes

One or more possible valid operation types.

For Trackable implementations, usually used in combination with permissionRoots() to create a full permission to validate. This can be left at the default value, in which case, the ContextInfo.getOperationType() is used. In the case where multiple operation types are declared here, the ContextInfo.getOperationType() is queried in order to choose which value to use. If there is no contextInfo available, or if there is no match with the value in the contextInfo, the first operation type in the array is used.

In the case where there is no active ContextInfo and the default of OperationType.UNKNOWN is used, an ALL_ is prepended against the given permissionRoots() and used to validate that permission.

Returns:

One or more possible valid operation types

Default:

com.broadleafcommerce.data.tracking.core.type.OperationType.UNKNOWN

permissionMatchingStrategy

public abstract PermissionMatchingStrategy permissionMatchingStrategy

When multiple permissionRoots() are specified this controls how the final built authorities are validated for this annotation. The default is for only a single permission to have to match in order for the policy to evaluate successfully

Returns:

the matching strategy that is used for multiple permissionRoots()

Default:

com.broadleafcommerce.data.tracking.core.policy.PermissionMatchingStrategy.ANY

identityTypes

public abstract IdentityType[] identityTypes

One of more possible user identity types. Identity types represent the type of user requesting access. Different identity type receive different validation treatment. For example, IdentityType.ADMIN types represent standard admin requests for accessing data and checks for visibility and mutability based on multitenant concerns, etc... are enforced. IdentityType.OWNER on the other hand represents a standard user that is accessing a record they own (e.g. a cart). OWNER users are detected via a PolicyUtils.getAuthDetailsOwnerIdentifier() parameter} present in the Authentication.getDetails() and the identifier harvested from there must match the identifier provided via Owned.getOwnerIdentifier() on the data object being accessed. The data object to test must implement the Owned interface to enforce the OWNED identity type.

Using one or multiple identity types, a common endpoint can be used for multiple users and be protected appropriately based on that user's viewing context.

Returns:

One of more possible user identity types

Default:

com.broadleafcommerce.data.tracking.core.policy.IdentityType.UNKNOWN

ownerIdentifier

public abstract String ownerIdentifier

For use with the OWNER IdentityType and a business domain that implements the Owned interface, this overrides the global owner identifier key at the method level. For default implementations, this can be thought of as a JWT claim.

This is an optional value, and should only be used in cases where the owner id of this domain does not match the global default.

Returns:

The owner identifier.

See Also:

Owned.getOwnerIdentifier(), PolicyUtils.getAuthDetailsOwnerIdentifier()

Default:

""

ownerIdentifierParam

public abstract int ownerIdentifierParam

The position (0 based) of the method parameter that represents the owner's identifier.

For use with the OWNER IdentityType when you prefer to validate the authenticated user's ownership against a specific method param value, instead of searching for a method param that implements the Owned interface.

This is primarily intended to be used in endpoint methods where the owner's identifier is provided via a path variable.

A value of -1 (the default) indicates that validation should instead gather the owner's identifier from a method param that implements the Owned interface.

Returns:

The position of the method parameter that represents the owner's identifier

Default:

-1