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:
- Using the
policy
CLI 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.
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
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.