Connecting Synapse to Cerbos Hub

Cerbos Hub is the managed service for distributing, auditing and governing Cerbos policies. The in-process Cerbos PDP can source policies from Hub as optimized, versioned bundles and can send audit logs to Hub for centralised retention, search and analysis.

The audit trail Hub receives captures each request as the PDP evaluated it, including every attribute that Synapse’s proxy extensions added before the decision. Each entry is annotated with the Synapse version, the list of extensions that ran, and any custom instance metadata configured on the instance. The record therefore reflects the inputs that produced the decision, not only the inputs the client sent.

This page covers the Synapse-specific aspects of connecting to Hub. For account provisioning, policy authoring workflows, deployment management and playground usage, see the Cerbos Hub documentation.

Prerequisites

A Cerbos Hub account with at least one workspace.
A deployment or playground that provides the policy bundle.
Client credentials for the selected Hub source. Audit log collection requires Read & write deployment credentials.
Outbound HTTPS access to api.cerbos.cloud and cdn.cerbos.cloud on port 443. See Network requirements.

If you do not yet have a Hub account, sign up at hub.cerbos.cloud.

Policy distribution

Configure the in-process Cerbos PDP to use the hub storage driver and point it at a deployment:

pdp:
  inProcess:
    hub:
      credentials:
        clientID: "${CERBOS_HUB_CLIENT_ID}" (1)
        clientSecret: "${CERBOS_HUB_CLIENT_SECRET}"
        pdpID: "synapse-1" (2)

    storage:
      driver: "hub" (3)
      hub:
        remote:
          deploymentID: "YOUR_DEPLOYMENT_ID" (4)
          cacheDir: /var/lib/synapse/hub-cache (5)

1	Client credentials for the selected Hub source. The environment variables can be used instead of defining the fields in the configuration file.
2	Optional identifier for the PDP in Hub. A generated identifier is used when this value is omitted.
3	Use the `hub` storage driver.
4	The deployment ID from Hub. Use `playgroundID` instead when connecting to a playground.
5	Optional directory for caching policy bundles. The directory must exist before Synapse starts.

Only one of deploymentID or playgroundID may be set at a time. See Cerbos Hub storage for the complete storage configuration.

A hub section at the root of the Synapse configuration is ignored. Place it under pdp.inProcess.

Supplying credentials

Credentials can be configured under pdp.inProcess.hub.credentials or with environment variables. Store client secrets in the secret-management system provided by the deployment platform.

Variable Purpose

Variable	Purpose
`CERBOS_HUB_CLIENT_ID`	Client ID for the selected Hub source.
`CERBOS_HUB_CLIENT_SECRET`	Client secret paired with the client ID.
`CERBOS_HUB_PDP_ID`	Optional identifier for this Synapse instance. Defaults to a generated value.
`CERBOS_HUB_DEPLOYMENT_ID`	Optional deployment ID. Selects the `hub` storage driver and overrides the configured deployment ID.
`CERBOS_HUB_PLAYGROUND_ID`	Optional playground ID. Selects the `hub` storage driver and overrides the configured playground ID.

CERBOS_HUB_CLIENT_ID

Client ID for the selected Hub source.

CERBOS_HUB_CLIENT_SECRET

Client secret paired with the client ID.

CERBOS_HUB_PDP_ID

Optional identifier for this Synapse instance. Defaults to a generated value.

CERBOS_HUB_DEPLOYMENT_ID

Optional deployment ID. Selects the hub storage driver and overrides the configured deployment ID.

CERBOS_HUB_PLAYGROUND_ID

Optional playground ID. Selects the hub storage driver and overrides the configured playground ID.

When deploymentID is configured, the client credential must belong to that deployment. Policy store credentials cannot fetch deployment bundles. For playgroundID, use the connection details under Implement → Connect a PDP in the playground.

When running under Docker, pass the credentials through on the command line for local testing or through the orchestrator’s secret mechanism for production:

$ docker run --rm --name synapse -p 3594:3594 \
    -e CERBOS_HUB_CLIENT_ID \
    -e CERBOS_HUB_CLIENT_SECRET \
    -v $(pwd)/config.yaml:/config/config.yaml:ro \
    CERBOS_DISTRIBUTION_REPO/synapse/synapse:latest \
    server --conf.path=/config/config.yaml

Under the Helm chart, create a Kubernetes Secret containing the credentials and reference it from the chart’s envFrom configuration.

Selecting a deployment from the environment

