Package com.broadleafcommerce.data.tracking.core.policy

Annotation Interface Policy

@Retention(RUNTIME) @Target(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

  • Element Details

    • param

      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

      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

      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:
      {UNKNOWN}

    • permissionMatchingStrategy

      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:
      ANY

    • identityTypes

      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:
      {UNKNOWN}

    • ownerIdentifier

      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.

      If multiple owner identifiers are supported, a comma separated string may be used. In the case of multiple owner identifiers, if any of these identifiers matches the owner, the ownership check will pass. A case where there may be multiple owners is with an account hierarchy where a parent account might define some payment or address to be shared with sub- accounts. In such a case, the owner identifier is either the requester's current account or one of its parents, "acct_id,parent_accts".

      Returns:
      The owner identifier.
      See Also:
      Default:
      ""

    • ownerIdentifierParam

      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