Core Concepts - Cerbos

Overview

Cerbos authorization revolves around answering one key question:

Can this PRINCIPAL perform this ACTION on this RESOURCE?

Understanding these core concepts is essential to designing effective authorization policies with Cerbos.

Principal

A principal is the entity attempting to perform an action. Most commonly a user, but can represent:

Users (authenticated humans)
Service accounts
Applications
Bots or automated systems
IoT devices
Any identifiable actor

Principal Attributes

Principals have three key properties:

A unique identifier for the principal.

"id": "user_12345"

Roles

Static roles assigned to the principal (e.g., from your identity provider).

"roles": ["user", "manager", "admin"]

Attributes

Contextual information about the principal used in policy conditions.

"attr": {
  "department": "engineering",
  "region": "us-west",
  "subscription_tier": "premium",
  "beta_tester": true
}

Example Principal

{
  "principal": {
    "id": "[email protected]",
    "roles": ["user", "manager"],
    "attr": {
      "department": "engineering",
      "region": "us-west-2",
      "clearance_level": 3
    }
  }
}

Bring Your Own Identity: Cerbos doesn’t manage authentication. Use any identity provider (Auth0, Okta, AWS Cognito, custom JWT, etc.) and pass the principal information to Cerbos.

Action

An action is a specific operation a principal wants to perform. Actions are defined by you based on your application’s domain.

Common Action Patterns

CRUD Operations

create
read
update
delete

Custom Operations

approve
publish
archive
share
export
flag

Namespaced Actions

view:public
view:private
edit:metadata
edit:content

Wildcards

*           (all actions)
view:*      (all view actions)

Actions in Requests

Check multiple actions in a single request:

{
  "actions": ["read", "update", "delete", "share"]
}

Cerbos returns individual ALLOW/DENY decisions for each action.

Resource

A resource is the object or entity being accessed. Resources are organized by kind (type) and have individual instances with unique IDs.

Resource Structure

Resource Kind

The type or category of resource. Defines which policy to use.

kind: "document"
kind: "album:object"
kind: "expense_report"

Use namespacing like album:object or album:photo to organize related resource types.

Resource ID

The unique identifier for a specific resource instance.

id: "doc_12345"
id: "album_abc"

Resource Attributes

Contextual information about the resource used in policy conditions.

attr:
  owner: "[email protected]"
  status: "draft"
  public: true
  department: "engineering"
  created_at: "2024-01-15"

Example Resource

{
  "resource": {
    "kind": "expense_report",
    "id": "report_789",
    "attr": {
      "owner": "[email protected]",
      "status": "submitted",
      "amount": 2500,
      "department": "engineering"
    }
  }
}

Policies

Policies are YAML files that define authorization rules. They specify which principals can perform which actions on resources.

Policy Types

Cerbos supports three types of policies:

Resource Policies
Derived Roles
Principal Policies

Define rules for a specific resource kind. This is the primary policy type.

---
apiVersion: api.cerbos.dev/v1
resourcePolicy:
  resource: "expense_report"
  version: "default"
  rules:
    - actions: ['create', 'read']
      effect: EFFECT_ALLOW
      roles:
        - employee
    
    - actions: ['approve']
      effect: EFFECT_ALLOW
      roles:
        - manager
      condition:
        match:
          expr: request.resource.attr.department == request.principal.attr.department

Use for: Standard authorization rules that apply to all instances of a resource type

Dynamically assign roles based on context. Extend RBAC with attribute-based conditions.

---
apiVersion: "api.cerbos.dev/v1"
derivedRoles:
  name: common_roles
  definitions:
    - name: owner
      parentRoles: ["user"]
      condition:
        match:
          expr: request.resource.attr.owner == request.principal.id
    
    - name: dept_member
      parentRoles: ["employee"]
      condition:
        match:
          expr: request.resource.attr.department == request.principal.attr.department

Use for: Context-dependent roles that change based on resource attributes

Override rules for specific principals. Handle special cases and exceptions.

---
apiVersion: "api.cerbos.dev/v1"
principalPolicy:
  principal: "admin_user_123"
  version: "default"
  rules:
    - resource: "*"
      actions:
        - name: read_all
          action: "read"
          effect: EFFECT_ALLOW

Use for: User-specific overrides and exceptions to general rules

Policy Rules

Rules within policies have several components:

Actions

Which actions this rule applies to.

actions: ['read', 'update']
actions: ['*']  # all actions

Effect

Whether to allow or deny the action.

effect: EFFECT_ALLOW
effect: EFFECT_DENY

Roles or Derived Roles

Which roles this rule applies to.

roles:
  - user
  - manager

derivedRoles:
  - owner

Condition (Optional)

Additional attribute-based conditions for the rule.

condition:
  match:
    expr: |
      request.resource.attr.status == "draft" &&
      request.principal.attr.department == request.resource.attr.department

Policy Decision Point (PDP)

The Policy Decision Point (PDP) is the Cerbos service that evaluates policies and makes authorization decisions.

How the PDP Works

Load Policies

The PDP continuously monitors your policy storage location (disk, S3, Git, database) and loads policies into memory.

Receive Requests

Your application sends authorization requests via gRPC or HTTP to the PDP.

Evaluate Policies

The PDP matches the request against the appropriate policies, evaluates conditions, and determines the outcome.

Return Decision

The PDP returns EFFECT_ALLOW or EFFECT_DENY for each action requested.

