Pular para o conteúdo
Voltar para o blog
  • Arquitetura de Software
  • Open Source
  • Desenvolvimento Tecnológico
  • Projetos Pessoais
  • TypeScript
  • NodeJS
  • Convex
  • Free Software
  • Desenvolvimento Pessoal
  • Tecnologia e Sociedade

Construindo um Sistema de Autorização Inspirado em ReBAC

Um Estudo de Caso Completo

Pixel art noturno: uma cidade murada em que fios roxos ligam casas a portões específicos, e só os portões com relação estão abertos e acesos

Ler tutoriais e comparar plataformas SaaS ensina o conceito de autorização. Não ensina como um sistema de autorização funciona por dentro. Isso eu só aprendi construindo um do zero e lidando com todas as consequências dessa escolha. Este post conta a história do GateKey, um sistema de autorização inspirado em ReBAC (controle de acesso baseado em relacionamentos) que eu construí para explorar o espaço entre a simplicidade do Auth0 e a completude do Keycloak. E conta o que essa construção me ensinou sobre projetar sistemas que tomam decisões binárias sobre o acesso de pessoas.

Por Que ReBAC Importa: Além do Controle de Acesso Baseado em Papéis

Para a maioria dos devs, autorização se resume a uma de duas perguntas: "qual é o papel deste usuário?" (RBAC) ou "este usuário pode fazer esta ação?" (uma verificação binária). As duas abordagens funcionam bem, até o dia em que deixam de funcionar.

O motivo é que, na prática, o acesso não é binário. Ele é relacional. Um usuário não tem um papel: ele tem uma relação com um recurso. "Gerente do projeto X", "membro do time Y", "convidado do workspace Z". Cada relação carrega permissões diferentes. O RBAC tenta achatar essas relações em papéis com nome, e essa simplificação quebra assim que os requisitos ficam complexos: sistemas multi-tenant, acesso delegado, permissões que dependem do contexto.

O ReBAC (Relationship-Based Access Control) inverte o modelo. Em vez de atribuir papéis a usuários, você define relações entre entidades: quem é dono do quê, quem pode editar o quê, quem convidou quem. O componente que decide a permissão, o PDP (Policy Decision Point), não pergunta "este usuário tem o papel de Editor?". Ele pergunta "qual é a relação entre este usuário e este recurso?" e avalia a permissão a partir dessa relação.

A granularidade é a maior força do ReBAC e também o seu preço. Você define permissões no nível de cada recurso, ligadas a caminhos de relação específicos. Você revoga o acesso de uma pessoa a um único recurso sem mexer em mais nada. Em troca, nenhuma permissão nasce de forma implícita: todo acesso exige um binding explícito. Para casos simples, isso é demais. Para sistemas sérios, é o que funciona.

ReBAC é uma questão de tipo de controle, não de escala

A pergunta que mais aparece é "quando eu preciso de ReBAC?". A resposta não é "quando você tiver 10 mil usuários" nem "quando o sistema crescer". É quando a granularidade que você quer manter passa do que o RBAC consegue expressar. Um SaaS de duas pessoas pode precisar de ReBAC se exigir trilha de auditoria granular e revogação de acesso a recursos individuais. Uma empresa de 10 mil pessoas pode viver bem com RBAC se o modelo de permissões dela for simples.

A decisão, então, não é sobre tamanho. É sobre o nível de controle de que você precisa e, por consequência, quanta complexidade você aceita na camada de autorização. Foi para sentir essa complexidade na pele que eu decidi construir um sistema inteiro.

Aprender Construindo Sistemas Completos, Não Projetinhos

O projeto começou com uma decisão: eu não ia construir uma demo, nem uma feature isolada. Ia construir um sistema completo.

Existe uma diferença grande entre "fazer um app de tarefas para aprender React" e "construir um sistema de produção em que React é essencial". No primeiro caso, você aprende React. No segundo, você aprende arquitetura, gerenciamento de estado, trade-offs de performance e como estruturar um código que envelheça bem. A mesma tecnologia gera aprendizados completamente diferentes.

Construir o GateKey significou construir tudo o que um sistema de autorização de produção precisa:

  • multi-tenancy, com Organizações que contêm Workspaces;
  • gerenciamento de sessão;
  • MFA e login por magic link;
  • auditoria de acesso;
  • avaliação de permissões em tempo real;
  • expiração de tokens e revogação de acesso imediata.

Cada item é um problema pequeno e isolado. Juntos, eles obrigam você a entender como a autorização se encaixa no sistema inteiro. Se eu tivesse estudado só "recursos e capacidades", teria aprendido o conceito. Construindo ao lado da hierarquia multi-tenant, da sincronização em tempo real e da interação entre autenticação e autorização, aprendi outra coisa: o atrito entre essas partes, as decisões sobre onde cada lógica deve morar e as falhas que só aparecem quando tudo está conectado.

Código aberto como prática

Tudo o que eu construo para aprender, eu libero como código aberto. Não vou transformar isso em discussão política aqui. É uma prática: se você está construindo um sistema de referência, outras pessoas precisam poder ver, criticar e construir em cima dele. O raciocínio por trás dessa escolha está em outro post, sobre GPL vs MIT.

Com o escopo definido, o próximo passo não foi abrir o editor. Foi escrever.

Do PRD à Arquitetura: Como Desenhei o GateKey

Comecei por um PRD (Product Requirements Document). Ele definia o que eu queria explorar:

  • um modelo ReBAC puro no núcleo, não híbrido;
  • uma estrutura multi-tenant em três níveis: Org raiz → Organizações → Workspaces;
  • permissões definidas como relações: quem pode fazer o quê em qual recurso;
  • atualização de permissões em tempo real: se eu revogo um acesso, ele cai na hora;
  • trilha de auditoria para toda decisão de permissão;
  • um sistema utilizável por um único dev, não só teoria.

O PRD estava incompleto, e isso é normal. Conforme eu construía, descobria o que não sabia, e o PRD evoluía. A linha central, porém, nunca mudou: relações primeiro, o resto vem depois. Três decisões deram forma à arquitetura.

Decisão 1: nenhum papel global, todo acesso é um binding com escopo

A maioria dos sistemas começa com RBAC e adiciona relações depois. É pragmático, porque é fácil de implementar no início. E é fatal, porque você acaba com dois sistemas parciais conversando entre si.

No GateKey eu parti do outro lado: a relação entre usuário e recurso vem primeiro. Não existe papel global com permissões implícitas. Toda permissão é um binding: um usuário, um papel e um recurso (ou o workspace inteiro), sempre dentro de um workspace. O papel sozinho não concede nada. Ele só vale onde existe um binding. O PDP avalia cada pedido perguntando: "existe um binding que liga este usuário a este recurso com um papel que tenha esta capacidade?".

O PRD pedia ReBAC puro. O que o código implementa fica no meio do caminho: é mais perto de um RBAC com escopo por recurso, com herança entre recursos, do que do ReBAC do Zanzibar. A "relação" que o PDP enxerga é "este usuário tem este papel neste recurso", mais a relação de contenção entre um recurso e o recurso pai. Não existem tipos de relação livres, como "dono" ou "convidou".

Isso é mais expressivo e também mais complexo. Toda permissão precisa ser definida de forma explícita. Você precisa modelar as relações e pensar na propagação: se eu dou acesso a alguém num container, esse acesso desce para os itens dentro dele ou não?

Decisão 2: três níveis de hierarquia, com herança conforme o contexto

A hierarquia tem três níveis: Org raiz → Organizações → Workspaces. Os bindings vivem dentro do Workspace. Dentro dele, um binding pode valer para o Workspace inteiro ou para um recurso específico. E um tipo de recurso pode herdar de outro (um item dentro de um container, por exemplo), mas só se a definição do tipo declarar essa herança. Isso resolve problemas comuns de multi-tenancy, mas cria ambiguidade.

Para avaliar uma permissão, o PDP pode ter que percorrer a hierarquia inteira antes de dar o veredito. O usuário pode editar este documento? Verifico o binding direto no documento. Não tem? Se o tipo "documento" herda de um container, verifico o binding no container pai. Não tem? Verifico o binding no Workspace que contém o documento. Também não? Negado. Agora some a isso cache, invalidação de cache e a necessidade de registrar qual binding concedeu a permissão.

Essa decisão resolveu o problema que eu queria resolver e criou problemas que eu não tinha previsto. É exatamente isso que construir um sistema ensina.

Decisão 3: separar capacidades de papéis

No RBAC tradicional, um papel tem as permissões diretamente: "Editor = editar, deletar, comentar". Eu inverti isso. Papéis têm capacidades, e capacidades têm permissões. Um papel é um conjunto de capacidades, e uma ação exige uma capacidade.

Isso adiciona uma camada de indireção, mas me permite compor permissões sem duplicar nada: crio papéis novos combinando capacidades que já existem. O custo aparece na auditoria. Quando o PDP responde "negado", qual capacidade faltou? Qual papel foi aplicado? Sem logs claros, você não consegue rastrear.

Boa parte dessas decisões não saiu do nada. Ela veio de um paper do Google.

Zanzibar na Prática: Autorização Como Problema de Grafo

Em 2019 o Google publicou o paper do Zanzibar, o sistema de autorização da empresa. Não é um produto que você baixa. É um padrão de design. A ideia central é que avaliar autorização é um problema de grafo: as relações entre entidades formam um grafo, e checar uma permissão é perguntar "consigo chegar do usuário até o recurso seguindo caminhos de relação permitidos?".

O Zanzibar também separa o armazenamento (as tuplas de relação) da avaliação (o PDP). Isso é essencial. Significa que o PDP pode ser stateless e rodar em paralelo. Um pedido de permissão não precisa de transação: precisa de um snapshot do grafo de relações e da capacidade de percorrê-lo.

O GateKey pegou emprestada essa separação. Os bindings são registros (usuário, papel, recurso) dentro de um workspace. O PDP é stateless. Vários PDPs podem avaliar permissões em paralelo sobre o mesmo armazenamento de bindings. A diferença é que o PDP do GateKey não percorre um grafo arbitrário como o Zanzibar: ele faz um número fixo de buscas, na ordem recurso, recurso pai e workspace.

O problema da trilha de auditoria

O ReBAC padrão devolve um binário: ALLOW ou DENY. Só que o "por quê" importa tanto quanto a resposta. Por isso adicionei uma trilha de auditoria: o PDP devolve a decisão e também o motivo: binding direto, binding herdado do recurso pai, binding do workspace ou nenhum binding encontrado. "Negado porque nenhum binding foi encontrado em nenhum nível" é bem diferente de "permitido pelo binding do container pai, herdado pelo documento".

Essa parte é totalmente customizada. Não existe um padrão para isso nas implementações de ReBAC, e foi um experimento. Mas resolveu uma necessidade concreta: quando um usuário reclama do acesso, você precisa saber o motivo.

Essa necessidade fica ainda maior quando cada cliente tem as próprias regras.

Multi-Tenancy na Prática: Projetando Para Isolamento

A hierarquia de três níveis não é teórica. Ela existe porque produtos conhecidos usam essas estruturas: o Slack tem Workspaces, o Google tem Organizações e Projetos, o Figma tem Times e Arquivos. São padrões comuns, não casos extremos.

Construir para isso obriga você a responder perguntas difíceis:

  • Um admin da Organização vê todos os Workspaces, ou os admins de Workspace têm autonomia?
  • Uma permissão no nível da Organização pode sobrescrever uma negação no nível do Workspace, ou o contrário?
  • Quando uma pessoa sai da Organização, o que acontece com o vínculo dela nos Workspaces?
  • Como auditar quem tem acesso ao quê quando a permissão depende do contexto?

Essas deixam de ser perguntas de política e passam a ser perguntas de arquitetura. Elas definem como os dados são armazenados, como o PDP avalia permissões e quais casos extremos você vai encontrar.

