Skip to content
Menu

Upgrading#

This page walks the released versions from CHANGELOG.md, shows how to take a new gateway image, and notes what is coming.

0.6.2 (2026-11-10)#

No breaks: an app config that validated under 0.6.1 still validates, and the gateway behaves as before. Take the new image the way Getting the image describes.

What changed#

  • A crypto passphrase change rolls across two gateway instances on one Redis without signing anybody out (sh rig/run.sh multi), and CI's rig job runs the redis, redis-rotation and multi modes.
  • The front page's deploy layer requires PROCTOR ^0.15 and runs Squire's kit 0.10.7; the GitHub workflow is on Preflight 0.5.0. The gateway image does not change for them.

0.6.1 (2026-11-09)#

No breaks: an app config that validated under 0.6.0 still validates, and the gateway image runs as before. Take the new image the way Getting the image describes.

What changed#

  • A passphrase change over the Redis session store is now proven to sign nobody out (sh rig/run.sh redis-rotation); the README and the Sessions guide give the three rotation steps.
  • The front page's deploy layer runs Squire's kit 0.10.2 and requires HELMET ^1.3 and CREED ^0.1.8; the CI jobs run Composer 2.11.1 and Preflight 0.5.0. The gateway image does not change for them.

0.6.0 (2026-11-09)#

No breaks: an app config that validated under 0.5.0 still validates, and a gateway without the new setting runs as before. Take the new image the way Getting the image describes, then set the one new value below.

What changed#

  • New optional DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES (YYYY-MM-DD, the date Entra shows beside the client secret; not a secret). With it set, config:validate prints the date, the days left and the state (ok, soon at 30 days or fewer, urgent at 7 or fewer, expired) with the rotation steps, /metrics serves drawbridge_oidc_client_secret_days_left, and render writes one drawbridge: warning: line to the container log at start from soon on (the expiry date). Nothing refuses a request, but a value that is not a real date stops the container at start, so run config:validate with it set before you deploy.
  • If you scrape /metrics, alert on drawbridge_oidc_client_secret_days_left at 30 and again at 7 (Metrics).
  • The front page's deploy layer runs Squire's kit 0.10.1 and requires PROCTOR ^0.11; the gateway image does not change for it.

0.5.0 (2026-11-09)#

No breaks: an app config that validated under 0.4.0 still validates, and a plain claim name in oidc.extra_claims works as before. Take the new image the way Getting the image describes.

What changed#

  • An oidc.extra_claims entry can rename a claim with {from, as}, so a claim that arrives under a long directory extension name reaches the app under a short one ({from: extension_..._wsuRoles, as: wsu_roles}; the example config shows it commented out). Config validation refuses an entry missing from or as, any other key, an as the assertion sets itself, and a renamed name that appears twice, so config:validate a config before you deploy one that renames.
  • The image's mod_auth_openidc floor is 2.4.17-1+deb13u1 (was 2.4.17-1), Debian's fix for CVE-2026-54789. A mirror or base image that serves the unpatched build now fails the image build (The module floor).
  • New advisory watch: composer advisories asks OSV.dev whether Debian has a fixed apache2 or mod_auth_openidc above the image's floors, and exits 1 naming the advisory when it does. It needs the network, so it is not in composer ci; the GitLab advisories job runs it from a schedule or by hand (When to raise it).
  • composer ci now holds the offline half of signing out with third-party cookies blocked (tests/Unit/SignOutFlowTest.php), and the front page and docs follow the reader's dark mode.

0.4.0 (2026-11-08)#

No breaks: an app config that validated under 0.3.0 still validates, and every new rule is opt-in. Take the new image the way Getting the image describes, then check the two settings below.

