Policy Lifecycle

Policy

At the core of Topaz’s authorization model is an authorization policy, which we refer to simply as a Policy. Policies are authored in a textual language called Rego, defined as part of the Open Policy Agent (OPA) project in the Cloud Native Computing Foundation.

Policies are treated just like application code or infrastructure-as-code - they can be stored as code in a git repository, or as an OCIv2 image in a policy repository like GitHub Container Registry, Docker Hub, Google Container Registry, or the Aserto Policy Registry.

The policy lifecycle

Policies are authored using a text / code editor, built into an image, published to a repository hosted on a registry, run in the Topaz authorizer, and consumed by an application.

Author

Policies are comprised of a collection of .rego files and .json files, which provide static data that can be part of the policy.

Build, tag and publish Policy images

The set of source files that comprise a policy are built into a Policy Image using a set of tools that are modeled after the docker toolset. You can build and tag a policy just like you build and tag a docker image.

There are two paths for managing the lifecycle of a policy image:

1. Using the policy CLI to build, tag and push a policy image to a policy registry.
2. Using GitHub, a build action automatically builds a new version of a policy image when the source repository is tagged with a new tag.

policy CLI

Login

echo $PAT | policy login -s <REGISTRY> -u <USERNAME> --password-stdin

For example, to login to the Github Container Registry, use the server name ghcr.io.

echo $GITHUB_PAT | policy login -s ghcr.io -u <username> --password-stdin

Note that the GITHUB_PAT must have the repo and write:packages scopes, as well as read:org for reading packages in other orgs, and delete:packages to be able to use policy rm -r to remove an image from a remote registry.

Create a policy

To create a sample policy, you can use the policy templates apply command:

policy templates apply policy-template

This will generate a minimal "hello world" policy, accompanied by the following output:

Processing template 'policy-template'

Generating files .

The template 'policy-template' was created successfully.

The generated directory structure should look like this:

tree -a .
.
├── README.md
└── src
    ├── .manifest
    └── policies
        └── hello-rego.rego

2 directories, 3 files

Build

To build a policy image, use the policy build command, with the directory containing the policy source (in the example above, ./src). You can specify a tag using the -t option:

policy build ./src -t my-org/my-policy:v0.1.2

Tip

If you get an error like rego_type_error: undefined function ds.check_relation, chances are you are building from a directory that does not contain a .manifest file that declares the Topaz built-ins.

You can tag any image by using the policy tag command:

policy tag my-org/my-policy:v0.1.2 my-org/my-policy:latest

Publish

To publish a built policy image to the policy registry, use the policy push command:

policy push my-org/my-policy:v0.1.2

Pull

Using the policy CLI, you can pull a policy image from a Policy Repository just like you pull a docker image.

policy pull my-org/my-policy:v0.1.2

For a complete reference on the policy CLI, refer to the policy CLI documentation.

Run

To run Topaz with the policy image, you first need to ensure the Topaz configuration file contains a reference to the policy. You can do this via the topaz config new command:

topaz config new -d -r my-org/my-policy:v0.1.2 -n my-policy

To start Topaz interactively:

topaz run 

To start Topaz as a daemon:

topaz start 

Configuration

The configuration file contains an opa section that defines the container registry service from where the policy image is obtained. This may need to be changed to match your registry service. Refer to the configuration section to learn how to match the configuration to your specific container registry service.

Consume

An application that wants to authorize a user's access to a resource based on the policy can call the policy instance, passing it the policy, decision(s), user context, and resource context, and the policy instance will evaluate the policy with the provided inputs and returns the boolean value(s) of the requested decision(s), allowing the application to definitively check whether the user has access to the resource based on the given policy.

The authz.is API is the underlying mechanism for an application to call the policy instance to make a decision. The language SDKs provide higher-level abstractions for interacting with policy instances.