# Resource policies

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.

```yaml
---
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](https://docs.cerbos.dev/cerbos/latest/policies/scoped_policies) for this policy. |
| **4** | Optional [scope permission](https://docs.cerbos.dev/cerbos/latest/policies/scope_permissions) for this policy, defaults to `SCOPE_PERMISSIONS_OVERRIDE_PARENT`. |
| **5** | Import a set of [derived roles](https://docs.cerbos.dev/cerbos/latest/policies/derived_roles) (optional). |
| **6** | [Constant definitions](https://docs.cerbos.dev/cerbos/latest/policies/variables#export-constants) to import (optional). |
| **7** | [Local constant definitions](https://docs.cerbos.dev/cerbos/latest/policies/variables#local-constants) (optional). |
| **8** | [Variable definitions](https://docs.cerbos.dev/cerbos/latest/policies/variables#export) to import (optional). |
| **9** | [Local variable definitions](https://docs.cerbos.dev/cerbos/latest/policies/variables#local) (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.