Derived roles

Traditional RBAC roles are usually broad groupings with no context awareness. Derived roles are a way of augmenting those broad roles with contextual data to provide more fine-grained control at runtime. For example, a person with the broad manager role can be augmented to manager_of_scranton_branch by taking into account the geographic location (or another factor) and giving that derived role bearer extra privileges on resources that belong to the Scranton branch.

Derived roles are dynamically determined at runtime by matching the principal’s roles sent in the API request to the parentRoles specified in the derived roles definitions. Don’t use the derived role names as roles in the API request as Cerbos only expects that field to contain "normal" roles. 
---
apiVersion: "api.cerbos.dev/v1"
description: |-
  Common dynamic roles used within the Apatr app
variables: (1)
  flagged_resource: request.resource.attr.flagged
derivedRoles:
  name: apatr_common_roles (2)
  definitions:
    - name: owner (3)
      parentRoles: ["user"] (4)
      condition: (5)
        match:
          expr: request.resource.attr.owner == request.principal.id

    - name: abuse_moderator
      parentRoles: ["moderator"]
      condition:
        match:
          expr: V.flagged_resource == true
1 Optional variables section. Each variable is evaluated before any rule condition. A variable expression can contain anything that condition expression can have.
2 Name to use when importing this set of derived roles.
3 Descriptive name for this derived role.
4 The static roles (from the identity provider) to which this derived role applies to. The special value * can be used to match any role.
5 An (optional) set of expressions that should evaluate to true for this role to activate.
Understanding derived roles

To explain the concept of derived roles, consider this example from the DC Comics universe: when billionaire playboy Bruce Wayne wears the bat costume he becomes Batman, the caped crusader. Becoming Batman gives Bruce extra privileges like being able to beat up criminals without any consequences and driving a tank through the streets of Gotham. In Cerbos terms, Batman is the derived role and Bruce Wayne is the parentRole. The condition for activating the Batman derived role is: Bruce Wayne is wearing the bat costume.

Cerbos only ever deals with Bruce Wayne because he’s the only real person in this scenario. However, Cerbos is smart enough to treat him as Batman whenever he’s wearing his costume.

---
apiVersion: "api.cerbos.dev/v1"
derivedRoles:
  name: gotham_city
  definitions:
    - name: batman
      parentRoles: ["bruce_wayne"]
      condition:
        match:
          expr: P.attr.isWearingBatCostume
---