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.
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:
- Using the
policyCLI to build, tag and push a policy image to a policy registry.
- Using GitHub, a build action automatically builds a new version of a policy image when the source repository is tagged with a new tag.
echo $PAT | policy login -s <REGISTRY> -u <USERNAME> --password-stdin
For example, to login to the Github Container Registry, use the server name
echo $GITHUB_PAT | policy login -s ghcr.io -u <username> --password-stdin
Note that the GITHUB_PAT must have the
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 .
2 directories, 3 files
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
policy build ./src -t my-org/my-policy:v0.1.2
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
To publish a built policy image to the policy registry, use the
policy push command:
policy push my-org/my-policy:v0.1.2
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.
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 configure command:
topaz configure -d -r my-org/my-policy:v0.1.2 -n my-policy
To start Topaz interactively:
To start Topaz as a daemon:
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.
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.