Engine block

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 \