PDP Characteristics

Stateless

No session state. Each request is independent. Scale horizontally.

Fast

In-memory evaluation. Sub-millisecond policy decisions.

Hot Reload

Detects policy changes automatically. No restart required.

Audit Logs

Optional decision logging for compliance and debugging.

Primary APIs

The PDP exposes two main APIs:

CheckResources
PlanResources

Check if a principal can perform actions on specific resources.Use case: “Can Alice delete document #123?”

Request

{
  "principal": { "id": "alice", "roles": ["user"] },
  "resources": [
    {
      "resource": { "kind": "document", "id": "123" },
      "actions": ["read", "delete"]
    }
  ]
}

Response

{
  "results": [
    {
      "resource": { "id": "123", "kind": "document" },
      "actions": {
        "read": "EFFECT_ALLOW",
        "delete": "EFFECT_DENY"
      }
    }
  ]
}

Get a query plan showing which resources a principal can access.Use case: “Which documents can Alice read?” (for database filtering)

Request

{
  "principal": { "id": "alice", "roles": ["user"] },
  "resource": { "kind": "document" },
  "action": "read"
}

Response

{
  "filter": {
    "kind": "CONDITIONAL",
    "condition": {
      "expression": {
        "operator": "or",
        "operands": [
          { "expression": { "operator": "eq", "operands": [{"variable": "owner"}, {"value": "alice"}] } },
          { "expression": { "operator": "eq", "operands": [{"variable": "public"}, {"value": true}] } }
        ]
      }
    }
  }
}

Use query plan adapters to convert this to SQL, Prisma, SQLAlchemy, etc.

RBAC vs ABAC

Cerbos supports both Role-Based Access Control (RBAC) and Attribute-Based Access Control (ABAC).

Role-Based Access Control (RBAC)

Simple role-based rules:

RBAC Example

rules:
  - actions: ['read', 'create']
    effect: EFFECT_ALLOW
    roles:
      - user
  
  - actions: ['delete']
    effect: EFFECT_ALLOW
    roles:
      - admin

Attribute-Based Access Control (ABAC)

Add conditions for fine-grained control:

ABAC Example

rules:
  - actions: ['approve']
    effect: EFFECT_ALLOW
    roles:
      - manager
    condition:
      match:
        expr: |
          request.resource.attr.amount < 10000 &&
          request.resource.attr.department == request.principal.attr.department

Evolution Path

Start with RBAC

Define simple role-based rules that are easy to understand and maintain.

Add Derived Roles

Introduce context-dependent roles like “owner” or “team_member”.

Layer on Conditions

Add attribute-based conditions for granular control without creating role explosion.

Handle Exceptions

Use principal policies for specific user overrides when needed.

Start simple with RBAC and evolve to ABAC as your authorization requirements become more complex.

Policy Storage

Cerbos supports multiple storage backends for policies:

Disk

Local filesystem. Great for development and small deployments.

Git

Pull policies from Git repositories. Ideal for GitOps workflows.

Cloud Storage

S3, GCS, Azure Blob. Scalable policy distribution.

Database

SQLite, PostgreSQL, MySQL. Dynamic policy management.

See Storage Configuration for details.

Putting It All Together

Here’s how all the concepts work together:

Define Your Model

Identify your principals (users, services), resources (documents, albums), and actions (read, write, share).

Write Policies

Create resource policies defining who can do what. Add derived roles for dynamic role assignment.

Deploy the PDP

Run Cerbos with your policies. Choose your deployment model (sidecar, service, Lambda).

Make Authorization Calls

From your application, call CheckResources to verify permissions or PlanResources to filter queries.

Iterate on Policies

Update policies as requirements change. The PDP reloads them automatically.

Next Steps

Try the Quickstart

See these concepts in action with a working example

Explore Policies

Learn policy authoring patterns and best practices

Deploy Cerbos

Choose the right deployment model for your infrastructure

Integration Guide

Integrate Cerbos into your application with SDKs

Questions? Join the Cerbos Slack community or check the full documentation.

Get Started

Installation

Deployment

Policies

Configuration

Operations

Integration

​Overview

​Principal

​Principal Attributes

​Example Principal

​Action

​Common Action Patterns

CRUD Operations

Custom Operations

Namespaced Actions

Wildcards

​Actions in Requests

​Resource

​Resource Structure

​Example Resource

​Policies

​Policy Types

​Policy Rules

​Policy Decision Point (PDP)

​How the PDP Works

​PDP Characteristics

Stateless

Fast

Hot Reload

Audit Logs

​Primary APIs

​RBAC vs ABAC

​Role-Based Access Control (RBAC)

​Attribute-Based Access Control (ABAC)

​Evolution Path

​Policy Storage

Disk

Git

Cloud Storage

Database

​Putting It All Together

​Next Steps

Try the Quickstart

Explore Policies

Deploy Cerbos

Integration Guide

Build docs developers (and LLMs) love

Overview

Principal

Principal Attributes

Example Principal

Action

Common Action Patterns

Actions in Requests

Resource

Resource Structure

Example Resource

Policies

Policy Types

Policy Rules

Policy Decision Point (PDP)

How the PDP Works

PDP Characteristics

Primary APIs

RBAC vs ABAC

Role-Based Access Control (RBAC)

Attribute-Based Access Control (ABAC)

Evolution Path

Policy Storage

Putting It All Together

Next Steps