Configuration

The Cerbos server is configured with a YAML file. Start the server by passing the configuration file using the --config flag. The values defined in the file can be overridden from the command-line by using the --set flag. The --set flag can be used multiple times. For example, to override server.httpListenAddr and engine.defaultPolicyVersion, the --set flag can be used as follows:

./cerbos server --config=/path/to/config.yaml --set=server.httpListenAddr=:3592 --set=engine.defaultPolicyVersion=staging
Config values can reference environment variables by enclosing them between ${}. E.g. ${HOME}.
./cerbos server --config=/path/to/config.yaml --set=server.httpListenAddr=:3592 --set=engine.defaultPolicyVersion=staging

Minimal Configuration

At a minimum, Cerbos requires a storage driver to be configured in order to start. You must provide a configuration file when starting the Cerbos binary. The Cerbos container ships with a default configuration that has a disk driver configured to look for policies mounted at /policies. .Default configuration file shipped in the container

---
server:
  httpListenAddr: ":3592"
  grpcListenAddr: ":3593"

storage:
  driver: "disk"
  disk:
    directory: /policies
    watchForChanges: true

Full Configuration

Cerbos has many configuration options that are either optional or has reasonable defaults built-in. The following section describes all user-configurable options and their defaults.

Cerbos configuration file
---
server:
  httpListenAddr: ":3592" # The dedicated HTTP address to listen.
  grpcListenAddr: ":3593" # The dedicated HTTP address to listen.
  metricsEnabled: true # Set to false to disable the /_cerbos/metrics endpoint
  logRequestPayloads: false # Set to true to log full request and response payloads. Affects performance.
  playgroundEnabled: false # Set to true to enable the playground API.
  tls: # Optional
    cert: /path/to/certificate # Path to the TLS certificate file.
    key: /path/to/private_key # Path to the TLS private key file.
    caCert: /path/to/CA_certificate # Path to the optional CA certificate for verifying client requests.
  cors: # Optional
    disabled: false
    allowedOrigins: ['*'] # The contents of the allowed-origins header.
    allowedHeaders: ['content-type', 'access-control-allow-origin'] # The contents of the allowed-headers header
    maxAge: 10s # The max age of the CORS preflight check.
  adminAPI:
    enabled: true # Defines whether the admin API is enabled.
    adminCredentials: # Defines the admin user credentials.
      username: cerbos # The hardcoded username to use for authentication.
      passwordHash: JDJ5JDEwJEdEOVFzZDE2VVhoVkR0N2VkUFBVM09nalc0QnNZaC9xc2E4bS9mcUJJcEZXenp5OUpjMi91Cgo= # BCrypt hashed and base64 encoded password to use for authentication.

auxData: # Optional
  jwt:
    disableVerification: false # Set to true to disable JWT verification
    keySets: # Keysets for verifying JWTs
      - id: ks1 # Unique ID that can be used in API requests to indicate the keyset to use to verify a particular token.
        remote: # Fetch from a JWKS URL.
          url: https://domain.tld/.well-known/keys.jwks
      - id: ks2
        remote:
          url: https://other-domain.tld/.well-known/keys.jwks
          refreshInterval: 1h # Explicitly set the refresh interval.
      - id: ks3
        local: # Load from a local file
          file: /path/to/keys.jwks
      - id: ks4
        local: # Load from a base64-encoded key data defined inline.
          data: BASE64-ENCODED-KEY-DATA
      - id: ks5
        local:
          file: /path/to/keys.pem
          pem: true # Treat the file (or data) as PEM.

engine: # Optional
  defaultPolicyVersion: "default" # Default policy version to assume if the request does not specify one.

storage:
  driver: "disk" # Valid values are "disk", "git" or "sqlite3"
  disk: # Only required if "driver" is "disk"
    directory: pkg/test/testdata/store # Directory to store policies
    watchForChanges: false  # Enables watching the directory for changes.
  git: # Only required if the "driver" is "git"
    protocol: file # Valid values are "file", "ssh", "https"
    url: file://${HOME}/tmp/cerbos/policies # the URL to the Git repo.
    branch: policies # Branch that should be used as the source. Defaults to "master"
    subDir: policies # Set this if the policies are stored in a subdirectory
    checkoutDir: ${HOME}/tmp/cerbos/work # Work directory of the server
    updatePollInterval: 60s # How often the source git repo should be polled for updates
    https: # Only required if the "protocol" is "https"
      username: cerbos # The username to use for authentication.
      password: ${GITHUB_TOKEN} # The password (or token) to use for authentication.
    ssh: # Only required if the "protocol" is "ssh"
      user: git # The git user. Defaults to git.
      privateKeyFile: ${HOME}/.ssh/id_rsa # the path to the SSH private key file.
      # password: pw # the password to the SSH private key.
  blob: # Only required if the "driver" is "blob"
    bucket: "s3://my-bucket-name?region=us-east-2" # the URL of the bucket
    prefix: policies # Set this if the policies are stored in a bucket subdirectory
    workDir: ${HOME}/tmp/cerbos/work # Directory to store policies
    updatePollInterval: 15s # how often the bucket should be polled for updates. Defaults to 0, which disables polling.
    requestTimeout: 10s # HTTP request timeout. Defaults to 5s.
    downloadTimeout: 30s # Timeout to download all requested policies.
  sqlite3: # Only required if the "driver" is "sqlite3"
    dsn: ":memory:?_fk=true" # Data source name
  postgres: # Only required if the "driver" is "postgres"
    url: "postgres://user:password@localhost:port/db"
    connPool: # common SQL connection pool settings.
      maxLifeTime: 60m
      maxIdleTime: 45s
      maxOpen: 4
      maxIdle: 1
  mysql: # Only required if the "driver" is "mysql"
    dsn: "user:password@tcp(localhost:3306)/db?interpolateParams=true" # Data source name
    connPool: # common SQL connection pool settings.
      maxLifeTime: 60m
      maxIdleTime: 45s
      maxOpen: 4
      maxIdle: 1
    tls:
      mytls:
        cert: /path/to/certificate # Path to the TLS certificate file.
        key: /path/to/private_key # Path to the TLS private key file.
        caCert: /path/to/CA_certificate # Path to the optional CA certificate for verifying client requests.
    serverPubKey:
      mykey: testdata/server_public_key.pem

tracing: # Optional
  sampleProbability: 0.1 # Sampling probability value between 0.0 and 1.0
  exporter: jaeger # Trace exporter to use. Currently only Jaeger is supported
  jaeger: # Required only if exporter is "jaeger"
    serviceName: cerbos # Optional service name to report to Jaeger. Defaults to cerbos.
    agentEndpoint: "localhost:6831" # Export to Jaeger agent. Takes precedence if both "agentEndpoint" and "collectorEndpoint" are defined.
    collectorEndpoint: "http://localhost:14268" # Export to Jaeger collector.

audit: # Optional
  enabled: false # Enable audit logging
  accessLogsEnabled: true # Log API access attempts
  decisionLogsEnabled: true # Log policy decisions
  backend: local # Audit backend to use.
  local: # Configuration for the local audit backend
    storagePath: /path/to/dir # Path to store the data
    retentionPeriod: 168h # How long to keep records for
    advanced:
      bufferSize: 256
      maxBatchSize: 32
      flushInterval: 1s
      gcInterval: 60s

schema: # Optional
  enforcement: reject # How to enforce schema validation (none: no enforcement, warn: log warnings, reject: reject invalid requests)