Connecting Synapse to Cerbos Hub

Cerbos Hub is the managed service for distributing, auditing and governing Cerbos policies. Synapse’s embedded Cerbos PDP can source its policies from Hub as signed, versioned bundles, and can stream its audit logs into Hub for centralised retention, search and analysis. This is the recommended configuration for any Synapse deployment beyond local development.

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 published from the workspace. The deployment ID identifies the bundle that Synapse will fetch.
A set of Hub client credentials (client ID and client secret) scoped to the workspace.

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

Policy distribution

Configure the embedded PDP to use the hub storage driver and point it at a deployment:

pdp:
  inProcess:
    storage:
      driver: "hub" (1)
      hub:
        remote:
          deploymentID: "YOUR_DEPLOYMENT_ID" (2)

1	Use the `hub` driver. The embedded PDP authenticates to Hub, downloads the bundle matching the deployment and keeps it in sync.
2	The deployment ID from the Hub console at hub.cerbos.cloud. Use `playgroundID` instead when iterating on policies inside the Hub playground, before they are published as a deployment.

Only one of deploymentID or playgroundID may be set at a time.

Supplying credentials

Hub credentials are read from environment variables. Never place them in the configuration file.

Variable Purpose

Variable	Purpose
`CERBOS_HUB_CLIENT_ID`	Client ID for the Hub service account that will fetch the bundle.
`CERBOS_HUB_CLIENT_SECRET`	Client secret paired with the client ID.
`CERBOS_HUB_DEPLOYMENT_ID`	Optional. Overrides `storage.hub.remote.deploymentID` from the configuration file. Useful when the same container image runs against multiple deployments.
`CERBOS_HUB_PDP_ID`	Optional. Identifies this Synapse instance to Hub. Defaults to a generated value; set it explicitly when you want stable identification of instances in Hub audit views.

CERBOS_HUB_CLIENT_ID

Client ID for the Hub service account that will fetch the bundle.

CERBOS_HUB_CLIENT_SECRET

Client secret paired with the client ID.

CERBOS_HUB_DEPLOYMENT_ID

Optional. Overrides storage.hub.remote.deploymentID from the configuration file. Useful when the same container image runs against multiple deployments.

CERBOS_HUB_PDP_ID

Optional. Identifies this Synapse instance to Hub. Defaults to a generated value; set it explicitly when you want stable identification of instances in Hub audit views.

When running under Docker, pass them through on the command line (for local testing) or via 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.

Audit logging to Hub

Hub can also receive the PDP’s audit trail. Configure the embedded PDP to use the hub audit backend:

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

1	Optional field masks that remove sensitive data from audit entries before they are shipped to Hub. Supports masks on peer information, metadata headers, and `CheckResources`/`PlanResources` inputs and outputs using JSON path expressions.

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.

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 Hub audit backend buffers entries locally and flushes them in batches. The local buffer also acts as a fallback if the Hub ingest endpoint is temporarily unreachable. For the full set of tunables — flush intervals, batch sizes, goroutine pool options, field masking grammar — see the Cerbos PDP audit documentation.

The same CERBOS_HUB_CLIENT_ID and CERBOS_HUB_CLIENT_SECRET credentials are used for both policy distribution and audit logging.

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.

See the Cerbos PDP documentation for configuring Hub on the upstream PDP.

Troubleshooting

Authentication failures at startup. Check that CERBOS_HUB_CLIENT_ID and CERBOS_HUB_CLIENT_SECRET are set in the container environment and scoped to the workspace containing the deployment. Credentials from a different workspace will fail authorization even if the deployment ID is valid.
Bundle not found. Verify the deployment ID in the Hub console. A deployment must be published, not merely created, before Synapse can fetch it.
Bundle updates not applied. Confirm disableAutoUpdate is unset or false, and that the container has network access to Hub. The embedded PDP logs bundle fetches at DEBUG level.
Stale bundles after restart. If storage.hub.remote.cacheDir points at an ephemeral directory, each restart re-downloads the bundle. Mount a persistent volume to eliminate this round trip.