DOCSEARCHbyAlgolia
Submit Docs

Cerbos Documentation

website·Indexed 37 days ago

https://docs.cerbos.dev/

An Authorization-as-a-Service platform providing Policy as Code. Documentation covers configuration maps, identity integration, audit log management, policy lifecycle operations, and deployment as a sidecar container using cert-manager for certificate issuance.

Tokens
100.1K
Snippets
428
Records
602
Agent score
18%

What's inside Cerbos

  1. Overview of Cerbos policy types

    Cerbos provides six types of policies to manage access control:

    • Resource Policies: Define rules for actions on specific application resources (e.g., employee records).
    • Principal Policies: Define user-specific overrides that take precedence over resource policies.
    • Role Policies: Define additive constraints for roles via an allowActions list. They narrow access but cannot grant access not already allowed by a resource policy.
    • Derived Roles: Augment broad RBAC roles with contextual data (e.g., transforming manager to manager_of_scranton_branch) for fine-grained control.
    • Exported Variables: Define reusable variables for use in condition expressions across other policies.
    • Exported Constants: Define reusable constants for use in condition expressions across other policies.

  2. Overview of Synapse extension types

    Synapse provides four extension points to handle different integration problems during the authorization request lifecycle. Choosing the correct type depends on where the integration needs to occur:

    • Proxy Extensions: Intercept CheckResources and PlanResources requests/responses. Used for transparently enriching requests (e.g., fetching user department from IAM) or redacting response fields before they reach the caller.
    • Route Extensions: Register custom HTTP endpoints under /ext/ to translate non-Cerbos protocols into Cerbos authorization calls. Ideal for API gateways, query engines, or legacy apps that expect a specific request/response shape.
    • Envoy Extension: Natively implements the Envoy external authorization API. Allows Envoy proxies (or Istio, Gloo, Contour) to delegate authorization to Synapse without a translation layer.
    • Data Sources: Reusable, named lookup functions (e.g., a database lookup) that are called by other extensions via data_source_lookup(). This prevents duplicating integration logic across multiple extensions.

  4. Overview of Cerbos Synapse enrichment proxy

    Cerbos Synapse is a modular enrichment proxy that sits in front of the Cerbos PDP. It exposes the same Cerbos API (HTTP and gRPC) and can be deployed as a replacement for existing PDPs or as a standalone gateway.

    Synapse allows developers to configure request enrichment pipelines, integrate with third-party authorization APIs via HTTP handlers, and provide native Envoy external authorization support. It processes requests in three stages:

    1. Receives a CheckResources or PlanResources request.
    2. Runs proxy extensions to modify the request (e.g., adding attributes to the principal) or modify the response.
    3. Hands the augmented request to the PDP for policy evaluation.

    Synapse supports several extension types:

    • Native components supported by Cerbos.
    • Custom Starlark scripts (Python dialect).
    • WebAssembly (WASM) components.
    • Declarative mapping using Common Expression Language (CEL).

  5. Overview of Cerbos Policy Stores

    Policy stores are containers in Cerbos Hub that decouple policy storage from source control. They allow for:

    • Ownership: Separate stores per team, product, or environment.
    • Independent Cadence: Teams update stores without blocking others.
    • Layered Logic: Combine multiple stores in one deployment for a hierarchy of global guard rails and tenant overrides.
    • Source Agnostic Ingestion: Populate stores via Git (GitHub), CI/CD pipelines, Hub SDKs, cerbosctl CLI, or browser upload.

  6. Overview of Cerbos PDP Architecture

    Cerbos PDP is a standalone service that provides Authorization-as-a-Service using a 'Policy as Code' approach. Key characteristics include:

    • Centralized Decisions: Authorization logic is removed from application code and centralized in the PDP, returning simple ALLOW or DENY responses.
    • Policy as Code: Policies are defined as human-readable files, allowing updates to authorization rules without requiring code changes or service redeployments.
    • Identity Agnostic: Cerbos consumes identity information (principals) from any IdP (e.g., Auth0) or natively supports JWTs.
    • High Performance: The API is exposed via gRPC (with an HTTP gateway) and is designed for sidecar deployment in Kubernetes to minimize latency.

  7. Overview of Cerbos Hub platform components

    Cerbos Hub is an end-to-end authorization platform that manages the full lifecycle of authorization. It consists of the following core components:

    • Cerbos Hub (Policy Administration Point): The control plane used for authoring, testing, versioning, distributing policies, and viewing audits.
    • Cerbos Synapse: A data and integration layer that gathers identity and resource data from existing systems to provide context to the policy engine.
    • Cerbos PDP (Policy Decision Point): An open-source, stateless, high-performance authorization engine that evaluates requests against policies to return access decisions. It can scale horizontally.
    • Cerbos PEP SDKs (Policy Enforcement Point): Language-native client libraries that allow applications to connect to PDPs for real-time enforcement.

  8. Understand and use Synapse Proxy Extensions

    Proxy extensions in Synapse act as interceptors for Cerbos PDP requests (CheckResources and PlanResources) and their corresponding responses. They allow applications to send partial requests, which Synapse then processes through a sequence of extensions based on defined priority. Extensions can modify requests by adding, updating, or removing items before they reach the PDP, and similarly modify the PDP's response before it is returned to the caller.

    Key use cases include:

    • Centralizing the lookup of sensitive principal attributes for better security and performance.
    • Redacting sensitive information from responses.
    • Generating logs, metrics, and events for compliance.
    • Integrating with legacy data sources/sinks.
    • Updating attribute requirements or data providers without restarting applications.

  10. Configure AWS SAM template for Cerbos Lambda Extension

    Use the following AWS SAM template to define the Cerbos extension layer. The layer must be compatible with provided.al2 or provided.al2023 runtimes and arm64 architecture. The ContentUri should point to the directory containing the cerbosext binary.
    AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Cerbos server

Globals:
  Function:
    Timeout: 5

Resources:
  CerbosExtensionLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: cerbos-extension
      Description: Cerbos extension layer
      ContentUri: ./layer
      CompatibleRuntimes:
        - provided.al2
        - provided.al2023
      CompatibleArchitectures:
        - arm64

Outputs:
  CerbosExtensionLayerArn:
    Description: "Cerbos Extension Layer ARN"
    Value: !Ref CerbosExtensionLayer

  12. Apply best practices for Cerbos policy stores

    To maintain a scalable and secure policy architecture, follow these best practices:

    • Naming: Use responsibility-based names (e.g., security-global, payments-service, tenant-alpha).
    • Testing: Keep store-specific tests with the policies to catch regressions automatically on every change.
    • Security: Restrict write access and require reviews for stores feeding production deployments.
    • Isolation: Use dedicated stores for API-driven or user-defined policies to separate them from static files.
    • Composition: Periodically review deployments to ensure they reference only the necessary stores in the correct order.