Skip to content

aserto-dev/topaz

Repository files navigation

topaz logo

Topaz - cloud-native authorization for modern applications and APIs

Go Report Card ci Apache 2.0 GitHub release (latest SemVer) CII Best Practices

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.

topaz model visualization

Documentation and support

Read more at topaz.sh and the docs.

Join the community Slack channel for questions and help!

Benefits

  • Authorization in one place: a single authorization service, instead of spreading authorization logic everywhere.
  • Fine-grained: following the Principle of Least Privilege, assign the smallest set of fine-grained permissions to each user or group.
  • Policy-based: convert authorization "spaghetti code" into a policy expressed in its own domain-specific language, managed as code, and built into an immutable, signed artifact.
  • Real-time: gate each protected resource with an authorization call that ensures the user has the right permission.
  • Blazing fast: deploy the authorizer as a sidecar or microservice, right next to your app, for low latency and high availability.
  • Comprehensive decision logging: log every decision to facilitate audit trails, compliance, and forensics.
  • Flexible authorization model: Start simple, and grow from multi-tenant RBAC to ABAC or ReBAC, or a combination.
  • Capture your domain model: Create object types and relationships that reflect your domain model.
  • Separation of concerns: application developers can own the app logic, and security engineers can own the authorization policy.

Table of Contents

Getting Topaz

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 a GO install

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

Building from source

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:

  1. Install mage

  2. Clone the repo

  3. Build and run the executable

    mage build && ./dist/build_linux_amd64/topaz

Running with Docker

You can run as a Docker container:

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

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

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.

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.

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

Run the sample application

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.

Command line options

topaz --help
Usage: topaz <command> [flags]

Topaz CLI

Commands:
  start        start topaz in daemon mode
  stop         stop topaz instance
  restart      restart topaz instance
  status       status of topaz daemon process
  run          run topaz in console mode
  manifest     manifest commands
  test         test assertions commands
  templates    template commands
  console      open console in the browser
  import       import directory objects
  export       export directory objects
  backup       backup directory data
  restore      restore directory data
  install      install topaz container
  configure    configure topaz service
  certs        cert commands
  update       update topaz container version
  uninstall    uninstall topaz container
  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.

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

For more information on APIs, see the docs.

Demo

demo

Credits

Topaz uses a lot of great and amazing open source projects and libraries.

A big thank you to all of them!

Contribution Guidelines

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:

  • File an issue first prior to submitting a PR!
  • Ensure all exported items are properly commented
  • If applicable, submit a test suite against your PR