Concepts

Client credentials

The policy decision points (PDPs) establish an authenticated connection to Cerbos Hub using a client ID and a secret. You can create a client credential using the settings section of Cerbos Hub.

Deployment label

Within a Workspace, you can define a set of labels which are aliases pointing to branches, tags or specific commits in your git repository. This allows you to have multiple versions of policies active at the same time. For example, you could have a production label that points to the trunk and a staging label that points to your work-in-progress branch. On every push to the git repository, Cerbos Hub determines the set of labels affected by that push and builds bundles for each of them. Each one of your on-premise PDPs must be configured with the name of a label to watch. Cerbos Hub takes care of distributing the correct bundles to each PDP based on the label they are configured to watch. The set of labels must be defined in a file named .cerbos-hub.yaml stored in the root of the default branch you defined when setting up the workspace.

Embedded Policy Decision Point (Embedded PDP)

Self-contained policy snapshots that can be embedded into any system that supports WebAssembly modules. This is a powerful solution for cases where authorization decisions have to be made locally on device or at the edge without access to a full-fledged Cerbos PDP. These embedded PDPs are generated as part of the CI pipeline as well and clients can download the latest version by accessing a specific URL for that deployment label.

Organization

An Organization serves as the top-level entity in Cerbos Hub and provides centralized control over billing, access control, and Workspace management. Typically a business would have one Organization and a number of Workspaces underneath it.

Policy bundle

An encrypted file containing optimised binary representations of policies corresponding to a git commit. On every commit to the policy repository, if the git reference of the commit matches a configured label, Cerbos Hub validates the policies in the new commit, runs tests if there are any and produces a policy bundle that is then pushed to all connected PDPs that are configured to watch that label.

Policy Decision Point (Service PDP)

The open source Cerbos server instances that you run in your own infrastructure are called service PDPs. Cerbos Hub is the management control plane for PDP instances that are running inside your environment. Rather than each PDP being responsible for detecting policy changes, parsing, compiling and loading them, they get pre-compiled policy bundles pushed to them from Cerbos Hub. This model ensures that all your data remains within your network perimeter and that authorization checks happen locally with low latency while reducing the overhead of policy updates and the time it takes for the whole fleet to get in sync. A PDP must be configured with the name of a label, workspace secret and client credentials in order to connect to Cerbos Hub.

Policy playground

A browser-based policy editor to quickly prototype, test and collaborate on Cerbos policies. An organization can have multiple playground instances and all authorized users of the organization have access to those instances.

Workspace

A Workspace represents a single Git policy repository. You can organize your workspaces to represent different teams, products, environments or any other method you use to manage your policy repositories. Once a workspace is connected to a GitHub repository, it cannot be changed.

Workspace secret

When creating a new workspace, Cerbos Hub generates a public/private key pair and presents you with the private key. This key is not saved on Cerbos Hub servers and will be shown only once. You must copy and store it securely. All your Workspace artifacts are encrypted using public key cryptography and they can only be decrypted using the secret key. If you lose the secret key, you have to generate a new one using the Settings menu of Cerbos Hub. Generating a new key will trigger a rebuild of all your bundles. Any PDPs using the old key will stop working when the new key becomes active. You have to update the PDPs with the new key to make them work again.