commerce-canon/research/authorization-relationships/openfga-modeling.md

# 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