Policy Structure Overview

This document outlines the format and structure of a Cerbos policy representing permissions and roles for API resources.

API Version

The schema defines the API version to ensure backward compatibility and structured development.

• apiVersion: The constant must align with api.cerbos.dev/v1.

Metadata

Use this section to define metadata such as descriptions and identifiers related to the policy:

• description: A brief overview of the policy.
• disabled: A boolean flag indicating if the policy is currently active.

Principal Policy

The principal policy provides definitions for user roles and their access rights.

Structure of Principal Policy

• principal: Identifies the principal entity (user, group, etc.).
• version: Version of the principal policy.

Example:

{
  "principal": "user123",
  "rules": [
    {
      "resource": "resourceName",
      "actions": ["read", "write"]
    }
  ],
  "scope": "global"
}

Resource Policy

The resource policy defines the actions and controls associated with specific resources.

Structure of Resource Policy

• resource: Identifies the resource being controlled (e.g., a database, file).
• rules: Outlines specific access rules for the resource.

Example:

{
  "resource": "document",
  "rules": [
    {
      "actions": ["view", "edit"],
      "effect": "EFFECT_ALLOW"
    }
  ]
}

Role Definitions

Define roles and their inheritance to facilitate a structured access control mechanism.

Structure of Role Definition

• name: The name of the role.
• parentRoles: A list defining any parent roles this role inherits from.

Example:

{
  "name": "admin",
  "parentRoles": ["user"]
}

Variables

Variables provide a mechanism to define dynamic elements within policies, allowing for flexible policies that can adapt to various contexts.

Structure of Variables

• import: Specifies variables that are imported from other schemas or definitions.
• local: Defines local variables that may be used within the policy as permissions.

Conclusion

This structured overview provides a path for creating detailed and robust access policies using the Cerbos framework, thus ensuring that defined permissions adhere to organizational security policies.