commerce-canon/research/authorization-relationships/cerbos-abac-derived-roles.md

# Cerbos ABAC Derived Roles

## Source Type

Product documentation and open-source implementation reference for Cerbos
policy decision point with derived roles and attribute-based conditions.

## Domain

Policy-based authorization, attribute-driven role derivation, and resource-centric
access control.

## Why This Source Matters

Cerbos combines resource policies, principal attributes, and derived roles —
a pattern common in SaaS where permissions depend on both identity attributes
and resource ownership context.

## Key Concepts

- **Principal**: subject of authorization request with `id` and `roles` plus
  optional attributes.
- **Resource**: target with `kind`, `id`, and attributes (owner, department,
  classification).
- **Action**: operation requested on resource.
- **Policy**: YAML/JSON rules binding roles and conditions to allow/deny/effect.
- **Derived roles**: dynamically computed roles from principal + resource
  attributes (e.g., `owner` when `principal.id == resource.attr.owner`).
- **Static roles**: assigned roles on principal at request time.
- **Condition**: CEL expression over principal, resource, and request metadata.
- **Scope**: policy namespace for multi-tenant isolation (`scope` field).
- **AuxData**: JWT claims or external data enriching principal at check time.
- **Effect**: ALLOW, DENY, or conditional variants with rule ordering.

## Relevant Terminology

| Term | Source meaning |
| --- | --- |
| Principal | Requesting party with id, roles, attributes. |
| Resource | Entity with kind, id, and attributes. |
| Derived role | Role computed from attribute matching rules. |
| Static role | Pre-assigned role on principal. |
| Policy | Declarative allow/deny rules. |
| Scope | Tenant or environment partition for policies. |
| Condition | Boolean expression over request context. |
| AuxData | Supplemental principal data (e.g., JWT). |
| kind | Resource type discriminator. |
| attr | Attribute bag on principal or resource. |

## Modeling Assumptions

- **Authorization is resource-centric** with policies attached to resource kinds.
- **Roles can be derived at evaluation time** from attribute equality or
  relationships encoded in attributes.
- **Principal attributes may come from JWT** or external identity system.
- **Ownership is often modeled as resource attribute**, not explicit relationship.
- **Scope provides tenant isolation** for policy sets.
- **No graph traversal** for permissions; derivation is attribute-based.
- **Identity system supplies principal id and roles**; Cerbos does not store
  identity records.

## Identity-Canon Implications

- Cerbos **Principal** maps to **Authorization Principal** projection.
- **Resource** maps to **Authorization Resource** projection.
- **Derived role** (e.g., owner) should trace to canonical **Ownership
  Relationship** or **Membership** when possible, not only attribute equality.
- Encoding `resource.attr.owner = principal.id` collapses relationship into
  attribute — canon should prefer explicit Relationship with authz projection.
- **Scope** maps to **Scope** / **Tenant** for policy partition.
- **AuxData JWT claims** map to **Claim** inputs to authorization projection.
- Supports S05 (admin roles), S10 (service principal attributes), but risks
  hiding relationships in attributes (tension with **P5**).

## Terminology Conflicts

- **Principal vs. User**: Cerbos principal id often equals user id from app DB.
- **Owner**: derived role "owner" vs. Ownership Relationship vs. resource
  attribute.
- **Role**: derived role vs. static IAM role vs. canonical Role relationship.
- **Scope vs. Tenant**: Cerbos scope is policy namespace; may not equal tenant.
- **Attributes vs. Profile**: principal attributes overlap with profile fields.

## Candidate Canonical Mappings

| Cerbos concept | Candidate canonical concept |
| --- | --- |
| Principal | Authorization Principal |
| Resource | Authorization Resource |
| Action | Authorization Action |
| Static role | Role (authorization projection) |
| Derived role | Role derived from Relationship (preferred) or attribute rule |
| Policy | Authorization Policy (downstream) |
| Scope | Scope / Tenant (policy partition) |
| Principal attributes | Profile/Claim inputs to projection |
| Resource attributes | Resource metadata + Ownership hints |
| AuxData (JWT) | Claim + Authenticated Subject context |
| Condition | Request context projection |

## Open Questions

- Should canon explicitly discourage encoding Ownership as resource attribute
  without a backing Relationship?
- How should derived roles from group membership sync with canonical Membership
  edges?
- Does Cerbos scope map 1:1 to Tenant, or also to Application Scope?
- Should JWT AuxData be documented as standard Authenticated Subject →
  Principal projection path?

## References

- Cerbos documentation — https://docs.cerbos.dev/
- Cerbos derived roles — https://docs.cerbos.dev/cerbos/latest/policies/derived_roles
- Cerbos scopes — https://docs.cerbos.dev/cerbos/latest/policies/scope_policy