Resource policies

This documentation is for an as-yet unreleased version of Cerbos. Choose 0.40.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, then a rule specifying EFFECT_DENY will take precedence over one specifying EFFECT_ALLOW.

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

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

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

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	Import a set of derived roles (optional).
5	Constant definitions to import (optional).
6	Local constant definitions (optional).
7	Variable definitions to import (optional).
8	Local variable definitions (optional).
9	Actions can contain wildcards. Wildcards honour the `:` delimiter. E.g. `a:*:d` would match `a:x:d` but not `a:x`.
10	This rule applies to a derived role.
11	Rules can also refer directly to static roles. The special value `*` can be used to disregard roles when evaluating the rule.
12	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.
13	Optional name for the rule.
14	Optional section for defining schemas that apply to this resource kind.
15	Optional schema for validating the principal attributes.
16	Optional schema for validating the resource attributes.