- Arquitetura de Software
- Open Source
- Desenvolvimento Tecnológico
- Projetos Pessoais
- TypeScript
- NodeJS
- Convex
- Free Software
- Desenvolvimento Pessoal
- Tecnologia e Sociedade
Building a ReBAC-Inspired Authorization System
A Comprehensive Case Study
Reading tutorials and comparing SaaS platforms teaches you the concept of authorization. It does not teach you how an authorization system works on the inside. I only learned that by building one from scratch and living with every consequence of that choice. This post tells the story of GateKey, an authorization system inspired by ReBAC (relationship-based access control) that I built to explore the space between the simplicity of Auth0 and the completeness of Keycloak. It also covers what building it taught me about designing systems that make binary decisions about people's access.
Why ReBAC Matters: Beyond Role-Based Access Control
For most developers, authorization comes down to one of two questions: "what is this user's role?" (RBAC) or "can this user perform this action?" (a binary check). Both approaches work well, until the day they stop working.
The reason is that, in practice, access is not binary. It is relational. A user does not have a role: they have a relationship with a resource. "Manager of project X", "member of team Y", "guest in workspace Z". Each relationship carries different permissions. RBAC tries to flatten those relationships into named roles, and that simplification breaks as soon as requirements get complex: multi-tenant systems, delegated access, context-dependent permissions.
ReBAC (Relationship-Based Access Control) flips the model. Instead of assigning roles to users, you define relationships between entities: who owns what, who can edit what, who invited whom. The component that makes the permission decision, the PDP (Policy Decision Point), does not ask "does this user have the Editor role?". It asks "what is the relationship between this user and this resource?" and evaluates the permission based on that relationship.
Granularity is ReBAC's greatest strength and also its price. You define permissions at the level of each resource, tied to specific relationship paths. You can revoke one person's access to a single resource without touching anything else. In return, no permission is ever created implicitly: every access requires an explicit binding. For simple cases, that is overkill. For serious systems, it is what works.
ReBAC is about the kind of control, not scale
The question that comes up most is "when do I need ReBAC?". The answer is not "when you have 10,000 users" or "when the system grows". It is when the granularity you want to maintain goes beyond what RBAC can express. A two-person SaaS may need ReBAC if it requires a granular audit trail and the ability to revoke access to individual resources. A 10,000-person company may do just fine with RBAC if its permission model is simple.
So the decision is not about size. It is about the level of control you need and, as a result, how much complexity you are willing to accept in your authorization layer. I decided to build an entire system precisely to feel that complexity firsthand.
Learning by Building Complete Systems, Not Toy Projects
The project started with a decision: I would not build a demo, or an isolated feature. I would build a complete system.
There is a big difference between "building a to-do app to learn React" and "building a production system where React is essential". In the first case, you learn React. In the second, you learn architecture, state management, performance trade-offs and how to structure code that ages well. The same technology leads to completely different lessons.
Building GateKey meant building everything a production authorization system needs:
- multi-tenancy, with Organizations that contain Workspaces;
- session management;
- MFA and magic link login;
- access auditing;
- real-time permission evaluation;
- token expiration and immediate access revocation.
Each item is a small, isolated problem. Together, they force you to understand how authorization fits into the whole system. If I had studied only "resources and capabilities", I would have learned the concept. Building alongside the multi-tenant hierarchy, real-time sync and the interplay between authentication and authorization, I learned something else: the friction between those parts, the decisions about where each piece of logic should live and the failures that only show up when everything is connected.
Open source as a practice
Everything I build to learn, I release as open source. I will not turn this into a political discussion here. It is a practice: if you are building a reference system, other people need to be able to see it, critique it and build on top of it. The reasoning behind that choice lives in another post, on GPL vs MIT.
With the scope defined, the next step was not opening the editor. It was writing.
From PRD to Architecture: How I Designed GateKey
I started with a PRD (Product Requirements Document). It defined what I wanted to explore:
- a pure ReBAC model at the core, not a hybrid;
- a three-level multi-tenant structure: Root org → Organizations → Workspaces;
- permissions defined as relationships: who can do what on which resource;
- real-time permission updates: if I revoke access, it is gone immediately;
- an audit trail for every permission decision;
- a system usable by a single developer, not just theory.
The PRD was incomplete, and that is normal. As I built, I found out what I did not know, and the PRD evolved. The core principle, though, never changed: relationships first, everything else follows. Three decisions shaped the architecture.
Decision 1: no global roles, every access is a scoped binding
Most systems start with RBAC and add relationships later. It is pragmatic, because it is easy to implement at first. And it is fatal, because you end up with two partial systems talking to each other.
In GateKey I started from the other end: the relationship between user and resource comes first. There is no global role with implicit permissions. Every permission is a binding: a user, a role and a resource (or the whole workspace), always inside a workspace. A role on its own grants nothing. It only applies where a binding exists. The PDP evaluates each request by asking: "is there a binding that connects this user to this resource with a role that has this capability?".
The PRD called for pure ReBAC. What the code implements sits somewhere in between: it is closer to resource-scoped RBAC, with inheritance between resources, than to Zanzibar-style ReBAC. The "relationship" the PDP sees is "this user has this role on this resource", plus the containment relationship between a resource and its parent. There are no free-form relationship types such as "owner" or "invited".
That is more expressive and also more complex. Every permission has to be defined explicitly. You have to model the relationships and think about propagation: if I give someone access to a container, does that access flow down to the items inside it or not?
Decision 2: a three-level hierarchy, with context-dependent inheritance
The hierarchy has three levels: Root org → Organizations → Workspaces. Bindings live inside the Workspace. Within it, a binding can apply to the whole Workspace or to a specific resource. And one resource type can inherit from another (an item inside a container, for example), but only if the type definition declares that inheritance. That solves common multi-tenancy problems, but it creates ambiguity.
To evaluate a permission, the PDP may have to walk the entire hierarchy before returning a verdict. Can the user edit this document? I check for a direct binding on the document. None? If the "document" type inherits from a container, I check for a binding on the parent container. None? I check for a binding on the Workspace that contains the document. Still none? Denied. Now add caching, cache invalidation and the need to record which binding actually granted the permission.
That decision solved the problem I wanted to solve and created problems I had not anticipated. That is exactly what building a system teaches you.
Decision 3: separating capabilities from roles
In traditional RBAC, a role holds its permissions directly: "Editor = edit, delete, comment". I inverted that. Roles hold capabilities, and capabilities hold permissions. A role is a set of capabilities, and an action requires a capability.
That adds a layer of indirection, but it lets me compose permissions without duplicating anything: I create new roles by combining existing capabilities. The cost shows up in auditing. When the PDP says "denied", which capability was missing? Which role applied? Without clear logs, you cannot trace it.
Many of these decisions did not come out of nowhere. They came from a Google paper.
Zanzibar in Practice: Authorization as a Graph Problem
In 2019 Google published the paper on Zanzibar, the company's authorization system. It is not a product you can download. It is a design pattern. The core idea is that evaluating authorization is a graph problem: the relationships between entities form a graph, and checking a permission means asking "can I get from the user to the resource by following allowed relationship paths?".
Zanzibar also separates storage (the relation tuples) from evaluation (the PDP). That is essential. It means the PDP can be stateless and run in parallel. A permission request does not need a transaction: it needs a snapshot of the relationship graph and the ability to traverse it.
GateKey borrowed that separation. Bindings are records (user, role, resource) inside a workspace. The PDP is stateless. Multiple PDPs can evaluate permissions in parallel against the same binding store. The difference is that GateKey's PDP does not traverse an arbitrary graph like Zanzibar does: it runs a fixed number of lookups, in the order resource, parent resource and workspace.
The audit trail problem
Standard ReBAC returns a binary: ALLOW or DENY. But the "why" matters as much as the answer. So I added an audit trail: the PDP returns the decision and also the reason: direct binding, binding inherited from the parent resource, workspace binding or no binding found. "Denied because no binding was found at any level" is very different from "allowed by the parent container's binding, inherited by the document".
This part is entirely custom. There is no standard for it in ReBAC implementations, and it was an experiment. But it addressed a concrete need: when a user complains about access, you need to know why.
That need grows even bigger when every customer has its own rules.
Multi-Tenancy in Practice: Designing for Isolation
The three-level hierarchy is not theoretical. It exists because well-known products use these structures: Slack has Workspaces, Google has Organizations and Projects, Figma has Teams and Files. These are common patterns, not edge cases.
Building for this forces you to answer hard questions:
- Can an Organization admin see every Workspace, or do Workspace admins have autonomy?
- Can a permission at the Organization level override a denial at the Workspace level, or the other way around?
- When someone leaves the Organization, what happens to their Workspace memberships?
- How do you audit who has access to what when permissions depend on context?
These stop being policy questions and become architecture questions. They determine how the data is stored, how the PDP evaluates permissions and which edge cases you will run into.
Multi-tenancy is not "having a tenant_id column". It is designing around the assumption that tenants may have conflicting policies and that the system has to respect both.
One decision I did not expect to treat as architecture was the interface.
Design as a Reflection of the System: GateKey's Visual Identity
GateKey's first mockup was generic. Default-style cards, buttons with no clear logic, icons that meant nothing in particular. It looked like any admin dashboard, because the specification was vague.
The specification said things like "octagon in the empty state", "cards as a graph", "cut corners". It sounds specific when you read it. The moment a designer or an AI has to execute it, each sentence turns into dozens of possible interpretations. "Cut corners" could be a 30-degree chamfer, a hard 90-degree edge or something else entirely. Whoever executes picks the easiest interpretation, which is almost never the one you meant.
The problem was not the execution. It was the specification.
From prose to code: the specification as the source of truth
So I inverted the process. Instead of describing design intent and hoping it would come out right, I took the code that already worked, extracted its tokens (exact colors, spacing values, animation keyframes) and documented those tokens as the specification. The source of truth moved from prose to the system itself.
The second iteration was not "let's make it pretty". It was "let's document what works and make it consistent".
Every visual choice maps to a function
- Sharp corners, no border-radius: authorization has no curves. ALLOW and DENY are final, and the geometry conveys that decisiveness without explanation.
- Monospace font for system data: IDs, tokens, capabilities and permissions are not interface copy. They are data. They need to be easy to scan, easy to copy and visually distinct from UI labels.
- Amber as the only accent color: in a system where everything is denied by default, whatever is allowed or active needs to stand out. The color does not decorate. It signals "this passed the check".
- Real-time animations (scan, pulse, status indicators): an authorization system never rests. It is constantly evaluating sessions, expiring tokens and logging events. The interface cannot look static, because the system is not.
The only arbitrary choice was amber itself. It could have been green or blue. Once it was chosen, every decision that followed had a structural reason.
What I Learned Building an Authorization System
You can read about ReBAC, study the Zanzibar paper and watch videos on authorization patterns. None of that shows you what happens when you build a system with those patterns. Four lessons stuck.
Walking the hierarchy has a cost
The audit trail adds overhead. Every permission check may walk the hierarchy: direct binding? Parent resource binding? Workspace binding? That is three queries, or one with good caching. At scale, it adds up. You cannot avoid it, only plan for it.
The line between identity and authorization is blurry
I kept running into cases where identity and authorization overlapped. If MFA is enabled, does it change permission evaluation? If a session expires, do pending permission requests return the previous decision or fail? Where does authentication end and authorization begin? These questions are not theoretical. They determine how you structure your code.
You will miss a role hierarchy later
I implemented roles as flat lists of capabilities, with no inheritance. If you create a "Moderator" role and a "Senior Moderator" role with a few extra capabilities, you end up duplicating everything. That does not scale. Production systems need role hierarchies ("Senior Moderator extends Moderator"), but that complicates the PDP. I learned this by building, not by reading.
Convex is great for development, but not for this product in production
I chose Convex for its real-time reactivity and for not having to sync anything by hand. For building fast, it is excellent. For an authorization system that anyone should be able to self-host, it is a problem: a system meant to run anywhere should not depend on a proprietary managed service.
That tension is still unresolved. If GateKey goes to production, I will revisit the Convex decision. The likely path is replacing it with Postgres and an ORM that supports reactive queries, or accepting the lock-in as an explicit trade-off.
With those lessons on the table, it is easier to say what GateKey is today, and what it is not.
What GateKey Is Today
GateKey is a complete authorization system. It has authentication (MFA and magic links), resource-scoped bindings, multi-tenancy, real-time updates, access auditing and a working UI. The code is open on GitHub.
It does not replace Keycloak, which is far more complete. It is also not a direct alternative to Auth0, because it has no SaaS offering and never will for anyone but me. It fills a specific niche: engineers who want to understand how authorization works, who are willing to learn the system and who operate where "a complete system on my own infrastructure" matters more than "a managed SaaS".
What it deliberately is not
- It is not a general-purpose auth solution. Most apps do not need ReBAC. For those, use Auth0 or Supabase.
- It is not self-hosted in the traditional sense. The UI and logic run anywhere, but the data lives in Convex. That is a concrete limitation.
- It is not "done". It works, but production patterns (role hierarchies, large-scale caching, complex audit requirements) have not been fully explored.
- It is not minimal. It includes authentication features (MFA, magic links) that, strictly speaking, an authorization system should not have. They are there because production systems need them.
Who it works for
- Engineers building their own authorization system who want a reference implementation.
- Teams that understand authorization deeply and want to own their implementation.
- Products that need granular multi-tenant control and can absorb the complexity.
- Anyone who wants to learn ReBAC by building, not just reading.
It does not work for startups that need to ship fast, small teams without authorization expertise or anyone who wants "set it and forget it" auth.
Conclusion
This post was not a tutorial. It was a case study, and the difference matters. A tutorial would show "this is how ReBAC works" with isolated examples. A case study shows what happens when you commit to understanding a concept well enough to build an entire system around it.
The learning was not in the theory behind Zanzibar. It was in discovering that the theory does not deal with session expiration, audit trails, real-time invalidation, or the fact that people do not create bindings in clean, testable patterns. Systems in use are messier, and understanding that requires building.
If you are thinking about building your own authorization system, start here:
- Write a clear specification before any code.
- Build one complete feature at a time.
- Test your audit trail early. It is hard to add later.
- Accept that the technology you choose (Convex, Postgres or anything else) will constrain your design.
- Document your decisions, not for others, but for yourself a year from now.
If you are evaluating authorization systems for your product, GateKey can serve as a reference to study, even if you choose something else. Understanding what goes into an authorization system makes you a better evaluator of the ones already on the market.
Understanding a concept and understanding a system are different things. It is the difference between reading about ReBAC and building one. The second teaches more and costs more. This project was built on that trade-off.
References
- Google Research. "Zanzibar: Google's Consistent, Global Authorization System". USENIX Security Symposium, 2019.
- Keycloak Official Documentation. "Identity and Access Management".
- Open Policy Agent. "Policy as Code".
- Auth0. "Authorization Fundamentals".
- NIST. "Access Control Models and Policies". SP 800-162.
- Martin Fowler. "Microservices Security".
- Casbin. "Authorization Library for Multiple Languages".
- Convex. "Backend Development Platform with Real-Time Reactivity".
- Lidwell, Holden, Butler. "Universal Principles of Design".
- GateKey Repository. "Open Source ReBAC Authorization System".
- Mierzwa, Matheus. "GPL vs MIT".