generated from coulomb/repo-seed
tegwick
1c1b5c9bc6
Backfill all 23 research source notes with terminology extracts, modeling assumptions, conflicts, canonical mappings, and references. Refresh terminology artifacts, refine the conceptual model with explicit scenario paths, reconcile canon surfaces and open questions, and mark the workplan finished.
114 lines
4.9 KiB
Markdown
114 lines
4.9 KiB
Markdown
# 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 |