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
  • Via WinGet for Windows 10+

    winget install Aserto.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. Before using the container image installer ensure that you have a Docker runtime such as Docker Desktop installed.

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.

docker settings

Install the todo template

Topaz has a set of pre-built templates that contain three types of artifacts:

  • an authorization policy
  • a domain model (in the form of a manifest file)
  • sample data (users, groups, objects, relationships)

You can use the CLI to install the todo template:

topaz templates install todo

Artifacts

This command will install the following artifacts in $HOME/.config/topaz/:

tree $HOME/.config/topaz
/Users/ogazitt/.config/topaz
├── certs
│   ├── gateway-ca.crt
│   ├── gateway.crt
│   ├── gateway.key
│   ├── grpc-ca.crt
│   ├── grpc.crt
│   └── grpc.key
├── cfg
│   └── config.yaml
├── data
│   ├── citadel_objects.json
│   └── citadel_relations.json
├── db
│   └── directory.db
└── model
└── manifest.yaml
  • certs/ contains a set of generated self-signed certificates for Topaz.
  • cfg/config.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.
  • 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.
  • db/directory.db contains the embedded database which houses the model and data.
  • model/manifest.yaml contains the manifest file which describes the domain model.
tip

For a deeper overview of the cfg/config.yaml file, see topaz config.

What just happened?

Besides laying down the artifacts mentioned, installing the Todo template did the following things:

  • started Topaz in daemon (background) mode (see topaz start --help).
  • set the manifest found in model/manifest.yaml (see topaz set manifest --help).
  • imported the objects and relations found in data/ (see topaz import --help).
  • opened a browser window to the Topaz console (see 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.

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 an authorization request

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"]
}
}'

gRPC Endpoints

To interact with the authorizer endpoint over gRPC, 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. Clone and run the Todo sample backend in your favorite language.
  2. Create your own directory manifest.
  3. Create your own policy.
  4. Push your policy to a registry.
  5. Start Topaz by pointing it to your new policy with topaz configure and topaz start.