Topaz authorization: OPA and Zanzibar-style directory

Topaz's authorization boundary for applications and APIs

Topaz is an open-source authorization service for applications and APIs that need access decisions based on more than a simple role name. The README positions it for teams that want to remove scattered permission checks from application code and place those decisions behind a service interface. Its intended users include application developers who own product behavior and security engineers who own authorization policy.

The project supports a policy model that can combine user attributes, group membership, application resources, and relationships between those entities. The README describes movement from multi-tenant RBAC toward ABAC or ReBAC, or a combination of those models. This matters when a conventional role check cannot express whether a person may act on a particular document, project, tenant, or other domain object.

Topaz is not presented as only an API gateway or only a policy library. It is an authorizer that applications can call when they need to determine whether a subject can perform an operation. The README says the service can run as a sidecar or microservice near an application. That deployment choice makes network availability and failure behavior part of the adoption decision, rather than leaving authorization entirely inside each application process.

The repository is licensed under Apache-2.0. The license is relevant to organizations reviewing whether the code can be incorporated into an internal authorization platform, subject to the license terms and organizational compliance requirements. The README does not interpret those license terms or provide legal guidance.

How OPA evaluates Topaz directory data

Topaz uses Open Policy Agent as its decision engine. OPA evaluates authorization policy written in its policy language, while Topaz supplies the service and directory around that evaluation. This creates a recognizable policy boundary: policy authors work with OPA rules, and application code consumes authorization decisions through the Topaz interface.

The directory is inspired by the Google Zanzibar data model. The README explains that authorization data is modeled and stored locally in an embedded database. Objects represent application resources, relations describe relationships, and attributes and group membership can contribute to decisions. The Todo template makes this concrete by including object and relation files, a manifest, users, and groups.

This differs from storing every authorization record only in the calling application. With Topaz, the relevant users, groups, objects, and relationships are held by the authorization service. A request can therefore be evaluated against a shared directory and a policy artifact rather than reconstructing the same graph in each service. The README does not specify the embedded database engine, capacity limits, or replication behavior, so those details require separate documentation before Topaz becomes a system of record for a large workload.

Policy delivery also has a distinct packaging model. The Todo configuration references a policy image, described as an OCI image containing OPA policy. The repository therefore treats policy as a deployable artifact rather than an informal collection of checks. The README mentions signed artifacts, but it does not show the signing workflow or key-management procedure.

Installing Topaz and loading the Todo template

Topaz is available as binaries for Linux, Windows, and macOS. The README also gives Homebrew and Go installation routes. For a developer who wants the command-line tool on a supported machine, the documented Go installation is:

$ go install github.com/aserto-dev/topaz/topaz@latest

After that, the Quickstart uses the Topaz CLI to install its container image. This operation requires access to a Docker daemon. The README specifically calls out Docker Desktop socket permissions if the daemon cannot be reached:

$ topaz install

The next step installs the Todo policy, domain manifest, and sample authorization data into the local Topaz configuration directory:

$ topaz templates install todo

The README says the artifacts appear under `$HOME/.config/topaz/`. It lists `cfg/todo.yaml`, `todo/data/`, `todo/model/manifest.yaml`, and `topaz.json`. The data directory contains sample objects and relations, including five users and four groups based on Rick & Morty. The template helps show how a policy, manifest, and data set fit together, but those sample records are not production application data.

For a source build, the README lists the build and execution commands:

$ make build
$ ./dist/topaz_<os>_<arch>/topaz

It states that `make build` targets the host platform by default and that `GOOS` and `GOARCH` can select another target. The exact output directory is reported in the build log or in `dist/artifacts.json`. A documented Docker invocation is also available:

$ docker run -it --rm ghcr.io/aserto-dev/topaz:latest --help

The README excerpt stops before showing the complete authorization request and sample application commands. It identifies gRPC endpoints as part of the documentation, but it does not provide a complete request body or response example. That omission matters for a first integration because installation alone does not show how a caller specifies the subject, resource, action, and policy context.

Topaz repository components and version requirements

The repository is written primarily in Go and contains multiple command packages or binaries, including `topaz`, `topazd`, `topaz-backup`, and `topaz-db` directories. The Dockerfile copies the authorizer, daemon, and backup components into an Alpine image. It declares volumes for `/config`, `/certs`, `/db`, and `/decisions`, then starts `./topazd` with `run -c /config/config.yaml`.

The current `go.mod` gives the module identity as `github.com/aserto-dev/topaz` and requires Go `1.27.1`. It includes OPA `v1.21.1`, gRPC and gateway packages, OpenAPI packages for the authorizer and directory, and AuthZEN access packages. This is a substantial dependency surface for a service that may sit in the request path. An upgrade may therefore require more than replacing an application binary because database data, certificates, policy images, generated interfaces, and configuration files can all participate in deployment.

There is a documentation inconsistency to resolve before building from source. The README says Topaz is currently using Go `1.22.*` to compile, while the repository's `go.mod` declares `go 1.27.1`. The README also says the `go.mod` files are pinned to `1.21` or lower, which does not match the displayed file. A developer should treat the checked-out `go.mod` and current build documentation as items to reconcile rather than assuming the README version statement is current.

The repository is not archived. Its last push was on 2026-10-14, and recent releases include `v0.33.22` on 2026-09-28, `v0.33.21` on 2026-09-28, and `v0.33.20` on 2026-09-09. The release history shows recent development, but it does not establish upgrade compatibility or the operational cost of moving between versions.

Topaz failure modes and unsuitable workloads

Topaz introduces a networked control point. An application that calls an authorizer must handle the availability and latency of that service, along with what happens when a decision cannot be obtained. The README recommends sidecar or microservice deployment, but it does not define fail-open or fail-closed behavior for each operation. Teams should establish their expected behavior from the service documentation and configuration before relying on Topaz for emergency access decisions.

It is also a poor fit when authorization is only a small set of static rules already owned by one application. Running OPA, a directory, certificates, policy artifacts, and decision logs can add deployment and maintenance work without improving the decision model. A local policy evaluation or application-level permission table may be easier to inspect and operate for a narrow system.

The embedded local database is another boundary. The README confirms local storage, but it does not provide details about clustering, replication, backup validation, or recovery objectives. Topaz should not be treated as a distributed authorization graph until those operational questions are answered. The repository contains `topaz-backup`, which indicates that backup functionality exists, but the README does not document its schedule, restore procedure, or consistency guarantees.

The service also requires policy authors who can work with OPA and a domain manifest. The Todo template demonstrates the structure, yet it does not remove the need to define ownership, object types, relationships, and policy rules for the actual application. A correct relationship model is as important as a correct policy expression.

Topaz versus direct OPA and local permission checks

A direct Open Policy Agent integration can provide policy evaluation without adding Topaz's directory and authorization service layer. The application would load OPA policy and supply the input required by its rules. That approach keeps the policy engine close to the caller and can be simpler when the application already owns all users, groups, and resources.

Topaz takes a different approach. It packages OPA with a directory inspired by Zanzibar, a shared authorization interface, local relationship data, and a policy-image delivery model. The trade-off is a larger operational boundary in exchange for centralized access decisions and a reusable relationship model. Direct OPA is the better candidate when policy is small and the application already has a trusted data source. Topaz is more relevant when several application services need a common authorization service and their decisions depend on shared objects and relationships.

Compared with application-local permission checks, Topaz centralizes policy and data but introduces network failure modes. Compared with a policy engine used directly, it adds a directory and service conventions. Neither alternative wins in every situation. The choice depends on whether shared domain relationships and separate policy ownership justify operating another service.

Managing Topaz policies, certificates, and decisions

The Dockerfile shows runtime directories that deserve attention in deployment planning. `/config` stores configuration, `/certs` holds certificate material, `/db` is the database volume, and `/decisions` receives decision output. It also sets `TOPAZ_RUNNING_IN_CONTAINER=true`, which indicates container operation to the runtime.

The Todo template configuration references `ghcr.io/aserto-policies/policy-todo:latest`. That creates a dependency on a public policy image, so a deployment should decide whether to consume it as documented or maintain an internally controlled policy artifact. The README calls policies immutable and signed, but it does not provide commands for signature verification.

Decision logging is listed as a feature for audit trails, compliance, and forensics. The README does not document retention controls, access permissions, a structured log schema, or volume controls for `/decisions`. Those are operational details that cannot be inferred from the existence of a directory. They should be checked against the service documentation and local security requirements.

The API side includes gRPC endpoints, and the `go.mod` includes gRPC gateway and OpenAPI packages. This indicates that Topaz is not limited to one command-line interface, but the README excerpt does not enumerate the endpoint contracts. Teams should verify the exact API surface before writing an SDK or reverse proxy integration.

Editorial conclusion

Adopt Topaz when application developers and security engineers want a separate, policy-driven authorization service backed by OPA and shared relationship data. Do not choose it for a small application that can enforce authorization locally without another service. First verify the Go toolchain required by the current `go.mod`, the certificate and storage configuration, and the availability of a policy that matches your domain. The repository was not archived and its last push was on 2026-10-14.

Frequently asked questions

Official sources

1. aserto-dev/topaz on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases