Installing templates

Topaz includes some built-in templates to make it easy to get started.

A template references three types of artifacts:

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

Listing templates

topaz templates list lists the set of available templates.

Example:

topaz templates list

  NAME          DESCRIPTION                                                        DOCUMENTATION                                                                    
  peoplefinder  Corporate directory end-to-end sample                              https://docs.aserto.com/docs/getting-started/peoplefinder/peoplefinder-overview  
  todo          Todo application end-to-end sample                                 https://docs.aserto.com/docs/quickstarts/todo/overview                           
  simple-rbac   Simple RBAC authorization template                                 https://docs.aserto.com/docs/quickstarts/simple-rbac/overview                    
  gdrive        Authorization template for nested folders and documents            https://docs.aserto.com/docs/quickstarts/gdrive/overview                         
  slack         Authorization template for workspaces and channels                 https://docs.aserto.com/docs/quickstarts/slack/overview                          
  github        Authorization template for repositories, organizations and teams.  https://docs.aserto.com/docs/quickstarts/github/overview                         
  ...

Installing a template

topaz templates install installs a template. Note that this will replace the existing manifest and remove all existing data!

Example:

topaz templates install todo

Installing this template will completely reset your topaz configuration.
Do you want to continue? (y/N) y
>>> stopping topaz...
>>> stopping topaz "todo"...
>>> topaz is not running
>>> configure policy
certs directory: /Users/ogazitt/.local/share/topaz/certs

  FILE            ACTION
  gateway.crt     skipped, file already exists
  gateway-ca.crt  skipped, file already exists
  gateway.key     skipped, file already exists
  grpc.crt        skipped, file already exists
  grpc-ca.crt     skipped, file already exists
  grpc.key        skipped, file already exists
policy name: todo

Using configuration "todo"
>>> starting topaz "todo"...
9dd5a0fc176980e9eb6ebf3587a3d6fcc9334c5cc4cb7182f4da52103736115b


WARNING: delete manifest resets all directory state, including relation and object data
>>> delete manifest>>> set manifest to /Users/ogazitt/.local/share/topaz/tmpl/todo/model/manifest.yaml>>> importing data from /Users/ogazitt/.local/share/topaz/tmpl/todo/data
        objects 20
      relations 25

Artifacts

This command installs configuration artifacts in the Topaz configuration directory. To find out where this is, see configuration. Unless you've set $XDG_CONFIG_HOME, this should be $HOME/.config/topaz/.

tree $HOME/.config/topaz
/Users/ogazitt/.config/topaz
├── cfg
│   └── todo.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.
• topaz.json contains all the installed configurations, as well as other topaz defaults.

Data and template artifacts

The command also data and template artifacts in the Topaz data directory ($XDG_DATA_HOME/topaz), which defaults to $HOME/.local/share/topaz on Mac/Linux and $HOME\AppData\Local\topaz on Windows.

When Topaz starts, it will also create certificates in a certs directory under this path.

tree $HOME/.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.
that are based on the "Rick & Morty" cartoon.
* `db/todo.db` contains the embedded database which houses the model and data.
* `tmpl/todo/data/` contains the objects and relations that the template loads. The `citadel` files contain the users and groups associated with the "Citadel" demo IDP, and the `todo` files contain the template-specific objecs and relations.
* `tmpl/todo/model/manifest.yaml` contains the directory manifest for the Todo template.

Some templates also contain an `assertions/` subdirectory, which contains test cases for the model.

## Additional actions

Besides laying down the artifacts mentioned, installing the Todo template invoked the following actions:

* started Topaz in daemon (background) mode (see [starting Topaz](start)).
* set the manifest found in `tmpl/todo/model/manifest.yaml` (see [setting the manifest](manifest#setting-a-manifest)).
* imported the objects and relations found in `tmpl/todo/data/` (see [importing data](data#importing-objects-and-relations)).
* opened a browser window to the Topaz [console](https://localhost:8080/ui/directory) (see the [console](console)).