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 schema for Cerbos policies is available at https://api.cerbos.dev/v0.16.0/cerbos/policy/v1/Policy.schema.json. If you prefer to always use the latest version, it can be accessed at https://api.cerbos.dev/latest/cerbos/policy/v1/Policy.schema.json as well.

  • 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 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.

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

YAML language server also supports per-directory settings. If all your Cerbos policies are contained in a specific directory, you can configure the editor to always use the correct schema for the YAML files in that directory. Refer to the YAML language server documentation for more information.

Example: Apply the schema to all files in the /cerbos directory
yaml.schemas: {
    "https://api.cerbos.dev/latest/cerbos/policy/v1/Policy.schema.json": "/cerbos/*"
}

Neovim

Easiest way to get started is to install the lspcontainer.nvim plugin. With Packer, you can use a configuration similar to the following:

use({ 'lspcontainers/lspcontainers.nvim' })

use({
    'neovim/nvim-lspconfig',
    config = function()
        lspconfig = require "lspconfig"
        lspcontainers = require "lspcontainers"
        ...
        lspconfig.yamlls.setup {
            before_init = function(params)
                params.processId = vim.NIL
            end,
            cmd = lspcontainers.command('yamlls', { network = "bridge", }),
            root_dir = lspconfig.util.root_pattern(".git", vim.fn.getcwd()),
            on_attach = on_attach,
            capabilities = capabilities,
            settings = {
                yaml = {
                    schemas = {
                        "https://api.cerbos.dev/latest/cerbos/policy/v1/Policy.schema.json": "/cerbos/*"
                    },
                },
            },
        }
    end,
})

JetBrains IDEs

Navigate to the Preferences  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/*

JetBrains JSON Schema Mappings menu

In the example above, the schema is applied to all files in the cerbos directory.

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 File  Preferences  Settings to edit settings. Expand Extensions  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/*"
  }
}
In the example above, the schema is applied to all files in the cerbos directory.