Multi-tenancy não é "ter uma coluna tenant_id". É projetar a partir da premissa de que tenants podem ter políticas conflitantes e de que o sistema precisa respeitar as duas.

Uma decisão que eu não esperava tratar como arquitetura foi a interface.

Design Como Reflexo do Sistema: A Identidade Visual do GateKey

O primeiro mockup do GateKey era genérico. Cards no estilo padrão, botões sem critério, ícones que não diziam nada. Parecia um dashboard de admin qualquer, porque a especificação era vaga.

A especificação dizia coisas como "octógono no empty state", "cards como grafo", "cantos cortados". Parece específico quando você lê. Na hora em que um designer ou uma IA precisa executar, cada frase vira dezenas de interpretações possíveis. "Cantos cortados" pode ser um chanfro de 30 graus, uma quina de 90 graus ou outra coisa. Quem executa escolhe a interpretação mais fácil, que quase nunca é a que você queria.

O problema não era a execução. Era a especificação.

De prosa a código: a especificação como fonte de verdade

Então eu inverti o processo. Em vez de descrever a intenção de design e torcer para dar certo, peguei o código que já funcionava, extraí os tokens (cores exatas, valores de espaçamento, keyframes de animação) e documentei esses tokens como a especificação. A fonte de verdade deixou de ser a prosa e passou a ser o próprio sistema.

A segunda iteração não foi "vamos deixar bonito". Foi "vamos documentar o que funciona e deixar consistente".

Cada escolha visual mapeia uma função

  • Cantos retos, sem border-radius: autorização não tem curva. ALLOW e DENY são finais, e a geometria comunica essa decisão sem precisar explicar.
  • Fonte monoespaçada para dados do sistema: IDs, tokens, capacidades e permissões não são texto de interface. São dados. Precisam ser fáceis de ler, de copiar e de distinguir dos rótulos da UI.
  • Âmbar como única cor de destaque: num sistema em que tudo é negado por padrão, o que está permitido ou ativo precisa saltar aos olhos. A cor não decora. Ela sinaliza "isto passou na verificação".
  • Animações em tempo real (scan, pulse, indicadores de status): um sistema de autorização não para. Ele avalia sessões, expira tokens e registra eventos o tempo todo. A interface não pode parecer parada, porque o sistema não está.

A única escolha arbitrária foi o âmbar em si. Poderia ter sido verde ou azul. Depois de escolhido, toda decisão seguinte teve um motivo estrutural.

O Que Aprendi Construindo um Sistema de Autorização

Você pode ler sobre ReBAC, estudar o paper do Zanzibar e assistir a vídeos sobre padrões de autorização. Nada disso mostra o que acontece quando você constrói um sistema com esses padrões. Quatro lições ficaram.

Percorrer a hierarquia tem custo

A trilha de auditoria adiciona overhead. Cada verificação de permissão pode percorrer a hierarquia: binding direto? Binding no recurso pai? Binding no Workspace? São três queries, ou uma só com um bom cache. Em escala, isso pesa. Não dá para evitar, só para planejar.

A fronteira entre identidade e autorização é borrada

Encontrei vários casos em que identidade e autorização se sobrepunham. Se o MFA está ativo, isso muda a avaliação de permissão? Se a sessão expira, os pedidos de permissão pendentes devolvem a decisão anterior ou dão erro? Onde termina a autenticação e começa a autorização? Essas perguntas não são teóricas. Elas definem como você organiza o código.

Hierarquia de papéis faz falta depois

Implementei os papéis como listas planas de capacidades, sem herança. Se você cria um papel "Moderador" e um "Moderador Sênior" com um pouco mais de capacidades, acaba duplicando tudo. Isso não escala. Sistemas de produção precisam de hierarquia de papéis ("Moderador Sênior estende Moderador"), mas isso complica o PDP. Aprendi construindo, não lendo.

Convex é ótimo para desenvolver, mas não para este produto em produção

Escolhi o Convex pela reatividade em tempo real e por não precisar sincronizar nada na mão. Para construir rápido, é excelente. Para um sistema de autorização que qualquer pessoa deveria poder hospedar por conta própria, é um problema: um sistema feito para rodar em qualquer lugar não deveria depender de um serviço gerenciado proprietário.

Essa tensão continua sem solução. Se o GateKey for para produção, vou revisitar a escolha do Convex. O caminho provável é trocar por Postgres com um ORM que suporte queries reativas, ou aceitar o lock-in como um trade-off explícito.

Com essas lições na mesa, fica mais fácil dizer o que o GateKey é hoje, e o que ele não é.

O Que o GateKey É Hoje

O GateKey é um sistema de autorização completo. Tem autenticação (MFA e magic links), bindings com escopo por recurso, multi-tenancy, atualização em tempo real, auditoria de acesso e uma interface funcionando. O código está aberto no GitHub.

Ele não substitui o Keycloak, que é muito mais completo. Também não é uma alternativa direta ao Auth0, porque não tem oferta SaaS e nunca vai ter para ninguém além de mim. Ele ocupa um espaço específico: engenheiros que querem entender como autorização funciona, que estão dispostos a aprender o sistema e que estão no nicho em que "sistema completo na minha infraestrutura" vale mais do que "SaaS gerenciado".

O que ele deliberadamente não é

  • Não é uma solução de auth de uso geral. A maioria dos apps não precisa de ReBAC. Para esses, use Auth0 ou Supabase.
  • Não é self-hosted no sentido tradicional. A interface e a lógica rodam em qualquer lugar, mas os dados ficam no Convex. É uma limitação concreta.
  • Não está "pronto". Funciona, mas os padrões de produção (hierarquia de papéis, cache em larga escala, requisitos complexos de auditoria) não foram explorados por completo.
  • Não é mínimo. Inclui recursos de autenticação (MFA, magic links) que, a rigor, um sistema de autorização não deveria ter. Estão lá porque sistemas de produção precisam deles.

Para quem ele funciona

  • Engenheiros construindo o próprio sistema de autorização que querem uma implementação de referência.
  • Times que entendem autorização a fundo e querem ser donos da implementação.
  • Produtos que precisam de controle granular multi-tenant e conseguem absorver a complexidade.
  • Quem quer aprender ReBAC construindo, não só lendo.

Ele não funciona para startups que precisam lançar rápido, para times pequenos sem experiência em autorização nem para quem quer um auth do tipo "configura e esquece".

Conclusão

Este post não foi um tutorial. Foi um estudo de caso, e a diferença importa. Um tutorial mostraria "é assim que o ReBAC funciona", com exemplos isolados. Um estudo de caso mostra o que acontece quando você decide entender um conceito a ponto de construir um sistema inteiro em volta dele.

O aprendizado não esteve na teoria do Zanzibar. Esteve em descobrir que a teoria não trata de expiração de sessão, trilha de auditoria, invalidação em tempo real, nem do fato de que pessoas não criam bindings em padrões limpos e fáceis de testar. Sistemas em uso são mais bagunçados, e entender isso exige construir.

Se você está pensando em construir o seu próprio sistema de autorização, comece por aqui:

  • Escreva uma especificação clara antes de qualquer código.
  • Construa uma feature completa por vez.
  • Teste a trilha de auditoria cedo. Ela é difícil de adicionar depois.
  • Aceite que a tecnologia escolhida (Convex, Postgres ou qualquer outra) vai limitar o seu design.
  • Documente as decisões, não para os outros, mas para você daqui a um ano.

Se você está avaliando sistemas de autorização para o seu produto, o GateKey pode servir de referência para estudo, mesmo que você escolha outra ferramenta. Entender o que existe dentro de um sistema de autorização faz de você um avaliador melhor dos que já estão no mercado.

Entender um conceito e entender um sistema são coisas diferentes. É a diferença entre ler sobre ReBAC e construir um. A segunda opção ensina mais e custa mais. Este projeto foi construído em cima desse trade-off.

Referências