What changed#

  • New event log (see Log events): one JSON line for each sign-in, failed sign-in, sign-out, denial and revocation. DRAWBRIDGE_EVENT_LOG picks the file and defaults to /dev/stdout, next to the access log, so a log pipeline that reads the gateway's stdout now sees these lines too. Point it at its own file if your collector expects access-log lines only.
  • New drawbridge revoke <subject>... ends every gateway session a person holds, on every app host, without waiting for it to expire (Signing out). It writes to DRAWBRIDGE_REVOCATION_FILE (default /tmp/drawbridge/revoked.txt). If you run more than one gateway instance, mount one shared file at that path on every instance, or a revocation reaches only the instance it ran on.
  • New per-path answers, all opt-in (Protecting paths): a deny list of paths that never reach the app, default: deny so only the listed paths exist, and groups on a protected or api rule, read from the ID token claim oidc.groups_claim (wsu_roles at WSU). Config validation refuses groups without oidc.groups_claim, and groups or a context on a public or deny rule, so config:validate the config before you deploy one that uses them.
  • Each app host lets the gateway's own error pages through, whatever its default, so they still load on a default: deny host.

0.3.0 (2026-11-07)#

No breaks. Take the new image the way Getting the image describes, and note that the gateway image now lives at <registry>/enterprise-apps/images/drawbridge-gateway:<tag>.

What changed#

  • The gateway image moves to the stack's image registry; the old project registry stays readable for the releases already there.
  • New keys:jwks command writes the key set file apps verify assertions with (the current key and the next one). ADR-0001 and the "Rotating the signing key" runbook describe the distribution and the yearly rotation.

0.2.2 (2026-11-06)#

No breaks. Take the new image the way Getting the image describes.

What changed#

  • If you run gateway.session_store: redis with a password, take this release: 0.2.1 never rendered the Redis password, so a password-protected Redis refused the gateway and every sign-in answered 500. With 0.2.2 the gateway authenticates with DRAWBRIDGE_REDIS_PASSWORD. The default shm store renders exactly as before.
  • The front page's deploy layer moves to Symfony 7.4.23 (symfony/http-foundation and symfony/yaml advisories), the image's vendor build stage takes a refreshed Composer digest, and the site gains an accessibility gate.

0.2.1 (2026-11-05)#

No breaks, one behavior change to check (see below). Take the new image the way Getting the image describes.

What changed#

  • Protected and api paths now answer with Cache-Control: no-store when the app sends none (setifempty). Apps whose protected paths serve cacheable assets lose browser caching of them unless the app sends its own Cache-Control (for example through HELMET); public paths are untouched.

0.2.0 (2026-11-03)#

Breaking#

  • Header mode is removed. Config validation (config:validate, render, and gateway start) now rejects an app whose mode is headers or both, and the gateway will not start with such a config. Assertion is the only mode. An unsigned identity header cannot be trusted while app containers may reach each other directly, so an app gets the signed assertion or nothing.
  • This is a pre-1.0 minor: the 0.2 line is a deliberate break for configs that used the header modes.

What changed#

  • Changed: header mode removed for 1.0. The renderer code stays for a later, gated return.
  • Fixed: the gateway image jobs pin the Buildah image to the v1.43.5-immutable tag and its manifest list digest, because the previous digest was removed upstream and the tag pipeline failed with "manifest unknown".
  • Tests: new tests pin the rejection of headers and both, that assertion still loads, and that an assertion app never sees a client's identity headers.

Steps#

  1. Find apps whose config sets mode: headers or mode: both (grep -rn "mode:" config/). In each, set mode: assertion, or delete the line, since assertion is the default.
  2. Move each of those apps to verify the signed assertion with SESAME's gateway driver, because it no longer receives plain X-Authenticated-* headers.
  3. Check the config, then take the new image the way Getting the image describes and restart the gateway with the same two mounted files and the two environment variables.
php bin/drawbridge config:validate --config=config/drawbridge.yaml
docker pull <registry>/enterprise-apps/images/drawbridge-gateway:0.2.0

How to verify#

Verify the image you pulled against the digest the publish job printed:

docker inspect --format='{{index .RepoDigests 0}}' <registry>/enterprise-apps/images/drawbridge-gateway:0.2.0

Then run the rig (sh rig/run.sh or rig\run.ps1); green means the sign-in, path, spoofing, callback and logout tests pass against the new image.

0.1.2 (2026-11-03)#

Breaking#

No breaking changes in 0.1.2, and nothing is deprecated.

