---
title: "Configuration | DRAWBRIDGE docs"
description: "The full configuration reference: the oidc block, the gateway block, and each app's id, host, upstream, mode and path rules."
url: https://drawbridge.apps.wayne.edu/docs/reference/configuration.html
llms: https://drawbridge.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# Configuration [#](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html#configuration)

This page lists the environment variables Drawbridge reads and shows how the environment and the config file fit together.

## Environment variables [#](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html#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 |

Note

The table lists the variables the PHP code reads. `.env.example` also sets `DRAWBRIDGE_RUN_DIR`, `DRAWBRIDGE_LOG_LEVEL` and `DRAWBRIDGE_EVENT_LOG`, which the container uses for scratch space, the Apache log level and the [event log](https://drawbridge.apps.wayne.edu/docs/reference/log-events.html) (default `/dev/stdout`).

## Example environment [#](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html#example-environment)

Every variable from the table, plus the three from `.env.example`, with placeholder values:

```dotenv
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=
```

Warning

The secrets are never committed: `DRAWBRIDGE_OIDC_CLIENT_SECRET`, `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE` and `DRAWBRIDGE_METRICS_TOKEN` are set in the deployment's secret store (or a `.env` that never goes in git), and the signing key is a file mounted into the container.

## Client secret expiry [#](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html#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:validate` prints 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.
- `/metrics` serves `drawbridge_oidc_client_secret_days_left`, a gauge that goes negative once the date has passed (see [Metrics](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html)); alert on it at 30 and 7.
- `render`, which the entrypoint runs once at each container start, writes one `drawbridge: warning: ...` line to the container log when the state is `soon`, `urgent` or `expired`.

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 [#](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html#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](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html) 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).

## Related [#](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html#related)

- [Commands](https://drawbridge.apps.wayne.edu/docs/reference/commands.html)
- [Protecting paths](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html)
- [WSU values (Playbook)](https://drawbridge.apps.wayne.edu/docs/guides/wsu-values.html)
- [Register Drawbridge in Entra ID](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html)
