Skip to main content

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​

  1. Review a sample app in your favorite language
  2. Create your own policy
  3. Push your policy to a registry
  4. Start Topaz by pointing it to your new policy with topaz configure and topaz start