Setup
Installation
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
On Windows 10+
Download the
topaz_windows_x86_64.msi
file from the GitHub releases page and execute the MSI.Via a GO install
go install github.com/aserto-dev/topaz/cmd/topaz@latest
Quickstart
These instructions help you get Topaz up and running as the authorizer for a sample Todo app.
Install Topaz authorizer container image
The Topaz authorizer is packaged as a Docker container. You can get the latest image using the following command:
topaz install
Create a configuration
You can use the CLI to create a configuration file:
topaz configure -n <policy-name> -d -s -r <resource-url>
For example, this command creates a configuration file for the sample Todo policy image.
topaz configure -d -s -r ghcr.io/aserto-policies/policy-todo-rebac:latest -n policy-todo
The configuration file is generated in $HOME/.config/topaz/cfg
.
- the config instructs Topaz to create a local directory instance (
-d
) - when started, Topaz will seed the directory with default object types (
-s
) - the config references an authorization policy for a sample "Todo" app, retrieved from the Open Policy Registry as a container image
- the config is named "policy-todo"
For an in-depth look on the configuration section see topaz config
Start Topaz in interactive mode
topaz run
Import sample data
Once Topaz is running, you can load user data into the database using the Topaz CLI.
The CLI contains commands to create schema and import data. In this quickstart we'll import the users, groups, and relationships for the Todo sample app.
First, retrieve the "Citadel" json files, placing them in the current directory:
curl https://raw.githubusercontent.com/aserto-dev/topaz/main/assets/citadel/citadel_objects.json >./citadel_objects.json
curl https://raw.githubusercontent.com/aserto-dev/topaz/main/assets/citadel/citadel_relations.json >./citadel_relations.json
Import the contents of the file into Topaz directory. This creates the sample users (Rick, Morty, and friends); groups; and relations.
topaz import -i -d .
Issue an API call
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 a query
Issue a query 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"]
}
}'
gRPC Endpoints
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
Next steps
- Review a sample app in your favorite language
- Create your own policy
- Push your policy to a registry
- Start Topaz by pointing it to your new policy with
topaz configure
andtopaz start