Topaz is an open-source authorization service providing fine-grained, real-time, policy-based access control for applications and APIs.
It 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.
Authorization policies can leverage user attributes, group membership, application resources, and relationships between them. All data used for authorization is modeled and stored locally in an embedded database, so authorization decisions can be evaluated quickly and efficiently.
Read more at topaz.sh and the docs.
Join the community Slack channel for questions and help!
topaz
is available on Linux, macOS and Windows platforms.
Binaries for Linux, Windows and Mac are available as tarballs in the release page.
Via Homebrew for macOS or LinuxBrew for Linux
brew tap aserto-dev/tap && brew install aserto-dev/tap/topaz
Via a GO install
go install github.com/aserto-dev/topaz/cmd/topaz@latest
topaz
is currently using golang v1.22.* to compile, go.mod
files are pinned to 1.21 or lower. In order to build topaz
from source you must:
Build and run the executable
make build && ./dist/build_linux_amd64/topaz
You can run as a Docker container:
docker run -it --rm ghcr.io/aserto-dev/topaz:latest --help
These instructions help you get Topaz up and running as the authorizer for a sample Todo app.
The Topaz authorizer is packaged as a Docker container. You can get the latest image using the following command:
topaz install
NOTE: If you get the following errors/warnings from Topaz commands:
Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
Be sure to allow the default Docker socket to be used in your Docker Desktop Advanced settings.
Topaz has a set of pre-built templates that contain three types of artifacts:
You can use the CLI to install the todo template:
topaz templates install todo
This command will install the following artifacts in $HOME/.config/topaz/
:
tree $HOME/.config/topaz
/Users/ogazitt/.config/topaz
├── cfg
│ └── todo.yaml
├── todo
│ ├── data
│ │ ├── citadel_objects.json
│ │ ├── citadel_relations.json
│ │ ├── todo_objects.json
│ │ └── todo_relations.json
│ └── model
│ └── manifest.yaml
└── topaz.json
cfg/todo.yaml
contains a Topaz configuration file which references the sample Todo policy image. A policy image is an OCI image that contains an OPA policy. For the Todo template, this is the public GHCR image ghcr.io/aserto-policies/policy-todo:latest
. The source code for the policy image can be found here.todo/data/
contains the objects and relations for the Todo template - in this case, a set of 5 users and 4 groups that are based on the "Rick & Morty" cartoon.todo/model/manifest.yaml
contains the manifest file which describes the domain model.tree ~/.local/share/topaz
/Users/ogazitt/.local/share/topaz
├── certs
│ ├── gateway-ca.crt
│ ├── gateway.crt
│ ├── gateway.key
│ ├── grpc-ca.crt
│ ├── grpc.crt
│ └── grpc.key
├── db
│ └── todo.db
└── tmpl
└── todo
├── data
│ ├── citadel_objects.json
│ ├── citadel_relations.json
│ ├── todo_objects.json
│ └── todo_relations.json
└── model
└── manifest.yaml
certs/
contains a set of generated self-signed certificates for Topaz.db/todo.db
contains the embedded database which houses the model and data.tmpl/todo
contains the template artifacts.For a deeper overview of the cfg/config.yaml
file, see topaz configuration.
Besides laying down the artifacts mentioned, installing the Todo template did the following things:
topaz start --help
).model/manifest.yaml
(see topaz manifest set --help
).data/
(see topaz directory import --help
).topaz console --help
).Feel free to play around with the Topaz console! Or follow the next few steps to interact with the Topaz policy and authorization endpoints.
To verify that Topaz is running with the right policy image, you can issue a curl
call to interact with the REST API.
This API call retrieves the set of policies that Topaz has loaded:
curl -k https://localhost:8383/api/v2/policies
Issue an authorization request using the is
REST API to verify that the user Rick is allowed to GET the list of todos:
curl -k -X POST 'https://localhost:8383/api/v2/authz/is' \
-H 'Content-Type: application/json' \
-d '{
"identity_context": {
"type": "IDENTITY_TYPE_SUB",
"identity": "rick@the-citadel.com"
},
"policy_context": {
"path": "todoApp.GET.todos",
"decisions": ["allowed"]
}
}'
To run the sample Todo backend in the language of your choice, and see how Topaz is used to authorize requests, refer to the docs.
To start an interactive session with the Topaz endpoints over gRPC, see the gRPC endpoints section.
topaz --help
Usage: topaz <command> [flags]
Topaz CLI
Commands:
run run topaz in console mode
start start topaz in daemon mode
stop stop topaz instance
restart restart topaz instance
status status of topaz daemon process
manifest manifest commands
templates template commands
console open console in the browser
directory (ds) directory commands
authorizer (az) authorizer commands
config configure topaz service
certs cert commands
install install topaz container
uninstall uninstall topaz container
update update topaz container version
version version information
Flags:
-h, --help Show context-sensitive help.
-N, --no-check disable local container status check ($TOPAZ_NO_CHECK)
-L, --log log level
Run "topaz <command> --help" for more information on a command.
To interact with the authorizer endpoint, install grpcui or grpcurl and point them to localhost:8282
:
grpcui --insecure localhost:8282
To interact with the directory endpoint, use localhost:9292
:
grpcui --insecure localhost:9292
For more information on APIs, see the docs.
Topaz uses a lot of great and amazing open source projects and libraries.
A big thank you to all of them!
Topaz is a work in progress - if something is broken or there's a feature that you want, please file an issue and if so inclined submit a PR!
We welcome contributions from the community! Here are some general guidelines: