Configuration#
This page lists the environment variables Drawbridge reads and shows how the environment and the config file fit together.
Environment variables#
The table below is generated from the code: every DRAWBRIDGE_ variable a file under src/ or bin/ reads, with its meaning, its default and the first file that reads it.
| Variable | Meaning | Default | Read in |
|---|---|---|---|
| DRAWBRIDGE_CONFIG | the per-app config file | /etc/drawbridge/drawbridge.yaml | src/Command/Env.php |
| DRAWBRIDGE_COOKIE_SECURE | Secure session cookie; false only for a plain-HTTP local rig |
true | src/Command/Env.php |
| DRAWBRIDGE_METRICS_ALLOW | comma list of client IPs/CIDRs allowed to read /metrics; empty trusts no address |
none | src/Command/Env.php |
| DRAWBRIDGE_METRICS_DIR | the shared file-backed metrics store: the signer and the /metrics endpoint keep their counters in this directory, one JSON file per metric family |
/tmp/drawbridge-metrics | src/Metrics/FileStorage.php |
| DRAWBRIDGE_METRICS_TOKEN | bearer token that may read /metrics; empty turns the endpoint off unless an allow list is set |
none | src/Command/Env.php |
| DRAWBRIDGE_OIDC_CLIENT_SECRET | the OpenID Connect client secret; or set DRAWBRIDGE_OIDC_CLIENT_SECRET_FILE to a mounted secret file (the plain variable wins when both are set) |
none, required | src/Config/ClientSecretExpiry.php |
| DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES | the day the client secret expires (YYYY-MM-DD, from Entra); config:validate prints the days left, /metrics serves drawbridge_oidc_client_secret_days_left, and render warns in the container log at 30 days or fewer; never refuses a request, but a value that is not a real date is refused when the config is rendered |
unset | src/Command/Env.php |
| DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE | encrypts state cookies and sessions; 32+ characters; with the default shm store, changing it signs everyone out (the rotation rig run documents why a previous passphrase cannot keep them); with gateway.session_store: redis, setting the old value as DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS keeps everyone signed in, proven by rig/run.sh redis-rotation |
none, required | src/Render/RenderOptions.php |
| DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS | an old passphrase, rendered as the second value (new first, old second); mod_auth_openidc accepts it, but with the default shm store every reload or restart empties the sessions, so it keeps nobody signed in (see the rotation rig run); with gateway.session_store: redis (0.2.1) it keeps the sessions sealed under the old value working while new ones use the new value, proven by rig/run.sh redis-rotation; remove it after session_seconds (8 hours by default), when those sessions have run out anyway; any still left are sent to sign in again |
unset | src/Command/Env.php |
| DRAWBRIDGE_PORT | port Apache listens on (non-root, so above 1024) | 8080 | src/Command/Env.php |
| DRAWBRIDGE_PUBLIC_PORT | public port when it is not the scheme default | empty | src/Command/Env.php |
| DRAWBRIDGE_PUBLIC_SCHEME | how browsers reach the gateway; feeds ServerName, X-Forwarded-Proto, the redirect URI |
https | src/Command/Env.php |
| DRAWBRIDGE_REDIS_PASSWORD | the password of the Redis that holds the gateway sessions when gateway.session_store is redis; rendered as a reference to this variable, never as a value, and only when it is set |
unset | src/Command/Env.php |
| DRAWBRIDGE_REVOCATION_FILE | the revocation list drawbridge revoke writes and the gateway reads on every signed-in request; several gateway instances must share one mounted file |
/tmp/drawbridge/revoked.txt | src/Command/Env.php |
| DRAWBRIDGE_SESSION_CACHE_ENTRIES | entries in the shared-memory cache: sessions, nonces, provider metadata (minimum 10; a smaller value or a non-number is refused when the config is rendered) | 1000 | src/Command/Env.php |
| DRAWBRIDGE_SIGNING_KEY_FILE | ES256 private key for assertions (mounted) | /run/drawbridge/signing.key | src/Command/Env.php |
| DRAWBRIDGE_SIGNING_KEY_ID | kid in each token header; change it when the key changes |
drawbridge-1 | src/Command/Env.php |
| DRAWBRIDGE_TRUSTED_PROXIES | comma-separated CIDRs allowed to set X-Forwarded-For; empty trusts nobody |
empty | src/Command/Env.php |
Example environment#
Every variable from the table, plus the three from .env.example, with placeholder values:
DRAWBRIDGE_CONFIG=/etc/drawbridge/drawbridge.yaml
DRAWBRIDGE_PORT=8080
DRAWBRIDGE_PUBLIC_SCHEME=https
DRAWBRIDGE_PUBLIC_PORT=
DRAWBRIDGE_COOKIE_SECURE=true
DRAWBRIDGE_TRUSTED_PROXIES=
DRAWBRIDGE_OIDC_CLIENT_SECRET=change-me
DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES=2028-11-01
DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE=change-me
DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS=
DRAWBRIDGE_SIGNING_KEY_FILE=/run/drawbridge/signing.key
DRAWBRIDGE_SIGNING_KEY_ID=drawbridge-1
DRAWBRIDGE_SESSION_CACHE_ENTRIES=1000
DRAWBRIDGE_REVOCATION_FILE=/tmp/drawbridge/revoked.txt
DRAWBRIDGE_RUN_DIR=/tmp/drawbridge
DRAWBRIDGE_LOG_LEVEL=warn
DRAWBRIDGE_EVENT_LOG=/dev/stdout
DRAWBRIDGE_METRICS_TOKEN=change-me
DRAWBRIDGE_METRICS_ALLOW=
Client secret expiry#
An Entra client secret expires on a date, and on that date nobody can sign in to any app behind the gateway. Set DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES to the date Entra shows beside the secret (YYYY-MM-DD; it is not a secret) and the gateway counts down to it in whole days from today's UTC date:
| State | Days left |
|---|---|
ok |
more than 30 |
soon |
30 or fewer |
urgent |
7 or fewer, the day itself included |
expired |
below 0 |
It shows in three places, and none of them refuses a request:
config:validateprints the date, the days left and the state, then how to rotate: add a new client secret in Entra, set it and its new date, restart the gateway, delete the old secret./metricsservesdrawbridge_oidc_client_secret_days_left, a gauge that goes negative once the date has passed (see Metrics); alert on it at 30 and 7.render, which the entrypoint runs once at each container start, writes onedrawbridge: warning: ...line to the container log when the state issoon,urgentorexpired.
Unset, nothing changes. A value that is not a real date (12/01/2026, 2026-02-30) is refused by config:validate and by render, so the container does not start with a reminder that would never fire. The owner is whoever owns the app registration in Entra and set the secret; update the date with the secret at every rotation.
The config file#
One YAML (or PHP array) file declares the gateway, the OpenID Connect provider and each app. config/drawbridge.example.yaml is annotated. The Protecting paths guide walks through it: each app's id, host, upstream, mode and default, its public, protected, api and deny paths, and the groups a rule can name (with oidc.groups_claim, the ID token claim that lists them).