Policy authoring

Tips for working with policies

• Policies can be in either YAML or JSON formats. Accepted file extensions are .yml, .yaml or .json. All other extensions are ignored.

• The JSON schemas for Cerbos files are available at:

• Policy

• https://api.cerbos.dev/v0.32.0/cerbos/policy/v1/Policy.schema.json

• Test suite

• https://api.cerbos.dev/v0.32.0/cerbos/policy/v1/TestSuite.schema.json

• Principal test fixtures

• https://api.cerbos.dev/v0.32.0/cerbos/policy/v1/TestFixture/Principals.schema.json

• Resources test fixtures

• https://api.cerbos.dev/v0.32.0/cerbos/policy/v1/TestFixture/Resources.schema.json

• Auxiliary data test fixtures

• https://api.cerbos.dev/v0.32.0/cerbos/policy/v1/TestFixture/AuxData.schema.json

• If you prefer to always use the latest version, they can be accessed at:

• https://api.cerbos.dev/latest/cerbos/policy/v1/Policy.schema.json

  • https://api.cerbos.dev/latest/cerbos/policy/v1/TestSuite.schema.json
  • https://api.cerbos.dev/latest/cerbos/policy/v1/TestFixture/Principals.schema.json
  • https://api.cerbos.dev/latest/cerbos/policy/v1/TestFixture/Resources.schema.json
  • https://api.cerbos.dev/latest/cerbos/policy/v1/TestFixture/AuxData.schema.json

Policy structure

• The policy header is common for all policy types:

• apiVersion: Required. Must be api.cerbos.dev/v1.

  • description: Optional. Description of the policy.
  • disabled: Optional. Set to true to make the Cerbos engine ignore this policy file.
  • metadata.sourceFile: Optional. Set to the source of the policy data for auditing purposes.
  • metadata.annotations: Optional. Key-value pairs of strings holding free-form data for auditing purposes.

• Resource names, actions, and principal names can be hierarchical. Use : as the delimiter. For example: app:component:resource.

• Wildcard matches are allowed on certain fields. Wildcards respect the hierarchy delimiter :.

• Scoped policies (optional) are handy for use cases like multi-tenancy where you may want to override particular rules for some tenants.

• See Conditions to learn how to write conditions in policy rules.

• See Schemas to learn how you can define schemas for validating requests.

• See Best practices to check out a growing collection of snippets detailing the optimal way to write policies.

Editing policies

The quickest and the easiest way to get familiar with Cerbos policies is to use the online playground. It provides an IDE-like experience with an interactive editor, examples, code snippets, test cases and other useful utilities to help you design policies.

Editor configurations

Editors with support for the Language Server Protocol (LSP) can make use of the YAML language server implementation when working with Cerbos policies. Simply add the following line at the beginning of your policy file to get context-sensitive code suggestions and validation messages from the editor.

# yaml-language-server: $schema=https://api.cerbos.dev/latest/cerbos/policy/v1/Policy.schema.json

Neovim

Refer to your plugin manager documentation to figure out how to install nvim-lspconfig and configure the yaml-language-server. Plugins such as mason-lspconfig can automatically download and install language servers as well.

JetBrains IDEs

Navigate to the Languages & Frameworks Schemas and DTDs JSON Schema Mappings in JetBrains IDE of your choice.

Add an entry with the following configuration:

Name: Cerbos
Schema file or URL: https://api.cerbos.dev/latest/cerbos/policy/v1/Policy.schema.json
Schema version: JSON Schema Version 7
File path pattern: cerbos/*

Visual Studio Code

If you are new to Visual Studio Code, refer to the documentation for more information about how to change settings.

Install the YAML language server extension from https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml

After the extension is installed, hit Ctrl + , or Preferences Settings to edit settings. Expand YAML, click Edit in settings.json under Yaml: Schemas. and add the following snippet:

{
  "yaml.schemas": {
    "https://api.cerbos.dev/latest/cerbos/policy/v1/Policy.schema.json": "cerbos/*",
    "https://api.cerbos.dev/latest/cerbos/policy/v1/TestSuite.schema.json": "/cerbos/**/*_test.yaml",
    "https://api.cerbos.dev/latest/cerbos/policy/v1/TestFixture/Resources.schema.json": "/cerbos/**/testdata/resources.yaml",
    "https://api.cerbos.dev/latest/cerbos/policy/v1/TestFixture/Principals.schema.json": "/cerbos/**/testdata/principals.yaml",
    "https://api.cerbos.dev/latest/cerbos/policy/v1/TestFixture/AuxData.schema.json": "/cerbos/**/testdata/auxdata.yaml"
  }
}