O Topaz é um serviço de autorização escrito em Go. Ele “uses the Open Policy Agent (OPA) as its decision engine, and provides a built-in directory that is inspired by the Google Zanzibar data model” (usa o Open Policy Agent (OPA) como seu mecanismo de decisão e oferece um diretório embutido inspirado no modelo de dados do Google Zanzibar) (README). Uma decisão é tomada por uma política Rego; a política pode perguntar ao diretório se uma relação ou permissão vale entre um sujeito e um objeto, que é a parte que se assemelha ao Zanzibar. Os dados do diretório são “modeled and stored locally in an embedded database” (modelados e armazenados localmente em um banco de dados embarcado) (mesmo README).
O Topaz foi construído pela Aserto. Em 2025-04-27, a Aserto anunciou que estava “sunsetting the Aserto SaaS control plane and will shut it down by May 31, 2025” (descontinuando o plano de controle SaaS da Aserto, que seria desligado até 31 de maio de 2025), que iria “wind down Aserto as a commercial entity” (encerrar a Aserto como entidade comercial) e que “we have a set of maintainers that will continue to support Topaz” (temos um grupo de mantenedores que continuará a dar suporte ao Topaz) (blog da Aserto, de autoria do fornecedor). Novas versões continuaram a sair desde então. Os 30 commits mais recentes no branch padrão, em 2026-11-13, são todos de um único autor, Gert Drapers, que também assinou a publicação sobre o encerramento (commits).
O artigo e o Topaz lado a lado
| No artigo | No Topaz |
|---|---|
| Configuração de namespace (§2.3) | Um tipo de objeto sob types no manifesto, um arquivo YAML com model: version: 3 (referência do manifesto) |
Tupla de relação object#relation@user (§2.1) |
Um registro de relação: object_type, object_id, relation, subject_type, subject_id e um subject_relation opcional |
_this |
Os registros armazenados de uma relação; a relação lista os tipos de sujeito que aceita, como viewer: user | group#member |
computed_userset |
Nomear outra relação ou permissão do mesmo tipo dentro de uma permissão |
tuple_to_userset |
A seta, como parent->can_read |
| União, interseção, exclusão | |, &, - |
| Zookie (§2.2, §2.4) | Nenhum documentado |
| Check (§2.4.4) | Reader.Check e Checks do diretório; decisões de política por meio de Authorizer.Is (reader.proto, authorizer.proto) |
| Read (§2.4.1) | Reader.GetRelation, GetRelations |
| Write (§2.4.2) | Writer.SetRelation, DeleteRelation (writer.proto); cargas em massa por meio de Importer.Import (importer.proto) |
| Watch (§2.4.3) | Nenhum na API do diretório |
| Expand (§2.4.5) | Nenhuma chamada Expand; Reader.GetGraph (“get object relationship graph”, obter o grafo de relacionamentos do objeto) é a mais próxima |
| Leopard (§3.2.4) | Nenhum equivalente documentado |
| Spanner (§3.1) | Um arquivo BoltDB embarcado (arquitetura) |
O exemplo recorrente como manifesto do Topaz
A Figura 1 do artigo torna os donos editores, os editores visualizadores, e os visualizadores da pasta pai visualizadores do documento (§2.3.1). Um manifesto do Topaz separa as relations, que contêm registros armazenados, das permissions, que são calculadas a partir de relações e de outras permissões.
model:
version: 3
types:
user: {}
group:
relations:
member: user
folder:
relations:
viewer: user | group#member
permissions:
can_read: viewer
doc:
relations:
parent: folder
owner: user
editor: user | group#member
viewer: user | group#member
permissions:
can_write: owner | editor
can_read: viewer | can_write | parent->can_read
group#member concede a relação a “everyone with the member relation to a specified group” (todos que têm a relação member com um group especificado), e a seta “allows a permission to be granted to subjects who have a specified relation or permission with another object” (permite conceder uma permissão a sujeitos que têm uma relação ou permissão especificada com outro objeto) (referência do manifesto). Os nomes devem ser minúsculos e ter no máximo 64 caracteres.
As cinco relações do exemplo recorrente, no formato JSON lines dos dados de exemplo dos mantenedores (gdrive_relations.jsonl):
{"object_type":"doc","object_id":"readme","relation":"owner","subject_type":"user","subject_id":"anne"}
{"object_type":"group","object_id":"eng","relation":"member","subject_type":"user","subject_id":"beto"}
{"object_type":"doc","object_id":"readme","relation":"viewer","subject_type":"group","subject_id":"eng","subject_relation":"member"}
{"object_type":"doc","object_id":"readme","relation":"parent","subject_type":"folder","subject_id":"A"}
{"object_type":"folder","object_id":"A","relation":"viewer","subject_type":"user","subject_id":"chen"}
Qual registro e qual expressão de permissão decidem o can_read de cada pessoa sobre o readme?
Observe que o diretório responde a essa pergunta sozinho, por meio de Reader.Check. A camada de políticas é o que o Topaz acrescenta por cima: uma regra Rego pode chamar o diretório e combinar a resposta dele com atributos da requisição.
Arquitetura
Onde uma decisão é executada, e onde ficam os dados de relacionamento?
- “The Authorizer exposes three APIs to the calling application” (o autorizador expõe três APIs à aplicação chamadora):
authz/is,authz/queryeauthz/decisiontree, cada uma “a POST or gRPC API” (uma API POST ou gRPC) (arquitetura). - As políticas alcançam o diretório por meio de built-ins do OPA, incluindo
ds.check,ds.check_relationeds.check_permission(mesma página). - “The directory is implemented as a BoltDB instance” (o diretório é implementado como uma instância do BoltDB) (mesma página). “Directory objects are loaded on-demand, in contrast to
data.jsonfiles” (os objetos do diretório são carregados sob demanda, ao contrário dos arquivosdata.json), que são carregados junto com a política. - “The authorizer captures and stores decision logs for every decision that it evaluates” (o autorizador captura e armazena logs de decisão para cada decisão que avalia) (mesma página).
- O Topaz pode ser implantado “as a sidecar or a microservice in your cloud” (como sidecar ou microsserviço na sua nuvem) (introdução).
Consistência
O zookie do artigo permite que um cliente peça uma verificação “at a consistent snapshot no earlier than the given zookie” (em um snapshot consistente não anterior ao zookie fornecido) (§2.4.4). O Topaz não documenta nada comparável: as páginas de referência do manifesto e de arquitetura não fazem nenhuma afirmação sobre consistência, e as mensagens Reader e Writer do diretório não carregam nenhum campo de token ou de snapshot (reader.proto, writer.proto). Uma verificação lê o arquivo BoltDB da instância do Topaz em que é executada. Como várias instâncias compartilham ou copiam dados não está descrito nas páginas consultadas aqui.
Diferenças em relação ao artigo
- Política em primeiro lugar. A API de decisão é
Is, que avalia uma política Rego; a verificação no estilo do Zanzibar é uma das entradas que a política pode usar. No artigo, o Check sobre o userset é a decisão (§2.4.4). - Armazenamento local e embarcado. Um arquivo BoltDB por instância, em vez do Spanner replicado pelo mundo (§3.1).
- Sem zookie, Watch ou Leopard. Nenhum deles está documentado.
- Curingas.
viewer: user | user:*permite uma relação com o sujeito de ID*(referência do manifesto). - Logs de decisão. Toda decisão é registrada para auditoria, o que o artigo não descreve para o Zanzibar.
Situação
- Primeira versão v0.20.3 em 2022-10-25; mais recente v0.33.28 em 2026-11-14; último commit no branch padrão em 2026-11-14; cerca de 1,4 mil estrelas (versões, API do GitHub, 2026-11-15).
- A Aserto anunciou seu encerramento em 2025-04-27 e o fim de seu plano de controle SaaS até 2025-05-31; os mantenedores continuam o Topaz (blog da Aserto). O repositório ainda fica sob a organização
aserto-dev.
Fontes
- Repositório e README do Topaz: github.com/aserto-dev/topaz
- Documentação do Topaz, introdução: topaz.sh/docs/intro
- Arquitetura: topaz.sh/docs/architecture
- Referência do manifesto: topaz.sh/docs/directory/manifest-reference
- Manifesto e relações de exemplo: manifest.yaml, gdrive_relations.jsonl
- API do diretório: reader.proto, writer.proto, importer.proto
- Commits recentes: github.com/aserto-dev/topaz/commits/main
- API do autorizador: authorizer.proto
- Encerramento da Aserto: aserto.com/blog/the-final-chapter-for-aserto