Cerbos Policies

There are three kinds of Cerbos policies:

Derived roles

Traditional RBAC roles are usually broad groupings with no context awareness. Derived roles are a way of augmenting those broad roles with contextual data to provide more fine-grained control at runtime. For example, a person with the broad manager role can be augmented to manager_of_scranton_branch by taking into account the geographic location (or another factor) and giving that derived role bearer extra privileges on resources that belong to the Scranton branch.

Resource policies

Defines rules for actions that can be performed on a given resource. A resource is an application-specific concept that applies to anything that requires access rules. For example, in an HR application, a resource can be as coarse-grained as a full employee record or as fine-grained as a single field in the record.

Principal policies

Defines overrides for a specific user.

Policies are evaluated based on the metadata passed in the request to the Cerbos PDP. See Cerbos API for more information.

View the latest documentation and example requests by accessing a running Cerbos instance using a browser (e.g. http://localhost:3592/). The OpenAPI (Swagger) schema can be obtained by accessing /schema/swagger.json as well.

Policy authoring tips

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

  • 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. E.g. app:component:resource.

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

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

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