Join our Newsletter — 33% off our NHI Course
Home› Guides› Fine-Grained Authorisation Guide: Implementing ReBAC with Zanzibar, OpenFGA…
Guide Authorisation

Fine-Grained Authorisation Guide: Implementing ReBAC with Zanzibar, OpenFGA and SpiceDB

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 15 min read
On this page

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 as group: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) and tuple_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.

AspectOpenFGASpiceDB
ProjectCNCF project, accepted September 2022, Incubating since 28 October 2025Open source project by AuthZed
Schema unittype with relations and define statements in an authorization model; a store holds model versions and tuplesdefinition with relation and permission statements
Direct assignmentType restrictions such as [user], [group#member], [user:*]Subject types such as user, group#member, user:*
Union, intersection, exclusionor, and, but not+, &, -
Parent traversalviewer from parent (tuple to userset)parent->view (arrow), .all() for intersection arrows
ConditionsConditional tuples with CEL expressions; contextual tuples sent per request and not storedCaveats with CEL expressions; expiring relationships
ConsistencyMINIMIZE_LATENCY (default) or HIGHER_CONSISTENCY per query; a zookie-style token is under consideration, not yet availableZedTokens with minimize_latency, at_least_as_fresh, at_exact_snapshot, fully_consistent
Query APIsCheck, ListObjects, ListUsers, Expand, ReadCheckPermission, 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 organization or tenant relation and intersect sensitive permissions with tenant membership, for example can_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) or viewer - banned (SpiceDB) gives a deny that overrides inherited grants. Watch operator precedence: in SpiceDB union binds more tightly than intersection and exclusion, so a + b & c means (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 parent can be (folder or drive, not anything). OpenFGA rejects type:* and usersets in type restrictions used with from, and SpiceDB's use typechecking catches 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

RequirementPatternRisk if done wrong
Owners can edit, editors can viewComputed userset (relation implies relation)Missing implication causes support tickets; extra implication grants write to viewers
Folder access flows to documentsTuple to userset on parentMoved documents keep the old parent tuple and stay visible to the old audience
Team or group sharingUserset subject group#memberNested groups widen access silently; deep nesting slows checks
Public linksWildcard user:* on a viewer relationWildcard on an edit relation exposes write to everyone
Blocked users and legal holdsExclusionPlaced on the wrong side of a union, the block does nothing
Time-bound accessCondition, caveat or expiring relationshipExpiry handled in application code is forgotten and access becomes standing
Tenant isolationIntersection with tenant membershipA 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 to minimize_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 (a text column in Postgres) and pass it with at_least_as_fresh on later checks of that resource. at_exact_snapshot is 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_LATENCY may serve results that predate a recent write. The documentation suggests choosing HIGHER_CONSISTENCY at 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.
FlowSuggested consistencyWhy
Rendering a list or search resultsLowest latencyVolume is high; a brief delay is usually acceptable
Opening a specific sensitive resource after it changedAt least as fresh as the resource's stored token, or higher consistencyPrevents the new enemy problem on that object
After revoking access or offboardingFully consistent or higher consistencyRemoved users must lose access now
Admin and share operationsFully consistentLow volume, high impact
Paginating a lookupExact snapshot within the garbage collection windowStable 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 parent tuple 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#member tuples, 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

  1. 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.
  2. 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).
  3. Backfill tuples: generate relationships from existing data, then reconcile counts and spot-check access with real users.
  4. 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.
  5. 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.
  6. 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

FrameworkReferenceRelevance
NIST SP 800-53 Rev. 5AC-3 Access Enforcement, AC-3(7) Role-based, AC-3(13) Attribute-based, AC-24 Access Control DecisionsCentral decision service and enforcement points
NIST SP 800-53 Rev. 5AC-6 Least Privilege, AU-2, AU-12Narrow relations and logging of writes and decisions
NIST CSF 2.0PR.AA-05Permissions defined in policy, managed, enforced and reviewed with least privilege
OWASP ASVS 5.0V8.1.1, V8.2.1, V8.2.2, V8.3.1, V8.3.2, V8.3.3, V8.4.1Documented rules, object-level checks, trusted enforcement, immediate revocation, cross-tenant controls
OWASP API Security Top 10 2023API1 Broken Object Level AuthorizationThe 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 parent or 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

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

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.