What changed#

  • Added: a docs site (site/docs/) built by the shared docs builder from docs/, checked in composer ci.
  • Changed: the gateway image refuses to build when Debian serves apache2 or mod_auth_openidc below the tested floor (apache2 2.4.69-1~deb13u1, mod_auth_openidc 2.4.17-1): the Dockerfile checks the installed versions, so a drifted base image fails the build instead of shipping.
  • Changed: the front-page deploy layer pins HELMET ^0.3, PROCTOR ^0.4 and CREED ^0.1 (lock: HELMET 0.3.0, PROCTOR 0.4.0, CREED 0.1.6), and CI pins Preflight 0.1.4.
  • Docs: the README says how the Entra, gateway and app sessions relate, with each lifetime and what ends it.

Steps#

Only a version tag publishes the gateway image, so this is the release that puts the Debian floor and the earlier 0.1.1 changes (metrics endpoint in the image, rotation rig) into the registry. Take it the way Getting the image describes, then restart the gateway with the same two mounted files and the two environment variables.

docker pull <registry>/enterprise-apps/images/drawbridge-gateway:0.1.2

How to verify#

Verify the image you pulled against the digest the publish job printed:

docker inspect --format='{{index .RepoDigests 0}}' <registry>/enterprise-apps/images/drawbridge-gateway:0.1.2

Then run the rig (sh rig/run.sh or rig\run.ps1); green means the sign-in, path, spoofing, callback and logout tests pass against the new image.

0.1.1 (2026-11-03)#

Breaking#

No breaking changes in 0.1.1, and nothing is deprecated.

What changed#

  • Added: an opt-in keycloak argument for the rig (rig/run.sh keycloak, rig/run.ps1 keycloak) that starts a pinned Keycloak from a hand-written realm as a second identity provider; it checks the client secret and PKCE, knows only two synthetic users, and refuses unregistered redirect URIs.
  • Added: a shared file-backed metrics store, so the long-running assertion signer and the per-request /metrics endpoint keep their counters in one directory (default /tmp/drawbridge-metrics, moved by DRAWBRIDGE_METRICS_DIR). When the store cannot be created or written, the signer counts in memory and the endpoint serves build info only.
  • Added: the gateway image serves /metrics itself: it installs php-cgi, and render maps ^/metrics$ to bin/metrics.
  • Added: an opt-in rotation argument for the rig that walks a crypto passphrase change through the running gateway and documents what the pinned module actually does on reload.
  • Changed: docs and package metadata name nougat as the canonical repository, with git.wayne.edu and GitHub as read-only mirrors, until git.wayne.edu has CI runners.
  • Changed: the default catch-all host now answers every response on it (the unknown-host 403 and the error pages included) with Referrer-Policy: strict-origin-when-cross-origin and Content-Security-Policy: frame-ancestors 'none', both setifempty. No HSTS is added because the default host has no known public scheme, and app hosts are unchanged.
  • Fixed: DRAWBRIDGE_SESSION_CACHE_ENTRIES refuses a value below 10 or a value that is not a whole number when the config is rendered, instead of casting it and sizing the shared-memory cache with whatever survives.
  • Tests: a batch of new pins, among them the session cookie flags, the api 401 for a dead session, the WCAG 2.2 AA properties of the error pages, the catch-all host's hardened headers, the rendered session lifetimes, and the signer's log discipline.

Steps#

Take the new image the way Getting the image describes, then restart the gateway with the same two mounted files and the two environment variables.

docker pull <registry>/enterprise-apps/images/drawbridge-gateway:0.1.1

How to verify#

Verify the image you pulled against the digest the publish job printed:

docker inspect --format='{{index .RepoDigests 0}}' <registry>/enterprise-apps/images/drawbridge-gateway:0.1.1

Then run the rig (sh rig/run.sh or rig\run.ps1); green means the sign-in, path, spoofing, callback and logout tests pass against the new image.

0.1.0 (2026-11-02)#

Breaking#

As the first release there are no breaking changes, and nothing is deprecated.

What changed#

