Skip to content
Menu

Troubleshooting#

This page matches the answers the gateway gives by design (a refusal to start, a 503, a bare 401, a session that is gone) to their causes, and gives the command that checks each one.

Startup#

The entrypoint refuses to start#

Cause: the gateway cannot start without the two files and the two secrets it is given: drawbridge.yaml (the per-app config), signing.key (the ES256 key that signs assertions), DRAWBRIDGE_OIDC_CLIENT_SECRET (the Entra client secret) and DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE (at least 32 characters). The entrypoint refuses to start if any is missing, and render refuses an unusable secret, so Apache never starts with a literal ${...} for a secret. A config error stops the container from starting.

Fix: mount the two files read-only, put both environment variables in the deployment's secret store, keep the passphrase at 32 characters or more, and make sure the config validates.

Check:

php bin/drawbridge config:validate --config=config/drawbridge.yaml

config:validate reports problems#

Cause: config:validate checks the config and prints every problem at once, then the provider settings (never the secret, only whether its variable is set); it exits 1 if there is anything to report. Typical findings are a path rule that uses a wildcard or a regular expression (there are no wildcards and no regular expressions), an issuer that is not https (plain http is accepted only for a .test host), or a value outside its range.

Fix: read the printed lines, correct config/drawbridge.yaml, and run the check again until it is clean.

Check:

php bin/drawbridge config:validate --config=config/drawbridge.yaml

Sign-in and sessions#

An api path answers a bare 401#

Cause: this is the answer by design when the session is gone. A request for an api path without a session gets a plain 401, so a script never receives an HTML login page; the 401 carries no Location header. The session can be dead because either clock ran out (8 hours total, 1 hour idle by default), the visitor signed out through the ?logout= link, or the gateway was restarted or reloaded (the cache lives in shared memory and starts empty).

Fix: have the caller sign in again; nothing on the gateway side is broken. If a 401 appears where a redirect to sign in was expected, the path is listed under api instead of protected.

Check:

php bin/drawbridge explain app1.apps.wayne.edu /api/ --config=config/drawbridge.yaml

Sessions are empty after a reload or restart#

Cause: by default (gateway.session_store: shm) drawbridge keeps the gateway sessions in Apache's shared memory, and every restart or graceful reload rebuilds that store empty. The pinned mod_auth_openidc accepts the documented two-value form (a current plus a previous passphrase, DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS) and starts with it, but the previous passphrase can only decrypt a session whose state still exists, so it cannot keep anyone signed in across any restart or reload: the saved cookie is refused and the browser is sent to sign in again. The rotation rig run documents this against the pinned module, with the old passphrase kept, with it dropped, and after the gateway container is recreated.

Fix: none to apply with the default store; this is the expected behavior. Schedule the change for a moment when a mass re-sign-in is acceptable, and tell the app owners.

Check:

php bin/drawbridge config:validate --config=config/drawbridge.yaml

Signing#

A protected path answers 503#

Cause: the signer could not sign. If the signer cannot sign, the answer is 503 and the request does not reach the app. There is no unsigned mode: an app gets the signed assertion or nothing (the header modes were removed for 1.0). The usual cause is the mounted key: the ES256 private key at DRAWBRIDGE_SIGNING_KEY_FILE (default /run/drawbridge/signing.key) is missing or unreadable, or DRAWBRIDGE_SIGNING_KEY_ID no longer matches the key. Every end-to-end sign-in in the rig fails if the signer cannot read the mounted key.

Fix: make sure the key file is mounted read-only where DRAWBRIDGE_SIGNING_KEY_FILE points and that the signer can read it, and change DRAWBRIDGE_SIGNING_KEY_ID when the key changes. keys:generate makes a fresh ES256 key pair; it refuses to overwrite a file. The signer's log carries exactly one reason-code line per refused request, with no subject, attribute or token; a signing failure logs only the exception class, never its message.

Check:

php bin/drawbridge config:validate --config=config/drawbridge.yaml

Every app refuses sign-ins with gateway.signature after a key switch#

Cause: the gateway now signs with a key the apps do not trust. The kid in DRAWBRIDGE_SIGNING_KEY_ID is not in the apps' key set file, or the private key at DRAWBRIDGE_SIGNING_KEY_FILE is not the one published under that kid. This happens when the gateway switched to a key that was never published as the "next" key.

Fix: switch the gateway back to the previous key and kid (the apps still trust it), publish a key set file that holds the new key, wait until the apps have it, and switch again. The rotation guide has the order that avoids this.

Check:

php bin/drawbridge keys:jwks --key=<kid>=<the public half of the key the gateway signs with>

The printed kid, x and y must match an entry in the file the apps read.

Path rules#

A path goes to sign-in that should be public#

Cause: a path with no rule gets login unless the app says otherwise; public is a decision, not a default. Remember how rules match: exact (/up) or prefix (a trailing slash, /assets/), the longest rule wins, an exact rule beats a prefix of the same length, and query strings are never part of the match. A path with an encoded slash, a backslash, a semicolon, a control character or bad UTF-8 is treated as login (and the guard answers 400), so a mangled URL also lands on sign-in.

Fix: add the path to the app's public list in config/drawbridge.yaml (or to whichever list it belongs to), and re-check what the gateway will do with the request.

Check:

php bin/drawbridge explain app1.apps.wayne.edu /admin/users --config=config/drawbridge.yaml

explain says which rule applies to a request, and which authentication context it needs, and why.

An unknown host answers 403#

Cause: the request arrived for a host with no app entry in the config, or for a refused path. The default catch-all host answers 403 with its own error page.

Fix: add the app to the config (host, upstream, and which paths are public, protected, step-up or API) and re-render, or correct the address the visitor asked for.

Check:

php bin/drawbridge explain <app host> /up --config=config/drawbridge.yaml