Engine block

This documentation is for an as-yet unreleased version of Cerbos. Choose 0.40.0 from the version picker at the top right or navigate to https://docs.cerbos.dev for the latest version.

Default policy version

Cerbos policies have a version field to support use cases such as having different policies for different environments (production, staging etc.) or for gradual rollout of a new version of an application. By default, when a request does not explicitly specify the policy version, the Cerbos engine attempts to find a matching policy that has its version set to default. You can change this fallback value by setting the defaultPolicyVersion. For example, if you have a Cerbos deployment for your staging environment, you may want to set defaultPolicyVersion: staging to ensure that the default policies in effect are the ones versioned as staging.

engine:
  defaultPolicyVersion: "default"

Globals

Global variables are a way to pass environment-specific information to policy conditions. For example, you might want to grant additional permissions to a role in your staging environment, without creating separate policy versions for different environments.

engine:
  globals:
    environment: "staging"

Values set in globals can then be referenced in policy conditions:

rules:
  - actions:
      - view
    effect: EFFECT_ALLOW
    roles:
      - developer
    condition:
      match:
        expr: globals.environment != "production"

As with other configuration settings, environment variables can be used to set global values.

engine:
  globals:
    environment: ${CERBOS_ENVIRONMENT:development}

Lenient scope search

When working with scopes, the default behaviour of the Cerbos engine is to expect that a policy file exists for the requested scope. For example, if the API request defines a.b.c as the scope, a policy file must exist in the policy repository with the a.b.c scope. This behaviour can be overridden by setting lenientScopeSearch configuration to true. When lenient scope search is enabled, if a policy with scope a.b.c does not exist in the store, Cerbos will attempt to find scopes a.b, a and `` in that order.

This setting only affects how Cerbos treats missing leaf scopes when searching for policies. The policies stored in your policy store must have unbroken scope chains (for example, if you have a scoped policy a.b.c in the store, the policy files for scopes a.b, a and `` must also exist).

engine:
  lenientScopeSearch: true