The first release is a gateway built on Apache httpd and mod_auth_openidc in front of Microsoft Entra ID over OpenID Connect, with a signed assertion for SESAME's gateway driver.

  • Per-app config (YAML or PHP array) with exact and prefix path rules, login, api and public protection, and assertion, headers or both delivery; config:validate reports every problem at once.
  • render turns the config into Apache config and a Lua policy; explain says which rule applies; keys:generate makes an ES256 key pair.
  • ES256 assertion signer (typ: drawbridge+jwt, kid, iss, aud, sub, iat, nbf, exp, jti, auth_time, amr) behind Apache's prg: rewrite map. A signing failure gives 503.
  • composer ci: manifest validation, PHPUnit, Pint, PHPStan level 8, composer audit; GitLab and GitHub CI.
  • Gateway error pages: 403, 502, 503 and 504 answer with a small self-contained page served from /_drawbridge/errors/; 401 stays bare for api callers, and the /metrics endpoint keeps its empty-body 403.
  • auth_context on a path rule (c1 to c99): the gateway asks Entra for the context with the claims request parameter and requires it in the ID token's acrs array.
  • GitLab pipeline builds the gateway image with Buildah on every merge request and the default branch, and publishes it to the stack's image registry (the group's images project) when a tag is pushed (gateway:<tag>, no latest).
  • An off-by-default Prometheus /metrics endpoint (bin/metrics), on when DRAWBRIDGE_METRICS_TOKEN or DRAWBRIDGE_METRICS_ALLOW is set.
  • Response headers: every proxied answer gets X-Content-Type-Options: nosniff and Referrer-Policy: strict-origin-when-cross-origin, plus Strict-Transport-Security: max-age=31536000 when the public scheme is https, each with setifempty so an app that sends its own header through HELMET keeps it.
  • Config: the example and rig set oidc.user_claim: accessid, the AccessID the Entra app registration sends; preferred_username works for a tenant that does not send accessid. The example also lists wsu_roles in extra_claims.
  • Rig: mock-oauth2-server 6.1.3 as the test IdP.
  • Fixed: stale capability claims in the site and README.

Steps#

There is no earlier image to move from: build or pull 0.1.0 and start the gateway with the two files and the two secrets described in Install.

docker pull <registry>/enterprise-apps/images/drawbridge-gateway:0.1.0

How to verify#

Same as for 0.1.1: check the digest against the publish job's output, then run the rig.

Changes that are not released yet are listed under Unreleased at the top of CHANGELOG.md.

To rebuild the gateway image locally instead of pulling one, MAINTAINING.md gives:

docker build -f docker/gateway/Dockerfile -t drawbridge-gateway .

Taking a new image#

The pipeline builds the gateway image on every merge request and on the default branch, and publishes it to the stack's image registry (the group's images project) when a tag is pushed. The image is at <registry>/enterprise-apps/images/drawbridge-gateway:<tag> (for example <registry>/enterprise-apps/images/drawbridge-gateway:0.6.2). <registry> is the stack's container registry; Enterprise Applications has its address.

docker pull <registry>/enterprise-apps/images/drawbridge-gateway:0.6.2

Drawbridge is not installed with Composer by apps and is not on Packagist, so an app has no composer update to run for it; upgrading Drawbridge is taking the new gateway image and restarting the gateway with the same mounts and environment.

Rotating keys and secrets#

Upgrades often meet expiry dates. From MAINTAINING.md:

  • The Entra client secret expires (the portal caps it at 24 months). An expired secret means nobody can sign in. Keep at least two owners on the app registration so the expiry notice reaches more than one inbox. To rotate without signing anyone out: add a new secret in Entra, update DRAWBRIDGE_OIDC_CLIENT_SECRET and its expiry date in DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES, restart the gateway, check a sign-in, then delete the old secret. With the date set, config:validate, /metrics and the container log count down to it (the expiry date).
  • The crypto passphrase: with the default shm session store, changing it and restarting signs everyone out (safe, but noisy). With gateway.session_store: redis, set the old value as DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS, restart, wait session_seconds, then remove it and restart again: nobody is signed out, proven by rig/run.sh redis-rotation (Changing the passphrase).
  • The assertion signing key: every 12 months, or at once on a suspected leak. Apps read a key set file of the current and the next key (keys:jwks, SESAME's gateway.jwks_file), so switch the gateway to the next key, wait at least 5 minutes, then publish a new key set file; no shared window with the apps is needed (Rotating the signing key).