Role checks scattered through application code cannot answer "can this user see this document?" once sharing, folders, teams and tenants enter the picture. Relationship-based access control (ReBAC) models permissions as a graph of relationships between subjects and objects, and Google's Zanzibar paper showed that one such service could answer authorisation checks for many products at very large scale. Open source systems inspired by it, notably OpenFGA and SpiceDB, now let any engineering team run a central fine-grained authorisation service. This guide is for architects and engineers implementing one: the data model, schema design, consistency and the "new enemy" problem, data synchronisation, operating the service as critical infrastructure, and the mistakes that cause broken object level authorisation. For a comparison of RBAC, ABAC and ReBAC as models, see the Authorisation Models Guide.
Key takeaways
- Everything is a relationship tuple: permissions are derived from stored facts of the form object, relation, subject (for example
doc:readme#viewer@group:eng#member) plus schema rules that compute permissions from them. - The schema is security-critical code: union, intersection, exclusion and parent traversal rules decide who gets access; review and test them like any other access control code.
- Consistency is a design choice, not a default: cached checks can briefly use old relationships, so sensitive flows need consistency tokens (zookies, ZedTokens) or a higher consistency mode.
- Keeping tuples in sync is the hard part: most real failures come from stale or missing relationships after moves, deletions, tenant changes and offboarding, not from the engine.
- A central authorisation service is tier-0 infrastructure: its write API can grant access to anything, so protect, log and monitor it as you would an identity provider.
What Zanzibar introduced
Google described Zanzibar at USENIX ATC 2019 as a global system for storing and evaluating access control lists, used by services including Calendar, Cloud, Drive, Maps, Photos and YouTube. The paper reports more than 1,500 namespaces and more than 2 trillion relation tuples, millions of authorisation requests per second, 95th percentile latency under 10 milliseconds and availability above 99.999 per cent over three years. Most organisations will never need that scale; what matters is the design pattern.
- Relation tuples: stored facts written as
object#relation@user, where the user can be a single identity or a userset such asgroup:eng#member, which gives nested groups for free. - Namespace configuration: per object type, the relations and their userset rewrite rules.
- Userset rewrites:
_this(directly stored tuples),computed_userset(one relation implies another, so owners are editors and editors are viewers) andtuple_to_userset(follow a relation such as parent folder and inherit from it), combined with union, intersection and exclusion. - APIs: Check (does this user have this relation to this object), Read (stored tuples only), Write, Watch (a change stream) and Expand (the effective userset as a tree).
- Zookies: opaque consistency tokens that let a check be evaluated on a snapshot at least as fresh as a given content change.
- Leopard: a specialised index that flattens deep group nesting so membership becomes a fast reachability lookup.
OpenFGA and SpiceDB compared
Both projects implement the Zanzibar model as a service with their own schema languages. Naming them here explains the concepts; it is not a recommendation, and commercial managed services and other engines also exist.
| Aspect | OpenFGA | SpiceDB |
|---|---|---|
| Project | CNCF project, accepted September 2022, Incubating since 28 October 2025 | Open source project by AuthZed |
| Schema unit | type with relations and define statements in an authorization model; a store holds model versions and tuples | definition with relation and permission statements |
| Direct assignment | Type restrictions such as [user], [group#member], [user:*] | Subject types such as user, group#member, user:* |
| Union, intersection, exclusion | or, and, but not | +, &, - |
| Parent traversal | viewer from parent (tuple to userset) | parent->view (arrow), .all() for intersection arrows |
| Conditions | Conditional tuples with CEL expressions; contextual tuples sent per request and not stored | Caveats with CEL expressions; expiring relationships |
| Consistency | MINIMIZE_LATENCY (default) or HIGHER_CONSISTENCY per query; a zookie-style token is under consideration, not yet available | ZedTokens with minimize_latency, at_least_as_fresh, at_exact_snapshot, fully_consistent |
| Query APIs | Check, ListObjects, ListUsers, Expand, Read | CheckPermission, BulkCheckPermission, LookupResources, LookupSubjects, ReadRelationships, Watch |
For a standard API between your applications and whichever engine you pick, see the OpenID AuthZEN Authorization API Guide. Coding to a thin internal interface or AuthZEN reduces lock-in to one schema language.
Designing the schema
OpenFGA's own modelling guidance is a good sequence: pick the most important feature, list object types, list relations, define them, test, iterate. Practical rules on top of that:
- Separate stored relations from computed permissions: store nouns (
owner,editor,member,parent) and compute verbs (can_view,can_share,delete). In SpiceDB, relationships can only be written to relations, never to permissions, which enforces this. Applications should only ever check permissions. - Model the tenant explicitly: give every resource an
organizationortenantrelation and intersect sensitive permissions with tenant membership, for examplecan_view: viewer and member from organization. This makes a cross-tenant share fail even if a tuple is written by mistake. See the Multi-Tenant Authorisation Guide. - Use exclusion for blocks and suspensions:
viewer but not blocked(OpenFGA) orviewer - banned(SpiceDB) gives a deny that overrides inherited grants. Watch operator precedence: in SpiceDB union binds more tightly than intersection and exclusion, soa + b & cmeans(a + b) & c; use parentheses or intermediate permissions. - Limit public wildcards: SpiceDB documentation advises using
user:*only for read permissions. Never allow wildcards on admin, write or share relations. - Keep hierarchies shallow and typed: restrict what a
parentcan be (folder or drive, not anything). OpenFGA rejectstype:*and usersets in type restrictions used withfrom, and SpiceDB'suse typecheckingcatches impossible permissions at schema write time. - Put context in conditions, not tuples: time windows, IP ranges or approval state fit CEL conditions or caveats; per-request facts that should not persist fit OpenFGA contextual tuples.
- Document every relation: SpiceDB recommends doc comments on definitions, relations and permissions; reviewers need to know why each path exists.
Mapping common requirements to schema patterns
| Requirement | Pattern | Risk if done wrong |
|---|---|---|
| Owners can edit, editors can view | Computed userset (relation implies relation) | Missing implication causes support tickets; extra implication grants write to viewers |
| Folder access flows to documents | Tuple to userset on parent | Moved documents keep the old parent tuple and stay visible to the old audience |
| Team or group sharing | Userset subject group#member | Nested groups widen access silently; deep nesting slows checks |
| Public links | Wildcard user:* on a viewer relation | Wildcard on an edit relation exposes write to everyone |
| Blocked users and legal holds | Exclusion | Placed on the wrong side of a union, the block does nothing |
| Time-bound access | Condition, caveat or expiring relationship | Expiry handled in application code is forgotten and access becomes standing |
| Tenant isolation | Intersection with tenant membership | A single bad tuple shares data across customers |
Consistency and the new enemy problem
The Zanzibar paper names the risk: if access changes and content changes are applied out of order, a user who has just been removed can see new material. Its two examples are Alice removing Bob from a folder before Charlie moves new documents into it, and Alice removing Bob from a document before Charlie adds new content. Caching makes the window real in any ReBAC service.
- SpiceDB: writes and schema calls default to
fully_consistent; other APIs default tominimize_latency, which SpiceDB warns can open a new enemy window if used exclusively. The pattern is to store the ZedToken returned by a write next to the resource in your database (atextcolumn in Postgres) and pass it withat_least_as_freshon later checks of that resource.at_exact_snapshotis for short pagination windows and can fail with a snapshot expired error. - OpenFGA: caching is disabled by default, which makes all queries strongly consistent; when you enable caches,
MINIMIZE_LATENCYmay serve results that predate a recent write. The documentation suggests choosingHIGHER_CONSISTENCYat runtime, for example when the resource's last-modified time is recent. - Revocation paths need the strongest setting: offboarding, removing a share, or suspending an account should be followed by checks that cannot be answered from a stale cache. This matches OWASP ASVS 5.0 requirement V8.3.2, which expects changes to authorisation values to apply immediately or to be mitigated where they cannot.
| Flow | Suggested consistency | Why |
|---|---|---|
| Rendering a list or search results | Lowest latency | Volume is high; a brief delay is usually acceptable |
| Opening a specific sensitive resource after it changed | At least as fresh as the resource's stored token, or higher consistency | Prevents the new enemy problem on that object |
| After revoking access or offboarding | Fully consistent or higher consistency | Removed users must lose access now |
| Admin and share operations | Fully consistent | Low volume, high impact |
| Paginating a lookup | Exact snapshot within the garbage collection window | Stable pages without duplicates |
Keeping relationships in sync
The engine is only as correct as its tuples. Relationships come from the application database, the identity provider (groups, departments) and HR systems, and every source can drift.
- Write in the same unit of work: when the application creates, moves or deletes a resource, write or delete the tuples in the same transaction pattern (for example a transactional outbox) so they cannot diverge.
- Handle moves and deletes explicitly: moving a document means deleting the old
parenttuple and writing the new one atomically; deleting a resource must delete all its tuples or orphaned grants accumulate. - Synchronise identity data: map identity provider groups and SCIM events to
group#membertuples, and remove membership on leaver events. See the Joiner-Mover-Leaver Guide. - Reconcile: run a scheduled job that compares source-of-truth data with stored tuples and reports drift. Use the Watch or changes stream to feed audit and downstream caches.
- Prefer computed over copied: where a rule can be computed from existing relations (owners are editors), do not write a second tuple that can go stale.
Operating the authorisation service securely
A central service answers every access decision, so its availability, its credentials and its write path all matter.
- Protect the write API: separate credentials for write and check, scoped per application and per store where the engine allows; only the owning service writes its object types. A compromised write credential can grant anything. Treat the API keys or client credentials as privileged non-human identities. See the API Key Management Guide.
- Control schema changes: keep the model in version control, require review, run model tests in CI and deploy through a pipeline. In OpenFGA a store holds model versions, so pin applications to a model ID and promote deliberately. See the Policy-as-Code for Authorisation Guide.
- Fail closed: if the service times out, deny and show a retry message; never fall back to allow. Size timeouts and caches so a slow check does not tempt developers to bypass it.
- Isolate tenants and environments: data cannot be shared across OpenFGA stores, so stores can separate environments or very large tenants; never let test and production share a store.
- Enforce at a trusted layer: call the service from the API or service layer, not from the browser (ASVS V8.3.1), and check the originating subject's permissions rather than an intermediary's (ASVS V8.3.3).
Where identity fits
Service accounts, workloads and AI agents should be subjects in the graph too, with their own types (for example service or agent) and narrow relations, rather than using a shared super-user credential that bypasses checks. For delegated agent access, check the user's permission and the agent's permission together. See the AI Agent Authorisation Guide.
Implementation roadmap
- Inventory decisions: list every place the application checks access today and the rules behind it; ASVS V8.1.1 expects documented function-level and data-specific rules.
- Model one feature: write the schema for the most important resource type, with tenant intersection, and a test suite of allowed and denied cases (both OpenFGA and SpiceDB provide model testing tools).
- Backfill tuples: generate relationships from existing data, then reconcile counts and spot-check access with real users.
- Shadow mode: call the new service alongside the existing checks, log disagreements, but enforce the old decision. Fix the schema or data until disagreement is near zero and every remaining case is explained.
- Enforce by ring: switch enforcement for internal users, then a small tenant group, then everyone. Roll back by flipping the feature flag back to the legacy check, which you keep until the new path is stable.
- Extend and retire: add resource types one at a time, then remove legacy role checks from code so there is one source of truth.
Choosing your approach
- Stay with RBAC in code when the application has a handful of roles and no per-object sharing; a ReBAC service adds operational cost.
- Use ABAC or policy-as-code when decisions depend mostly on attributes and context (clearance, region, time) rather than relationships.
- Use ReBAC when users share objects, inherit through hierarchies, belong to nested teams or many tenants, or when you need "list everything this user can see".
- Small teams should start with a managed service or a single-node deployment and one store; large organisations need a platform team owning the service, schema review, capacity planning and per-application credentials.
Detection and measurement
Log every write (who wrote which tuple, from which service), every schema change, denied checks on sensitive types and the consistency mode used. Feed tuple writes into the SIEM; a burst of writes granting owner or wildcard access is a strong signal of misuse.
- Shadow disagreement rate: share of checks where old and new decisions differ, by resource type, during migration.
- Reconciliation drift: number of tuples with no matching source record, and source records with no tuples.
- Revocation latency: time from removing access in the source system to a denied check, measured with synthetic tests.
- Check latency and error rate: p95 and p99 latency and timeout rate, since slow checks lead to bypasses.
- Coverage: percentage of API endpoints whose access decision goes through the service rather than inline code.
Framework mapping
| Framework | Reference | Relevance |
|---|---|---|
| NIST SP 800-53 Rev. 5 | AC-3 Access Enforcement, AC-3(7) Role-based, AC-3(13) Attribute-based, AC-24 Access Control Decisions | Central decision service and enforcement points |
| NIST SP 800-53 Rev. 5 | AC-6 Least Privilege, AU-2, AU-12 | Narrow relations and logging of writes and decisions |
| NIST CSF 2.0 | PR.AA-05 | Permissions defined in policy, managed, enforced and reviewed with least privilege |
| OWASP ASVS 5.0 | V8.1.1, V8.2.1, V8.2.2, V8.3.1, V8.3.2, V8.3.3, V8.4.1 | Documented rules, object-level checks, trusted enforcement, immediate revocation, cross-tenant controls |
| OWASP API Security Top 10 2023 | API1 Broken Object Level Authorization | The main failure ReBAC is meant to prevent |
Common failure patterns
- Checking roles, not objects: verifying that a caller is "a customer" but not that this record belongs to them is broken object level authorisation. In the McHire default password flaw, an internal API returned other applicants' records when a sequential ID was changed, because it never checked entitlement to the object. See the OWASP API Top 10 API1 Broken Object Level Authorization Guide.
- Stale tuples after moves and deletes: old
parentor share tuples keep data visible to an audience that should have lost it. - Cache-only checks on revocation: using the lowest latency mode everywhere reopens the new enemy window just after access is removed.
- Wildcards and over-broad unions: a
user:*on an edit relation, or a union that accidentally includes a broad group, grants far more than intended. - Fail open on timeout: code that treats an error as "allowed" turns an outage into a data exposure.
- One super credential: every service sharing one write key means any compromised service can rewrite the whole graph.
Practitioner checklist
- Document access rules per resource type before modelling, including tenant boundaries and deny cases.
- Store relations, check only permissions, and intersect sensitive permissions with tenant membership.
- Keep the schema in version control with review, model tests in CI and pinned model versions.
- Store consistency tokens with resources, and use the strongest consistency mode after revocations and on admin operations.
- Write and delete tuples in the same unit of work as resource changes, and run a reconciliation job.
- Issue separate, narrowly scoped credentials per service for writes and checks, kept in a vault.
- Fail closed on errors and timeouts, and alert on latency that could drive bypasses.
- Log tuple writes and schema changes to the SIEM and alert on bursts of owner or wildcard grants.
- Run in shadow mode before enforcing, and keep the legacy check behind a flag until stable.
Standards and references
- USENIX: Zanzibar, Google's Consistent, Global Authorization System
- OpenFGA: Concepts
- OpenFGA: Configuration Language
- OpenFGA: Query Consistency Modes
- AuthZed: SpiceDB Schema Language
- AuthZed: SpiceDB Consistency
- OWASP: Application Security Verification Standard 5.0
- NIST: SP 800-53 Rev. 5
Related NHI Mgmt Group resources: Authorisation Models Guide · OpenID AuthZEN Authorization API Guide · Policy-as-Code for Authorisation Guide · Multi-Tenant Authorisation Guide · Externalised Authorisation Buyer's Guide