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.
111 lines
4.7 KiB
Markdown
111 lines
4.7 KiB
Markdown
# OpenFGA Modeling
|
|
|
|
## Source Type
|
|
|
|
Product documentation and open-source implementation reference for OpenFGA
|
|
authorization modeling (Zanzibar-inspired).
|
|
|
|
## Domain
|
|
|
|
Relationship-based access control modeling, authorization schema design, and
|
|
multi-tenant permission systems.
|
|
|
|
## Why This Source Matters
|
|
|
|
OpenFGA provides a concrete, documented modeling language for Zanzibar-style
|
|
relationship tuples with authorization models, stores, and checks.
|
|
|
|
## Key Concepts
|
|
|
|
- **Authorization model**: declarative schema of types, relations, and
|
|
permission definitions.
|
|
- **Type definition**: object type with relations and optional `define` rules.
|
|
- **Relation**: named edge on a type; may allow direct assignment or computed
|
|
rules.
|
|
- **Define / rewrite rules**: union (`+`), intersection, exclusion, and
|
|
inheritance (`from relation`).
|
|
- **Tuple**: `user:type#relation@object:type` stored fact.
|
|
- **Userset**: indirect reference such as `user:anne#member@group:engineering`.
|
|
- **Store**: isolated tuple set with its own model.
|
|
- **Check / ListObjects / ListUsers**: query APIs.
|
|
- **Contextual tuples**: ephemeral tuples supplied at check time.
|
|
- **Conditions**: CEL-based contextual rules on relations (newer versions).
|
|
|
|
## Relevant Terminology
|
|
|
|
| Term | Source meaning |
|
|
| --- | --- |
|
|
| User (in tuple) | Subject identifier in `user:` namespace. |
|
|
| Object | Entity in `object:` namespace with type. |
|
|
| Relation | Named permission edge on a type. |
|
|
| Type | Schema class for objects (document, folder, organization). |
|
|
| Model | Collection of type definitions. |
|
|
| Store | Isolated authorization dataset. |
|
|
| define | Computed relation rule. |
|
|
| from | Inheritance from related object's relation. |
|
|
| contextual tuple | Runtime-only tuple for conditional checks. |
|
|
|
|
## Modeling Assumptions
|
|
|
|
- **Model-first design**: relations are declared in schema before tuples are written.
|
|
- **User and object IDs are opaque strings**; no embedded identity semantics.
|
|
- **Organization/tenant patterns** are modeled as types (e.g., `organization`,
|
|
`tenant`) with `member`, `admin` relations.
|
|
- **Inheritance chains** (folder contains document) are common modeling pattern.
|
|
- **Store isolation** provides multi-tenant authorization separation.
|
|
- **Identity management is external**; OpenFGA consumes identifiers.
|
|
- **Permissions are computed**, not stored as standalone grants.
|
|
|
|
## Identity-Canon Implications
|
|
|
|
- OpenFGA aligns with Zanzibar mappings; adds explicit **authorization model**
|
|
as schema artifact (downstream, not canonical).
|
|
- Type definitions like `organization#member` parallel **Organization** +
|
|
**Membership Relationship** but in authz projection.
|
|
- **Store** maps to **Authorization Domain** Scope or tenant-scoped authz partition.
|
|
- `user:` prefix in tuples maps to **Authorization Principal** identifier.
|
|
- Contextual tuples support request-time **Delegation** context without
|
|
persisting relationship.
|
|
- Model examples for parent-child org hierarchies support S03, S04, S05.
|
|
- Reinforces **P6**: tuples are projections from actors/relationships.
|
|
|
|
## Terminology Conflicts
|
|
|
|
- **User**: OpenFGA `user:` is tuple subject prefix, not human or account.
|
|
- **Organization type**: authz type ≠ Organization collective actor unless
|
|
explicitly linked.
|
|
- **Member relation**: authz member ≠ community member without model alignment.
|
|
- **Store vs. Tenant**: store is authz isolation; tenant is broader scope.
|
|
- **Permission vs. Relation**: permissions are computed from relations; products
|
|
often say "permission" for relation name.
|
|
|
|
## Candidate Canonical Mappings
|
|
|
|
| OpenFGA concept | Candidate canonical concept |
|
|
| --- | --- |
|
|
| Tuple | Relationship Tuple (authorization projection) |
|
|
| user: (subject) | Authorization Principal |
|
|
| object: (entity) | Authorization Resource |
|
|
| Relation | Relationship type (authz-implied) |
|
|
| Type definition | Authorization schema (downstream) |
|
|
| Store | Authorization Domain Scope |
|
|
| define/from rules | Authorization derivation (non-canonical) |
|
|
| organization#member | Membership Relationship (projection) |
|
|
| organization#admin | Administration Relationship (projection) |
|
|
| contextual tuple | Delegation context (ephemeral) |
|
|
|
|
## Open Questions
|
|
|
|
- Should canon document standard OpenFGA type patterns (org/team/resource) as
|
|
downstream recommendations only?
|
|
- How should principal identifiers be aligned with Account IDs vs. Authenticated
|
|
Subject `sub` values?
|
|
- Do conditional (CEL) relations require canonical Context as a first-class
|
|
projection?
|
|
- Should one Store always map 1:1 to a Tenant Scope?
|
|
|
|
## References
|
|
|
|
- OpenFGA documentation — https://openfga.dev/docs
|
|
- OpenFGA modeling guide — https://openfga.dev/docs/modeling
|
|
- OpenFGA configuration language — https://openfga.dev/docs/configuration-language |