From RBAC to ReBAC: when and how to migrate

Migrate from RBAC to ReBAC when access depends on which object a user is related to, not just what role they hold. If you are creating roles like editor_for_project_xyz, modeling "share this folder with Bob," or encoding org and team trees in role names, you have outgrown RBAC. Relationship-based access control stores those relationships as data and computes permissions by walking them. The migration is low risk if you run both systems side by side and cut over one call site at a time.

This guide is for engineers who own authorization in a multi-tenant SaaS product or internal platform. For the concepts first, see RBAC vs ABAC vs ReBAC.

Recognize the signs

• Role explosion: more roles than active users, or roles that encode a resource ID.
• Per-object sharing: "share this with Bob but not Alice" cannot be expressed without a new role.
• Inheritance: nested folders, projects inside workspaces, organization and team hierarchies.
• Tenant-defined access: each customer wants its own groups and sharing rules.
• Listing is slow: "show me every document I can see" means loading everything and filtering in application code.

Choose the model: RBAC, ABAC or ReBAC

Most real systems end up hybrid. The choice is which concern is the hard part: the graph (pick a Zanzibar-style engine) or the attribute logic (pick a policy engine).

Where ReBAC comes from

The dominant design is Google's Zanzibar, described in the USENIX ATC 2019 paper. Zanzibar stores access control lists as relation tuples and, per the paper, serves "trillions of access control lists and millions of authorization requests per second" for hundreds of Google services, with 95th-percentile latency under 10 milliseconds and availability above 99.999% over three years. You will not need that scale, but the data model and the consistency approach (the paper's "zookies") are what the open engines copy. The broader category is often called fine-grained authorization.

The engines

Cerbos shows the other path: its derived roles are "computed at request evaluation time from the principal's base roles and request attributes," for example an owner role when request.resource.attr.owner == request.principal.id. That handles ownership without a separate relationship store, but deep inheritance chains are awkward because you must pass the chain in.

Whichever engine you pick, put a thin interface between your application and the decision call. The AuthZEN Authorization API 1.0 (spec), the OpenID Foundation's standard API between enforcement and decision points, is the obvious shape for it and keeps a later engine swap from touching every call site.

A worked model

An OpenFGA schema 1.1 model for folders and documents, using the union (or), inheritance (from) and exclusion (but not) operators described in the configuration language docs:

model
  schema 1.1
type user
type folder
  relations
    define owner: [user]
    define editor: [user] or owner
    define viewer: [user] or editor
type document
  relations
    define parent: [folder]
    define owner: [user]
    define editor: [user] or owner
    define blocked: [user]
    define viewer: ([user] or editor or viewer from parent) but not blocked

Data is written as tuples of user, relation and object, as in the OpenFGA modeling guide: { user: "user:anne", relation: "owner", object: "document:42" }, { user: "folder:legal", relation: "parent", object: "document:42" }, or a group grant such as { user: "organization:A#member", relation: "editor", object: "document:1" }. Your old role editor_for_project_xyz becomes one tuple per member instead of one role per project.

The migration, step by step

1. Inventory call sites. List every place that checks a role. Each becomes a check(user, relation, object) call. This list is your cutover plan.
2. Model first. Write the schema and unit-test it against the engine's test tooling before touching production code. Design deny rules (but not blocked) now; they are hard to add later.
3. Backfill. Translate existing role assignments into tuples. Map each role to the smallest relation that reproduces it, and log any role you cannot map; those are your design gaps.
4. Dual-write. Every grant, revoke, share and membership change writes to RBAC and to the engine. Use an outbox or change-data-capture so a failed engine write is retried, not dropped.
5. Shadow reads. Keep RBAC authoritative, call the engine in parallel, and log every divergence with the user, object and both answers. Divergence is either a model bug or a backfill bug; fix and re-run.
6. Cut over per call site. Flip one endpoint at a time behind a flag, starting with read paths. Rollback is flipping the flag back.
7. Decommission RBAC. Only after shadow reads have agreed long enough to cover rare paths (month-end jobs, admin consoles, exports). Keep coarse admin roles as relations in the model.

Consistency and caching

A permission check against stale data is how a removed user still sees a document. SpiceDB's docs call this the New Enemy Problem, and the engines handle it differently:

• SpiceDB lets each request choose minimize_latency, at_least_as_fresh (with a ZedToken), at_exact_snapshot or fully_consistent. Per the consistency docs, writes default to fully consistent and other APIs default to minimize_latency; store the ZedToken returned by a write alongside the resource and pass it on later checks.
• OpenFGA offers MINIMIZE_LATENCY (default) and HIGHER_CONSISTENCY, which skips the cache. Per the docs, caching is disabled by default, so checks are strongly consistent until you turn it on.

Rule of thumb: revocations and sharing changes on sensitive objects use the stronger mode; bulk list views use the faster one.

Common failure modes

Related

Guides: implementing RBAC in the enterprise, implementing ABAC. Glossary: ReBAC, fine-grained authorization, AuthZEN, least privilege. Vendors: authorization.