Resource policies

This documentation is for an as-yet unreleased version of Cerbos. Choose 0.51.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

Resource policies define rules for actions that can be performed on a given resource. A resource is an application-specific concept that applies to anything that requires access rules. For example, in an HR application, a resource can be as coarse-grained as a full employee record or as fine-grained as a single field in the record.

Multiple rules can be defined for the same action on a resource for different roles and/or with different conditions. If more than one rule matches a given input, the protocol for conflict resolution is as follows:

For a single role and an action, if some rules evaluated to EFFECT_ALLOW and some others evaluated to EFFECT_DENY, the overall effect is EFFECT_DENY.
If the principal has multiple roles and at least one of their roles evaluates to have EFFECT_ALLOW for the action, the overall effect is EFFECT_ALLOW. This prevents issues such as admin users inadvertently locking themselves out because they happen to have a less privileged role attached to them as well.

---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
  resource: "album:object" (1)
  version: "default" (2)
  scope: "acme.corp" (3)
  scopePermissions: SCOPE_PERMISSIONS_REQUIRE_PARENTAL_CONSENT_FOR_ALLOWS (4)
  importDerivedRoles:
    - apatr_common_roles (5)
  constants:
    import: (6)
      - apatr_common_constants
    local: (7)
      corporate_network_ip_range: 10.20.0.0/16
  variables:
    import: (8)
      - apatr_common_variables
    local: (9)
      is_corporate_network: |-
        request.principal.attr.ip_address.inIPAddrRange(constants.corporate_network_ip_range)
  rules:
    - actions: ['*'] (10)
      effect: EFFECT_ALLOW
      derivedRoles:
        - owner (11)

    - actions: ['view']
      effect: EFFECT_ALLOW
      roles:
        - user (12)
      condition:
        match:
          expr: request.resource.attr.public == true
      output: (13)
        when:
          ruleActivated: |-
            "view_allowed:%s".format([request.principal.id])
          conditionNotMet: |-
            "view_not_allowed:%s".format([request.principal.id])

    - name: moderator_rule (14)
      actions: ['view', 'delete']
      effect: EFFECT_ALLOW
      condition:
        match:
          expr: variables.is_corporate_network
      derivedRoles:
        - abuse_moderator
  schemas: (15)
    principalSchema:
      ref: cerbos:///principal.json (16)
    resourceSchema:
      ref: cerbos:///album/object.json (17)

1	Kind of resource to which this policy applies.
2	Version of this policy. Policies are uniquely identified by the resource name and version pair. You can have multiple policy versions for the same resource (e.g. production vs. staging). The version value `default` is special as it is the default fallback when no version is specified in the request.
3	Optional scope for this policy.
4	Optional scope permission for this policy, defaults to `SCOPE_PERMISSIONS_OVERRIDE_PARENT`.
5	Import a set of derived roles (optional).
6	Constant definitions to import (optional).
7	Local constant definitions (optional).
8	Variable definitions to import (optional).
9	Local variable definitions (optional).
10	Actions can contain wildcards. Wildcards honour the `:` delimiter. E.g. `a:*:d` would match `a:x:d` but not `a:x`.
11	This rule applies to a derived role.
12	Rules can also refer directly to static roles. The special value `*` can be used to disregard roles when evaluating the rule.
13	Optional output for the action rule. You can define optional expressions to be evaluated as output depending on whether the rule is activated or not activated because of a condition failure.
14	Optional name for the rule.
15	Optional section for defining schemas that apply to this resource kind.
16	Optional schema for validating the principal attributes.
17	Optional schema for validating the resource attributes.