Synapse applies CERBOS_HUB_DEPLOYMENT_ID and CERBOS_HUB_PLAYGROUND_ID before starting the in-process PDP. CERBOS_HUB_DEPLOYMENT_ID takes precedence if both variables are set.

Do not combine CERBOS_HUB_DEPLOYMENT_ID with a configured playgroundID, or CERBOS_HUB_PLAYGROUND_ID with a configured deploymentID. Both IDs remain set and prevent the PDP from starting.

A standalone Cerbos PDP uses these variables only when the corresponding configuration field is empty. The variables do not select the storage driver for a standalone PDP.

Audit logging to Hub

Hub can also receive the PDP’s audit trail. Configure the in-process Cerbos PDP to use the hub audit backend:

pdp:
  inProcess:
    audit:
      enabled: true
      backend: hub
      hub:
        storagePath: /var/lib/synapse/audit (1)
        mask: (2)
          metadata:
            - authorization
          checkResources:
            - inputs[*].principal.attr.ssn

1	Local buffer for audit entries awaiting delivery. Use persistent storage so buffered entries survive container restarts.
2	Optional field masks that remove sensitive data from audit entries before they are sent to Hub.

Each audit entry that Hub receives contains two records per request:

An access entry with the caller identity, transport metadata and method name.
A decision entry with the request inputs, evaluation outputs, matched policies and decision reasons.

The inputs recorded in the decision entry are the inputs after proxy extensions have run. If an extension fetched a principal’s department from an internal directory and added it as an attribute, that attribute appears in the audit record. The Hub console supports searching and filtering decisions on these enriched attributes.

See Hub audit log collection for field masking and other audit options.

Context added by Synapse

Synapse annotates each request’s requestContext before it reaches the PDP, and those annotations flow through to every audit entry Hub ingests. Three categories are added automatically:

Annotation key Value Source

Annotation key	Value	Source
`cerbos.dev/synapse/version`	The running Synapse version.	Always added.
`cerbos.dev/synapse/extensions`	The list of proxy extension names that processed this request, in the order they ran.	Added whenever one or more proxy extensions are configured.
your custom keys	Arbitrary string, number or boolean values.	Populated from the `audit.instanceAnnotations` section of the Synapse configuration.

cerbos.dev/synapse/version

The running Synapse version.

Always added.

cerbos.dev/synapse/extensions

The list of proxy extension names that processed this request, in the order they ran.

Added whenever one or more proxy extensions are configured.

your custom keys

Arbitrary string, number or boolean values.

Populated from the audit.instanceAnnotations section of the Synapse configuration.

Custom instance annotations are declared at the top level of config.yaml:

audit:
  instanceAnnotations:
    environment: "production"
    region: "eu-west-1"
    cluster: "auth-primary"

These annotations identify the Synapse instance that handled the call, the region or cluster it ran in, the Synapse version deployed at the time, and the extensions that contributed to the enriched request. When Hub is the audit destination, this context is searchable and filterable in the Hub console.

The same CERBOS_HUB_CLIENT_ID and CERBOS_HUB_CLIENT_SECRET credentials are used for policy distribution and audit logging. Audit log collection requires Read & write credentials.

Availability and monitoring

If the Hub connection is interrupted after startup, the PDP continues to evaluate requests with its current bundle and applies updates after reconnecting. The readiness endpoint reports PDP readiness rather than Hub connectivity.

Use the cerbos_dev_hub_connected metric to monitor the connection. See Cerbos Hub reliability for bundle distribution, caching and connectivity behavior.

Using Hub with an external Cerbos PDP

When Synapse is configured as a gateway in front of an existing Cerbos PDP fleet (pdp.external), Hub configuration lives on the upstream PDP, not on Synapse. Synapse itself does not need Hub credentials in that topology. It forwards authorization traffic to the PDP, and the PDP handles bundle fetching and audit shipping.

The top-level audit.instanceAnnotations setting remains available because Synapse adds those values before forwarding the request. See Cerbos Hub storage for configuring the external PDP.

Troubleshooting

Authentication failures at startup. Check that the client ID and client secret are available to the process and that the credentials belong to the configured deployment or playground.
Bundle not found. Verify the deployment or playground ID in Hub.
Bundle updates not applied. Confirm that disableAutoUpdate is unset or false, and monitor the Hub connection with cerbos_dev_hub_connected.
Configuration appears to be ignored. Confirm that hub, storage and audit are nested under pdp.inProcess.