Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Authorization: roles, relationships & policies

Who may do what, answered in single-digit milliseconds: RBAC vs ReBAC vs ABAC, the list-what-I-can-see problem, and how a revocation propagates.

A wall around one matter

A law firm keeps its case files in a document workspace, grouped by matter, one client's case. It takes on a new matter on one condition: four of its lawyers, who once advised the other side, must not open anything in it, an arrangement lawyers call an ethical wall. From then on the workspace has to answer, on every request, whether this person may do this to this file.

Who the person is was settled at sign-in (Authentication: passwords, MFA & identity providers), largely a solved problem you can buy. Authorization answers may you do this, to this thing, and only half of it is buyable: engines that evaluate roles, relationships and policies exist off the shelf, but the model, which relations exist and what they grant, is yours, because it depends on your domain's shape. It also runs on every request, which is why it belongs in a design review: a check that takes 40 ms and happens six times in a row per page is a 240 ms tax on the product.

Roles, until the first per-matter rule

The workspace started with RBAC, role-based access control: roles carry permissions, users carry roles. Partners edit, paralegals read. Simple, auditable, and the right answer for a back office. Global roles stop being enough the day permissions become per-object: "partner" cannot say partner on this matter, and the first workaround is a role called matter-4471-partner. Once role names contain object ids, the model has already failed: that is a relationship spelled inside a string.

What the firm has is a graph. Lawyers belong to matter teams, matters contain folders, folders contain documents, and access flows along those links. Permissions are edges, not columns, and "can Ana edit document 7" is a reachability query on that graph. That is ReBAC, relationship-based access control: permissions derive from relationships between subjects and objects, with inheritance (folder → document, team → member). It is what document, repository and workspace products usually need, and what Google's Zanzibar paper popularised. Each edge is stored as one small record, a relationship tuple: this matter, member, Ana.

The wall fits the same graph: a screened relation on the matter, and a rule that grants access to the matter's members except anyone screened from it. Other rules follow no relationship: documents marked privileged open only on firm-managed laptops, as the firm's device management reports them rather than as the request claims, even for a partner on the matter. That is ABAC, attribute-based access control: decisions computed from attributes of the subject, the resource and the context (department, data classification, device, time of day, IP range). Powerful, and the easiest kind to make unexplainable; keep the policy small enough that a human can predict the outcome.

Most real systems are a blend: coarse roles at the tenant boundary, relationships within it, a handful of attribute rules for compliance. In a product serving many firms, a mistake at that boundary lets one firm read another's files (Multi-tenancy). What matters is that the model is written down in one place and versioned separately from the application code, not reimplemented in every service's if statements, where ten copies give ten subtly different answers and no way to audit them. Centralise the decision, not the enforcement point: the gateway (API gateway & the edge) can turn away a request with no valid identity, but the document service still asks whether Ana may open document 7.

One decision service, one relationship store, one cache

Services ask; nobody re-implements the rules. Cached decisions live for seconds, and a revocation invalidates them instead of waiting.

One document, asked about all day

The first hard query is the check: one subject, one action, one object, answered in single-digit milliseconds, because opening one document asks it for the viewer, the comments and the share button. Cache it, keyed by everything the decision read (the device too, for a privileged file), but bound the staleness, and remember that the cache is the reason a revocation is not instant (Caching layers covers the cache itself). State the number out loud ("a revoked permission stops working within 10 seconds") so it is a property of the design rather than an accident of TTL configuration. For the wall, that number is the requirement: a fifth lawyer, once screened, loses access within 10 seconds. So, as in the diagram, the relationship change is emitted and the cache drops the decisions it could affect. A stale yes can still survive, from a lost invalidation or a decision computed just before the change and cached after it; only the TTL ends it, so the TTL plus any lag in the relationship data must fit in the 10 seconds.

The same screening is why every decision goes to the log with its subject, action, object and the rule that produced it. "Why could this lawyer see that?" gets asked in incidents and access reviews, and without that record the answer is guesswork; protecting the log from quiet edits is a topic of its own, Audit logs & tamper evidence.

A stale answer can also hide in a token: roles copied into a JWT's claims last until it expires, whatever the relationship store now says, so keep claims to identity and coarse roles. How long claims live, and how to cut a session short, is in Sessions vs tokens: JWT, refresh & revocation.

The list page nobody planned for

The second query is harder and gets forgotten until the list page is slow: "which objects may this subject see?" A paralegal opens My documents. You cannot answer it by fetching a page of rows and checking each one, because filtering after the fact breaks pagination (ask for 50, check 50, show 31; Pagination: offset, keyset & cursors), breaks counts, and leaks the existence of objects through page sizes: a screened lawyer who gets 31 results on a page of 50, with more pages after it, learns that 19 documents exist that they may not see. Either the authorization service can return the set of visible object ids, or the relationship data is close enough to the query to be joined. Decide this early, or the list endpoint gets rewritten.

Watch outFail closed. When the decision service is unreachable, deny, and make the outage loud. A cache that quietly serves the last known answer for an hour is a permission system that does not revoke, and "allow on error" is how a bug becomes a breach.

Draw both queries

Authorization Service at Scale is this workspace without the law firm. A finished Grid for it answers three questions from the drawing alone: where the single check is answered, where the list of visible objects comes from, and how many seconds a revoked permission survives, read off the cache's bound and its invalidation edge. SSO Identity Provider builds the sign-in that hands you the subject, and Multi-Tenant SaaS Platform shows what a mistake at the tenant boundary leaks.

Practice this