# Drawbridge: everything in one file > Drawbridge is the sign-in gateway we're building for Citadel, Wayne State's container platform: Apache with mod_auth_openidc as one OpenID Connect client for Microsoft Entra ID. It drops any identity header a visitor sends and passes the app a 60-second ES256-signed assertion that SESAME checks. It isn't in front of any apps yet. The README and the Markdown twin of every page, joined. The index is https://drawbridge.apps.wayne.edu/llms.txt. Written by Squire's agent-ready kit; do not edit. --- ## README Source: https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/README.md ## Drawbridge **Comes down for signed-in people.** Checks: `composer ci` (the same command runs in the GitLab pipeline and in the GitHub Actions workflow kept in `.github/`). The container rig has its own script, see "Run the checks". > The one way into the Citadel. It only comes down for people who signed in. Drawbridge is the sign-in gateway for the apps on Citadel, Wayne State's container platform. It is Apache with mod_auth_openidc, set up as one OpenID Connect client for Microsoft Entra ID. It is not live yet: its home will be `auth.apps.wayne.edu`, in front of every app on the platform, once the Citadel routing for it exists. The latest release, 0.6.2, is tagged. It builds the gateway image, which will run as a service on Citadel. As a reverse proxy it checks that the visitor has a session, drops any identity header the visitor sent, and passes the app a short-lived signed assertion that SESAME's `gateway` driver verifies. Which paths need a login, and which need an Entra authentication context on top, is declared per app in a config file. Nothing else decides it. Why a moat and not a lock on every door: each app doing its own OpenID Connect is another chance to get a nonce, a state check or a token signature wrong. We'd rather get that right once, in a maintained module (mod_auth_openidc). Each app then checks one small signed token. ### Documentation This page summarizes the gateway; the [docs site](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/site/docs/index.html) holds the full version, from [getting started](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/site/docs/install.html) and the guides through the [configuration](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/site/docs/reference/configuration.html) and [commands](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/site/docs/reference/commands.html) reference to [deploying](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/site/docs/deploying/getting-the-image.html) and releasing. ### Where the code lives The canonical repository is [enterprise-apps/drawbridge](https://git.wayne.edu/enterprise-apps/drawbridge) on git.wayne.edu, cloned over HTTPS (`git clone https://git.wayne.edu/enterprise-apps/drawbridge.git`) or SSH (`git clone git@git.wayne.edu:enterprise-apps/drawbridge.git`). Open issues and merge requests there. Tags are made there, by the maintainer, with an approver. Drawbridge is not on GitHub: git.wayne.edu is its only home. The drawbridge is down at the castle; there is no mirror across the moat. ### Where it fits in the stack Drawbridge is one part of the Wayne State application stack: one contract, several paths that agree, accessibility as a gate, and decisions written down. WELD is the Laravel starter app with the rest of it already set up. | Part | Job | |---|---| | WayneUI | the interface layer (project 0 of the stack) | | CREED | the shared rules and policy format | | PROCTOR | checks an app against the version policy | | SESAME | sign-in inside the app; its `gateway` driver verifies what Drawbridge signs | | HELMET | security headers and CSP reporting | | Sourdough | the starter that keeps the stack fed | | Squire | the Citadel deploy kit; the layer that serves this repo's front page is one | | Parity | Citadel on your computer: its PHP image, its proxy and MySQL 5.6, so an app that works here works on Citadel | | Preflight | the shared CI components | | Pinstripe | the coding standard presets (Pint, PHPStan, ESLint, Rector) | | Booster | upgrades an app's PHP, Laravel and front end, one hop at a time | | Rollcall | the fleet census: which apps run what, and how close each is to end of life | | **Drawbridge** | **the one OpenID Connect front door for the Citadel** | | ADVISOR | the read-only MCP server that answers a coding agent's stack questions | | WELD | the Laravel starter app with the rest of the stack already set up | ### How it works ``` browser --> Apache httpd (Drawbridge) --> app container | mod_auth_openidc : OpenID Connect client (Entra ID), one session cookie per app host | mod_lua : strips identity headers on every request, before anything else | mod_rewrite : asks the PHP signer for an assertion (prg: map) | mod_proxy : forwards to the app `- PHP component : validates the config, renders the Apache config, signs assertions (ES256) ``` - A request for a **protected** path without a session goes to Entra to sign in (authorization code flow with PKCE) and comes back. For an **api** path it gets a plain 401, so a script never receives an HTML login page. A **public** path passes through with no identity attached. A **deny** path never reaches the app: the gateway answers 403 with its own page, signed in or not. `default: deny` makes every unlisted path a deny path, so only the paths an app lists exist at all. The most specific rule wins, whichever list it is in. - A protected or api rule can name **groups** (`groups: [app1-admins]`, read from the ID token claim `oidc.groups_claim`, `wsu_roles` at WSU): a signed-in person who holds none of them gets 403. It is a coarse gate in front of the app; the app still decides what each person may do. - mod_auth_openidc checks the ID token (signature, issuer, audience, nonce, expiry) and keeps the session. The claims reach the gateway in the request environment only, never as headers, and no Entra token is passed to an app. - The assertion is a compact JWT with `typ: drawbridge+jwt` and a `kid`. Claims: `iss` (Drawbridge, never Entra), `aud` (the app's host), `sub` (the configured user claim, `accessid` in the example config and `preferred_username` if unset), `iat`, `nbf`, `exp` (60 seconds by default), `jti`; `auth_time`, `amr` and `acrs` when the ID token carries them; `email`, `name` and `affiliations` when configured; and any `extra_claims` (for example `wsu_roles`). A new one is signed for every request, and only from an ID token whose `iss` is the configured provider. - 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). - Header stripping: the guard removes every inbound `X-Authenticated-*`, `X-Sesame-*`, `X-Drawbridge-*`, `OIDC_CLAIM_*`, `OIDC_access_token` (and the module's other token names), `Remote-User`, `X-Forwarded-*`, `Forwarded` and similar header, in any hyphen or underscore spelling, on every request, before authentication runs. Every header under an owned prefix goes, whatever follows the prefix. It also trims `Connection` to `close`, `keep-alive` and `upgrade`, so a client cannot ask the proxy to drop a header the gateway set. #### Step-up with an authentication context A path rule can name an Entra authentication context (`c1` to `c99`): ```yaml protected: - /admin/ - path: /admin/payroll/ auth_context: c1 ``` On that path the gateway asks Entra for the context with the OpenID Connect `claims` request parameter (`{"id_token":{"acrs":{"essential":true,"value":"c1"}}}`) and lets the request through only when the ID token's `acrs` array lists `c1`. A visitor already signed in without it is sent back to Entra to step up (mod_auth_openidc answers with a short page that forwards the browser); an `api` path answers 401. What `c1` actually demands (MFA, a compliant device, a fresh sign-in) is a Conditional Access policy in Entra, not Drawbridge config. The check is made twice: by mod_auth_openidc's `Require claim acrs:c1`, and again by the gateway's own stamp step. #### Signing out An app links to `/_drawbridge/oidc/callback?logout=`. mod_auth_openidc ends the gateway session for that host and sends the browser through Entra's sign-out endpoint (named in the provider's discovery document) back to the address. An address on another host is refused, so the link cannot be used to bounce visitors elsewhere. To end a person's sessions from outside, on every app host at once, run `drawbridge revoke ` where the gateway reads its revocation list (`DRAWBRIDGE_REVOCATION_FILE`). On their next protected request a browser is sent through the sign-out above and an `api` caller gets 401; a fresh sign-in works as before, so disable the account in Entra to keep someone out. Entra offers other apps only an iframe front-channel logout, which blocked third-party cookies break, so Drawbridge uses none: every sign-out hop is a top-level redirect. Signing in is held the same way: a sign-in started with a `target_link_uri` on another host (written plainly, protocol-relative or with a userinfo trick) never sends the visitor there, and the answer never names that host. The rig proves it (`GatewayTest::testLoginReturnsOnlyToTheSameHost`). #### Error pages The errors the gateway answers itself get a small page of their own instead of Apache's default English wall: 403 (an unknown host or a refused path), 502 and 504 (the app is down or taking too long) and 503 (the signer cannot sign). Each page is one self-contained HTML file under `docker/gateway/errors/`: inline CSS, system fonts, no scripts, no external assets, dark-mode aware, and no hostname or product name in the text. They are served from `/_drawbridge/errors/`, which the app hosts keep out of the proxy. Two answers stay deliberately plain: an `api` path keeps its bare 401, because a script must never be handed an HTML login page, and the `/metrics` endpoint keeps its empty-body 403 (and 404), because a scrape must not look like a page. The endpoint is not routed by the gateway config, so these pages cannot reach it; if you wire it up as the Metrics section describes, keep the empty body inside that location. `tests/Unit/ErrorPagesTest.php` also pins their accessibility: WCAG 2.2 AA text contrast in both color schemes, a viewport that does not block zoom, a visible focus outline of at least 2px, and a body text size of at least 16px with headings set in rem or em. #### Response headers Apps send their own security headers through HELMET, so the gateway never overrides one. On every proxied answer it adds `X-Content-Type-Options: nosniff` and `Referrer-Policy: strict-origin-when-cross-origin` with `setifempty`, and an app that sends either keeps its own. When the public scheme is https it also adds `Strict-Transport-Security: max-age=31536000` the same way, with no `includeSubDomains` and no `preload`: the gateway serves many hosts and must not decide subdomain or preload policy for them. Protected and api paths also get `Cache-Control: no-store` with `setifempty`, so a signed-in page an app leaves uncached cannot be served by a shared cache after the session ends. Public paths are untouched: the gateway adds no `Cache-Control` there, and an app that wants its protected assets cached sends its own `Cache-Control`, which the gateway never overrides. The pages the gateway answers itself are not behind HELMET and carry their own headers, set plainly because no app header is expected there. The `/_drawbridge/` locations it owns (the OpenID Connect endpoint on each app host, the `/up` check on the default host) get `Cache-Control: no-store` and `Content-Security-Policy: frame-ancestors 'none'`. The default catch-all host adds `X-Content-Type-Options: nosniff` and `Cache-Control: no-store` to everything it answers, including the unknown-host 403 and the error pages. ### Install and quick start You need Docker and nothing else. The PHP component needs PHP 8.3 or newer and Composer, and these steps run both inside the `composer:2.11.1` container. **Windows (PowerShell)** ```powershell git clone https://git.wayne.edu/enterprise-apps/drawbridge.git; cd drawbridge docker run --rm -v "${PWD}:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer install --no-interaction Copy-Item .env.example .env Copy-Item config\drawbridge.example.yaml config\drawbridge.yaml docker run --rm -v "${PWD}:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 php bin/drawbridge config:validate --config=config/drawbridge.yaml docker build -f docker/gateway/Dockerfile -t drawbridge-gateway . ``` **Linux and macOS** ```sh git clone https://git.wayne.edu/enterprise-apps/drawbridge.git && cd drawbridge docker run --rm -v "$PWD:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer install --no-interaction cp .env.example .env cp config/drawbridge.example.yaml config/drawbridge.yaml docker run --rm -v "$PWD:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 php bin/drawbridge config:validate --config=config/drawbridge.yaml docker build -f docker/gateway/Dockerfile -t drawbridge-gateway . ``` With PHP installed locally the same commands are `composer install` and `php bin/drawbridge ...`. Then run the image with the two files it cannot start without, mounted read-only, and the two secrets in its environment. The entrypoint refuses to start if any is missing, and `render` refuses an unusable secret: | Item | What it is | |---|---| | `drawbridge.yaml` (file) | the per-app config, including the `oidc` block | | `signing.key` (file) | the ES256 key that signs assertions (`keys:generate` makes one) | | `DRAWBRIDGE_OIDC_CLIENT_SECRET` (env) | the Entra client secret (the variable name is `oidc.client_secret_env`) | | `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE` (env) | mod_auth_openidc's crypto passphrase, at least 32 characters | ```sh docker run --rm -p 8080:8080 --env-file .env \ -v "$PWD/config/drawbridge.yaml:/etc/drawbridge/drawbridge.yaml:ro" \ -v "$PWD/secrets:/run/drawbridge:ro" drawbridge-gateway ``` The secrets are never written into the rendered Apache config: it says `OIDCClientSecret "${DRAWBRIDGE_OIDC_CLIENT_SECRET}"` and Apache reads the value from its environment. Keys and secrets are never in git. `OPEN_QUESTIONS.md` lists where each real one comes from. #### Try it without Entra The container rig is the local trial: the real gateway image, a mock OpenID Connect provider standing in for Entra, and a tiny echo app. It signs in synthetic users through the mock and checks protected and public paths, spoofed headers, forged callbacks, logout and step-up to an authentication context. Nothing in the rig reaches Entra. A plain run (and the keycloak run) ends with `drawbridge smoke` inside the gateway container, with no options, the way a deployment is checked. ```powershell rig\run.ps1 # Windows ``` ```sh sh rig/run.sh # Linux, macOS ``` The `keycloak` argument swaps the mock for a pinned Keycloak started from `rig/keycloak/realm.json` and runs the sign-in, claims and logout tests against it. Unlike the mock, that provider checks the client secret and PKCE, signs in only the realm's two synthetic users, and refuses redirect URIs it was not given, so the run proves the round trip against a strict OpenID Connect implementation. ```powershell rig\run.ps1 keycloak # Windows ``` ```sh sh rig/run.sh keycloak # Linux, macOS ``` The `rotation` argument walks a crypto passphrase change through the running gateway without recreating it. It signs in, saves the session cookie, re-renders the Apache config with the new passphrase while keeping the old one as mod_auth_openidc's documented previous value, sends Apache a graceful reload, and replays the saved cookie. The run documents what the pinned module actually does: it accepts the two values and starts, but its shared-memory session store is rebuilt empty on every reload, so the saved cookie is refused and the browser is sent to sign in again. The same refusal is then shown with the old passphrase dropped, and after the gateway container is recreated with a fresh sign-in, so the result is not an accident of the reload. ```powershell rig\run.ps1 rotation # Windows ``` ```sh sh rig/run.sh rotation # Linux, macOS ``` The `redis` argument runs the gateway with its sessions in a Redis service (`gateway.session_store: redis`), signs in, sends Apache a graceful reload, and replays the saved cookie, which must still be accepted. ```powershell rig\run.ps1 redis # Windows ``` ```sh sh rig/run.sh redis # Linux, macOS ``` The `redis-rotation` argument changes the castle password with the sessions in Redis. It signs in under passphrase A, reloads with B current and A previous (`DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS`), and checks that the saved cookie is still accepted and that a new sign-in works under B. It then reloads with B alone: the cookie from A is sent back to sign in (a redirect, not an error page) while the session from B keeps working. Last, it recreates the gateway from its environment on B, the way an operator finishes a rotation, and the session from B survives that too. ```powershell rig\run.ps1 redis-rotation # Windows ``` ```sh sh rig/run.sh redis-rotation # Linux, macOS ``` The `multi` argument runs two gateway instances that share one Redis service and serve the same hosts, and rolls the redis-rotation steps across them one instance at a time (`MultiInstanceRotationTest`). On A, a session signed in through the first opens the app on the second. Mid-roll (the first on B current and A previous, the second still on A), that session opens both, and a session the second issues opens the first; but a session the first issues under B is sent to sign in by the second, which does not know B yet. Once both hold B and A, a session either one issues opens the app on the other. Last, A retires on both: both send the session from A back to sign in (a redirect, not an error page), and the sessions from B keep working on both. ```powershell rig\run.ps1 multi # Windows ``` ```sh sh rig/run.sh multi # Linux, macOS ``` The `trial` argument runs the trial kit in `trial/` (one gateway and the throwaway whoami app, the smallest real deployment, ready to copy onto a pre-production host) against the mock provider. It signs in through whoami, runs the smoke check, rolls the gateway back to a "previous" image while whoami keeps running, and checks again. [First deployment](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/docs/deploying/first-deployment.md) walks the same kit on a real host. ```powershell rig\run.ps1 trial # Windows ``` ```sh sh rig/run.sh trial # Linux, macOS ``` When the rig is green, the next step is the first real sign-in: [ENTRA_TEST.md](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/ENTRA_TEST.md). #### Register Drawbridge in Entra ID One app registration covers every app host. In the Entra admin center, under App registrations: 1. **New registration.** Single tenant. Platform **Web**. 2. **Redirect URIs.** One per app host: `https:///_drawbridge/oidc/callback` (for example `https://app1.apps.wayne.edu/_drawbridge/oidc/callback`). Each host gets its own session, so each needs its own redirect URI; add one whenever an app is added to the config. Leave the implicit grant boxes unticked: the gateway uses the authorization code flow with PKCE. 3. **Certificates & secrets.** Make a client secret and put it in the deployment's secret store as `DRAWBRIDGE_OIDC_CLIENT_SECRET`. Put its expiry date in `DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES` (`YYYY-MM-DD`): Entra secrets expire, the gateway cannot sign anyone in once it has, and with the date set `config:validate`, `/metrics` and the container log count down to it (see `OPEN_QUESTIONS.md`, E-6). 4. **Token configuration.** Add the optional ID token claims the config reads: `accessid` (the AccessID, transformed from the user principal name with `ExtractMailPrefix`; this is what the example config uses for `oidc.user_claim`), `email`, `auth_time`, and `acrs` if any path uses an authentication context. Add `wsu_roles` as a mapped claim (the source attribute is `user.wsuRoles`, an on-premises AD attribute; the emitted claim is `wsu_roles`) and set `acceptMappedClaims: true` in the app manifest, so no custom signing key is needed and the metadata URL stays plain; list it in `oidc.extra_claims`. A tenant that does not send `accessid` leaves `oidc.user_claim` at `preferred_username`. 5. **Overview.** Copy the Directory (tenant) ID into `oidc.issuer` (`https://login.microsoftonline.com//v2.0`) and the Application (client) ID into `oidc.client_id`. Neither is a secret, but neither belongs in this repository either. The issuer is in Playbook as `SESAME_OAUTH2_ISSUER`; see the WSU values (Playbook) section below. 6. **Authentication contexts** (only if a path uses `auth_context`): in Conditional Access, create the context (`c1` ...), and a policy that targets it with whatever it should demand. Before the first real sign-in, walk [ENTRA_TEST.md](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/ENTRA_TEST.md): every setting by name, and what to check for each open question E-1 to E-8. ### Getting the 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 `/enterprise-apps/images/drawbridge-gateway:` (for example `/enterprise-apps/images/drawbridge-gateway:0.6.2`). `` is the stack's container registry; Enterprise Applications has its address. There is no `latest` tag: pin a release. For a first run on a pre-production host (a throwaway app, the health and smoke checks, logs and a rollback), see [First deployment](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/docs/deploying/first-deployment.md) and the kit in `trial/`. ```sh docker pull /enterprise-apps/images/drawbridge-gateway:0.6.2 ``` The publish job prints the digest it pushed. Verify the image you pulled against it: ```sh docker inspect --format='{{index .RepoDigests 0}}' /enterprise-apps/images/drawbridge-gateway:0.6.2 ``` The image carries OCI labels (`org.opencontainers.image.source`, `.revision`, `.version`, `.licenses`) set from the pipeline's commit; a local `docker build` leaves them empty. The image also refuses to build if Debian serves apache2 or mod_auth_openidc below the versions the rig tested: the Dockerfile checks the installed versions with `dpkg --compare-versions` right after the install (apt-get has no `>=` syntax) and stops the build with a clear message when one is lower. The floor is apache2 2.4.69-1~deb13u1 (checked 2026-11-03) and mod_auth_openidc 2.4.17-1+deb13u1 (raised 2026-11-08 for CVE-2026-54789, a bug in the state-cookie parser), both against debian:trixie-slim. To raise it, bump the two versions in the Dockerfile's install step and in `tests/Unit/DockerfileFloorTest.php`, which pins them. The advisory watch says when to raise it. `composer advisories` reads the floors and the Debian release from the Dockerfile, asks [OSV.dev](https://osv.dev/) (which republishes Debian's security tracker) which advisories still affect each floor version, and exits 1 when Debian has a fixed build above a floor, naming the advisory and the fix. An advisory with no fix yet is listed to watch and does not fail. It needs the network, so it is not part of `composer ci`; the GitLab `advisories` job runs it from a pipeline schedule or by hand. ### WSU values (Playbook) A drawbridge lifts for barges it knows; these two settings tell it who is coming. Both carry Wayne State's shared values, and both come from [Playbook](https://git.wayne.edu/enterprise-apps/playbook), the private repository of the university's shared `KEY=value` lines: never secrets, never per-app values. Drawbridge does not read Playbook in code; it is where a person looks up the values to type into `config/drawbridge.yaml` and `.env`. | Playbook key | Drawbridge setting | Where it goes | |---|---|---| | `SESAME_OAUTH2_ISSUER` | `oidc.issuer` | `config/drawbridge.yaml`: the Entra issuer for the Wayne State tenant. Copy it from Playbook; never write a tenant id by hand. | | `HELMET_PROXIES` | `DRAWBRIDGE_TRUSTED_PROXIES` | `.env`: the front proxy addresses, comma-separated CIDRs. | **curl (Linux, macOS).** ``` curl --fail -H "PRIVATE-TOKEN: $GITLAB_TOKEN" "https://git.wayne.edu/api/v4/projects/enterprise-apps%2Fplaybook/repository/files/playbook.env/raw?ref=main" -o .env.playbook ``` **PowerShell (Windows).** ```powershell Invoke-WebRequest -Headers @{ 'PRIVATE-TOKEN' = $env:GITLAB_TOKEN } -Uri "https://git.wayne.edu/api/v4/projects/enterprise-apps%2Fplaybook/repository/files/playbook.env/raw?ref=main" -OutFile .env.playbook ``` **A clone.** ``` git clone https://git.wayne.edu/enterprise-apps/playbook.git ``` The curl and PowerShell commands download the values to `.env.playbook`; copy the two you need out of it. The secrets (`DRAWBRIDGE_OIDC_CLIENT_SECRET`, `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE`, `DRAWBRIDGE_METRICS_TOKEN`), the client id and the signing key are never in Playbook. The token is your own: `read_api` for curl, `read_repository` for clone. Playbook is private on git.wayne.edu. If you get a 404, ask the Enterprise Applications team for read access. ### Configuration One YAML (or PHP array) file declares the gateway, the OpenID Connect provider and each app. `config/drawbridge.example.yaml` is annotated. ```yaml oidc: issuer: https://login.microsoftonline.com//v2.0 client_id: client_secret_env: DRAWBRIDGE_OIDC_CLIENT_SECRET # the NAME of the variable, never the secret user_claim: accessid # the AccessID; preferred_username for a tenant that does not send it extra_claims: [wsu_roles] # copied into the assertion when present; rename a long claim with {from, as} apps: - id: app1 host: app1.apps.wayne.edu upstream: http://app1:8080 mode: assertion # the only mode default: login # what a path with no rule gets public: [/up, /assets/] protected: [/admin/, {path: /admin/payroll/, auth_context: c1}] api: [/api/] ``` The `oidc` block also takes `metadata_url` (defaults to the issuer's `/.well-known/openid-configuration`), `attribute_claims` (which claim feeds `email`, `name` and `affiliations`; `null` turns one off) and `amr_map` (Entra `amr` values to the values SESAME's MFA check reads; the default maps `pwd`, `mfa`, `ngcmfa` as `mfa`, `otp`, `rsa`, `wia`, and the REFEDS MFA URI). The issuer must be https; plain http is accepted only for a `.test` host, which is what the local rig uses. Path rules are exact (`/up`) or prefix (a trailing slash, `/assets/`). There are no wildcards and no regular expressions. The longest rule wins, and an exact rule beats a prefix of the same length. 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). `/_drawbridge` belongs to the gateway. #### Session lifetimes The `gateway` block sets how long a sign-in lasts and how long it may sit unused: `session_seconds` (default 28800 seconds, 300 to 604800) and `session_idle_seconds` (default 3600 seconds, 60 to 86400). Each app host renders them as mod_auth_openidc's `OIDCSessionMaxDuration` and `OIDCSessionInactivityTimeout`. #### Three sessions, three clocks A signed-in visitor has up to three sessions at once. Each has its own lifetime and its own owner, and ending one does not end the others. | Layer | Default lifetime | What ends it | What the visitor sees next | |---|---|---|---| | Entra (the identity provider) | set by Entra and its Conditional Access policy, not by Drawbridge | Entra's own policy, or the visitor signing out of Entra | Entra may sign them in again without a prompt, or ask for credentials | | Gateway (mod_auth_openidc, one per app host) | 8 hours total, 1 hour idle (`session_seconds`, `session_idle_seconds`) | either clock, the `?logout=` link above, `drawbridge revoke`, or, with the default `shm` store, a restart or reload of the gateway (the cache lives in shared memory and starts empty) | a protected path sends them to Entra; an `api` path answers 401 | | App (SESAME) | 720 minutes total, 120 minutes idle (`session.absolute_minutes`, `session.idle_minutes`) | either clock, or the app calling `sesame_logout()` | the app's login route asks the gateway for a fresh assertion | How they fit together: - The assertion is used once, when the app signs the visitor in (it lives 60 seconds and SESAME's replay guard refuses a second use). After that the app's session runs on SESAME's clocks; a protected page reads SESAME's session, not the gateway. - So the app session can outlast the gateway session. With the defaults it can: the app allows 12 hours, the gateway 8. The gateway session ending does not sign anyone out of the app; the visitor finds out the next time the app sends them through its login route. To make the app never outlive the gateway sign-in, set the app's `session.absolute_minutes` to `session_seconds / 60` or less (480 for the default). - Signing out through the `?logout=` link ends the gateway session and asks Entra to end its own for that browser, not the app's. The app ends its own session first (`sesame_logout()`), then sends the browser to the link. - With the default `shm` store, a gateway restart signs everyone out of the gateway layer only; apps keep their sessions until their own clocks run out. #### Session store The `gateway` block decides where the gateway sessions are kept: - `shm` (the default): Apache's shared memory, encrypted per host. One instance, zero extra parts; a restart or graceful reload rebuilds the store empty, so everyone signs in again. Removing the setting returns to this behavior. - `redis`: the sessions live in a Redis server named by `redis_host` (and `redis_port`, default 6379). Sessions then survive a restart and a graceful reload (the rig's `redis` run proves the reload: `RedisTest::testSessionSurvivesAGatewayReload`; the last step of `redis-rotation` proves the restart: `RedisRotationTest::testRestartTheSessionSurvivesAGatewayRecreatedFromItsEnvironment`), and more than one gateway instance can serve the same hosts when every instance points at the same Redis and uses the same passphrase (two instances in the rig: `MultiInstanceRotationTest`). A passphrase change kept graceful by `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS` needs this store, and is proven by `rig/run.sh redis-rotation` (`RedisRotationTest`). The password never goes in the config file: it comes from `DRAWBRIDGE_REDIS_PASSWORD`. Changing the passphrase with the `redis` store, without signing anyone out (with several instances, take each step on all of them before the next; `rig/run.sh multi` proves it with two instances on one Redis, and shows that mid-step an instance still on the old value sends sessions sealed under the new one to sign in again, so roll them quickly): 1. Set `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS` to the value in use now and `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE` to a new one, then restart the gateway. Old sessions keep working; new sign-ins use the new value. 2. Wait `session_seconds` (8 hours by default). 3. Remove `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS` and restart. A session still sealed under the old value is sent to sign in, not shown an error. Redis holds the sessions, not the revocation list: ending one person's sessions from outside is `drawbridge revoke` and its revocation list (see [Signing out](#signing-out)), which works with either store and which every gateway instance must share. ### Environment variables | Variable | Default | Meaning | |---|---|---| | `DRAWBRIDGE_CONFIG` | `/etc/drawbridge/drawbridge.yaml` | the per-app config file | | `DRAWBRIDGE_PORT` | `8080` | port Apache listens on (non-root, so above 1024) | | `DRAWBRIDGE_PUBLIC_SCHEME` | `https` | how browsers reach the gateway; feeds `ServerName`, `X-Forwarded-Proto`, the redirect URI | | `DRAWBRIDGE_PUBLIC_PORT` | empty | public port when it is not the scheme default | | `DRAWBRIDGE_COOKIE_SECURE` | `true` | Secure session cookie; `false` only for a plain-HTTP local rig | | `DRAWBRIDGE_TRUSTED_PROXIES` | empty | comma-separated CIDRs allowed to set `X-Forwarded-For`; empty trusts nobody | | `DRAWBRIDGE_OIDC_CLIENT_SECRET` | none, required | the Entra client secret (or whichever name `oidc.client_secret_env` gives) | | `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE` | none, required | 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` | | `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS` | unset | 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 | | `DRAWBRIDGE_OIDC_CLIENT_SECRET_FILE` | unset | path to a file holding the client secret (Docker secrets, Kubernetes volumes); used only when `DRAWBRIDGE_OIDC_CLIENT_SECRET` is unset or empty | | `DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES` | unset | the day the client secret expires (`YYYY-MM-DD`, from Entra; not a secret). `config:validate` prints the days left and the state (`ok`, `soon` at 30 days or fewer, `urgent` at 7 or fewer, `expired`), `/metrics` serves `drawbridge_oidc_client_secret_days_left`, and `render` warns once in the container log from `soon` on. Never refuses a request; a value that is not a real date stops the container at start | | `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_FILE` | unset | the same for the crypto passphrase | | `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS_FILE` | unset | the same for the previous passphrase | | `DRAWBRIDGE_SIGNING_KEY_FILE` | `/run/drawbridge/signing.key` | ES256 private key for assertions (mounted) | | `DRAWBRIDGE_SIGNING_KEY_ID` | `drawbridge-1` | `kid` in each token header; change it when the key changes (name keys by date, for example `drawbridge-2026-11`) | | `DRAWBRIDGE_SESSION_CACHE_ENTRIES` | `1000` | 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) | | `DRAWBRIDGE_RUN_DIR` | `/tmp/drawbridge` | scratch for rendered config, locks and the session cache | | `DRAWBRIDGE_LOG_LEVEL` | `warn` | Apache log level | | `DRAWBRIDGE_EVENT_LOG` | `/dev/stdout` | where the JSON event log goes (sign-in, failed sign-in, sign-out, denied, revoked) | | `DRAWBRIDGE_METRICS_TOKEN` | none | bearer token that may read `/metrics`; empty turns the endpoint off unless an allow list is set | | `DRAWBRIDGE_METRICS_ALLOW` | none | comma list of client IPs/CIDRs allowed to read `/metrics`; empty trusts no address | The file form is for platforms that hand secrets over as files. The gateway image reads the file at start, strips the trailing newline, and stops with a clear message (naming the variable, never the path or the contents) if the file is unreadable or empty. A plain variable always wins when both are set. The file form applies to these three default names only; a custom `oidc.client_secret_env` name keeps working as a plain environment variable. ### Commands Run as `php bin/drawbridge ` (or `vendor/bin/drawbridge` when installed as a dependency). | Command | Does | |---|---| | `config:validate` | checks the config and prints every problem at once, then the provider settings (never the secret, only whether its variable is set, and its expiry date with the days left when `DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES` is set); exit 1 if any | | `explain ` | says which rule applies to a request, the authentication context and groups it needs, and whether it is denied | | `revoke ... [--list]` | ends every gateway session those people hold now, on every app host (the revocation list the gateway rereads each second) | | `smoke [--url=URL] [--app=ID]... [--format=json]` | checks a running gateway without signing anyone in: `/_drawbridge/up`, an unknown host, each app's login, api, deny and public paths, the redirect URI and PKCE, a made-up callback, the app host's clock against the gateway's (more than 10 s apart fails) and `/metrics`; read-only, exit 1 if a check fails. Inside the container: `docker exec /opt/drawbridge/bin/drawbridge smoke` | | `render` | checks the two secrets in the environment, then writes `apps.conf` and `policy.lua` for Apache (the entrypoint runs this); warns on stderr when the client secret expires in 30 days or fewer | | `keys:generate` | makes an ES256 key pair; refuses to overwrite a file | | `keys:jwks --key=KID=FILE ... [--out=FILE]` | writes the key set file apps verify with: the public keys, current then next, as a JWKS; refuses a private key | | `signer:map` | the long-running process behind Apache's `prg:` map (not for people) | ### Run the checks Maintainers: how to build, test and release this project, and where its data comes from, is in [MAINTAINING.md](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/MAINTAINING.md). ```sh composer ci # manifest, unit tests, Pint, agent-ready pages, PHPStan level 8, composer audit, docs build composer advisories # needs the network: does the image's module floor admit a build Debian has patched? ``` The PHPStan and Pint settings come from Pinstripe, the stack's coding standard: `phpstan.neon` includes the raw PHP cut, and `pint.json` uses the same `per` preset as Pinstripe's `pint/per.json`. This repository adds only its own paths, PHP version range and excludes. In Docker, with no local PHP: ```powershell docker run --rm -v "${PWD}:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh -c "composer install --no-interaction && composer ci" ``` The accessibility gate runs Preflight's own checker (vendored from 0.9.0 and pinned by a test) against the front page and every docs page in a real Chromium browser inside Docker, so no host browser is needed: axe-core 4.14.0, light and dark at 320 and 1280 px, with the WCAG 1.4.10 reflow check, exactly what the a11y CI job checks. `sh scripts/a11y.sh` on Linux and macOS, `scripts\a11y.ps1` on Windows. The unit suite checks the assertion against a mirror of SESAME's `gateway` driver rules (`tests/Support/SesameContract.php`). To check it against the real driver instead, point `SESAME_PATH` at a SESAME checkout that has been installed (`composer install` in it) and run the integration suite; without it the suite skips, so `composer ci` stays green: ```powershell docker run --rm -v "${PWD}:/app" -v "C:\path\to\sesame:/sesame:ro" -e SESAME_PATH=/sesame -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 sh -c "composer install --no-interaction && vendor/bin/phpunit --filter RealSesame" ``` The container rig runs the real gateway image with a mock OpenID Connect provider ([mock-oauth2-server](https://github.com/navikt/mock-oauth2-server), pinned) standing in for Entra, and a tiny echo app. It covers sign-in, public and protected paths, header spoofing (including forged `OIDC_*` headers), path tricks, forged callbacks, step-up to an authentication context, signature checks against SESAME's `gateway` driver rules, and logout. The mock signs in anyone with whatever claims the test types into its form, which is exactly what you want from a stunt double. Nothing in the rig reaches Entra. ```powershell rig\run.ps1 # Windows ``` ```sh sh rig/run.sh # Linux, macOS ``` ### Using the assertion in an app Point SESAME's `gateway` driver at Drawbridge: the same issuer, the app's host as the audience, the key set file, and the header `X-Sesame-Assertion`. Apps do not parse the token themselves. #### Signing keys and rotation The gateway signs with one ES256 key at a time and names it in the `kid` header. Apps get the public keys as one key set file (a JWKS) that always holds the **current** key and the **next** one, written by `keys:jwks`, and point SESAME at it with `SESAME_GATEWAY_JWKS_FILE`. Because every app already trusts the next key, the gateway can switch to it without any app changing first; the apps pick up a fresh file afterwards. Rotate every 12 months (and at once on a suspected leak), and remove a retired key no sooner than 5 minutes after the switch. The steps, including the emergency ones, are in [Rotating the signing key](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/docs/guides/rotating-the-signing-key.md); the reasoning is [ADR-0001](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/ADR/ADR-0001-signing-key-distribution-and-rotation.md). Two keys on the ring: the guard can change locks without anyone waiting outside the gate. ### Log events Besides the access log, the gateway writes one JSON line for each sign-in, failed sign-in, sign-out, refusal and revoked session, and nothing for an ordinary request: ```json {"v":1,"event":"drawbridge.denied","time":"2026-11-07T15:04:05Z","host":"app1.apps.wayne.edu","path":"/admin/reports/q3","status":403,"user":"ab1234","rule":"login","reason":"group","client":"(client address)"} ``` The events are `drawbridge.signin`, `drawbridge.signin_failed`, `drawbridge.signout`, `drawbridge.denied` and `drawbridge.revoked`, each refusal with a `reason`. The path is logged without its query string, and no cookie, token or claim but the subject is ever written. `DRAWBRIDGE_EVENT_LOG` picks the file (default `/dev/stdout`). [Log events](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/docs/reference/log-events.md) documents every field. ### Metrics Drawbridge can expose a Prometheus `/metrics` endpoint, off by default. It is on when `DRAWBRIDGE_METRICS_TOKEN` (a bearer token) or `DRAWBRIDGE_METRICS_ALLOW` (a comma list of client IPs/CIDRs) is set, and a request is served when it presents the token or comes from an allowed address. A disabled or misconfigured endpoint answers 404 and an unauthorized request answers 403, so the route is never advertised and never served to a stranger. The client address is `REMOTE_ADDR` (the real client), never a client-supplied header, so a spoofed `X-Forwarded-For` cannot grant access, and the token is compared in constant time. When you wire it up yourself, point a web server at `bin/metrics` for the path. In Apache, a location such as: ```apache SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 ScriptAlias /metrics /opt/drawbridge/bin/metrics ``` serves it (the `SetEnvIf` passes the bearer token through; without it only the allow list works). In the gateway image the endpoint is a php-cgi child: `render` maps `^/metrics$` to `bin/metrics` with a virtual-host-level `ScriptAliasMatch` beside the Location block that stands outside sign-in and signing, and a fixup hook hands the child the access rules, because Apache passes no server environment to a CGI child. The endpoint serves only what it can see truthfully: | Metric | Type | Meaning | |---|---|---| | `drawbridge_build_info{version}` | gauge | the gateway is up, and which release (`Version::CURRENT` in `src/Version.php`, the same value `drawbridge --version` prints) | | `drawbridge_signing_requests_total` | counter | signing requests the assertion signer received | | `drawbridge_assertions_signed_total` | counter | assertions the signer signed successfully | | `drawbridge_assertion_errors_total{reason}` | counter | signing requests the signer refused or failed, by reason | | `drawbridge_oidc_client_secret_days_left` | gauge | whole days until the Entra client secret expires, negative once it has; only when `DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES` is set, and worked out on every scrape (never kept in the store) | The signing counters cross from the long-running signer to the per-request endpoint through a shared file-backed store: one JSON file per metric family in a directory (default `/tmp/drawbridge-metrics`, moved by `DRAWBRIDGE_METRICS_DIR`), written atomically while a per-family lock is held, so a reader always sees a whole file and two writers never lose an increment. Every process in the gateway container runs as the same UID, so plain file permissions are enough. Without a shared store the endpoint registers no counters at all, because a counter that is always zero is not shown. Apache, not PHP, serves the requests, so request counts by path class are not exposed here either, and public requests and sign-in failures never reach the PHP side; mod_auth_openidc would need its own status or log scraping to expose those. Labels carry no identity, claim, or token, and the `reason` label is folded to a fixed set (refused, failed, other), so it stays low-cardinality. ### Documents - `BEST_PRACTICES.md`: the practices the gateway holds itself to, each with its sources, one tag and the tests that hold it. - `ENTRA_TEST.md`: the first real Entra test: what you need to do. - `OPEN_QUESTIONS.md`: what is unanswered, what is missing, what is not built yet. - `ADR/`: decisions about Drawbridge itself, one file each (ADR-0001: signing key distribution and rotation). - `CHANGELOG.md`: what changed. - `site/`: the front page, a static sheet set for the gatehouse (`site/index.html`; see `site/README.md`). It and the docs pages follow the reader's dark mode: the drafting office after hours. On Citadel it is served by the raw-PHP deploy layer in [`deploy/`](https://git.wayne.edu/enterprise-apps/drawbridge/blob/HEAD/deploy/): a Squire kit whose front controller serves `site/` behind HELMET's security headers. For local development, keep serving `site/` directly. ### The name It is a drawbridge, so it goes up on strangers and down on friends. If you find a header it should have caught, raise the issue. The moat is only as good as the people who keep reporting where it is shallow. ### License MIT. Copyright Wayne State University. --- Source: https://drawbridge.apps.wayne.edu/ A-101 Gatehouse · section A-A ## Drawbridge Comes down for signed-in people. - **draw·bridge noun, not an acronym**: The one way into the Citadel. It comes down only for people who are signed in, and goes back up for everyone else. Drawbridge is Apache with mod_auth_openidc, set up as one OpenID Connect client for Microsoft Entra ID. Its home will be **auth.apps.wayne.edu**, in front of every app on Citadel. It checks that the visitor has a session, drops any identity header they sent, and passes the app a 60-second ES256-signed assertion that SESAME verifies. **Works alongside [WELD](https://weld.apps.wayne.edu/).** You don't install Drawbridge in your app; it's a Citadel service. It isn't in front of any apps yet, so WELD signs in with [SESAME](https://sesame.apps.wayne.edu/) directly for now. Once the gateway is live, Citadel apps switch SESAME to its `gateway` driver. [Build the gatehouse](https://drawbridge.apps.wayne.edu/#build-title) [Read the section](https://drawbridge.apps.wayne.edu/#section-title) ![Drawbridge mark: a cream gatehouse tower on a green tile, its bridge lowered on a gold chain](https://drawbridge.apps.wayne.edu/brand/drawbridge-avatar-256.png) The bridge is down for a signed-in visitor. A forged header would be stripped at the gate, before sign-in runs. A-201 Longitudinal section ### One request through the gatehouse Apache httpd with four modules and a small PHP component. Every request takes the same passage, in this order. 1. ### Browser Sends whatever headers it wants, forged ones included. the approach 2. ### Guard Strips every inbound identity header, in every hyphen and underscore spelling, before anything else runs. mod_lua 3. ### OpenID Connect client One Entra ID client for every app, with a separate session for each app host. Without a session, the browser is sent to Entra to sign in. mod_auth_openidc 4. ### Signer Signs a new ES256 assertion for each request. If signing fails, the visitor gets a 503. mod_rewrite prg: map + PHP 5. ### App Receives the request with one signed header and checks it with SESAME's `gateway` driver. mod_proxy login No session? The browser goes to Entra to sign in and comes back to the page. api Without a session it gets a plain **401**, so a script never receives an HTML login page. public Passes through with no identity attached. A path is public only if the config says so. deny The gateway's own **403**, signed in or not. The path never reaches the app, and nobody is asked to sign in for it. groups Signed in but holding none of the rule's groups in the verified ID token: **403**, and nothing reaches the app. signer down **503**. Nothing reaches the app unsigned. Why a moat and not a lock on every door: each app doing its own OpenID Connect is another chance to get a nonce, a state check or a token signature wrong. We'd rather get that right once, in a maintained module (mod_auth_openidc). Each app then checks one small signed token. A-301 Door schedule ### Which doors need a key Each app lists its paths in one config file, and nothing else decides. A rule is exact (`/up`) or a prefix (`/assets/`). The longest match wins, and an exact rule beats a prefix of the same length. There are no wildcards or regular expressions, and the query string is never part of the match. **Door schedule for `app1.apps.wayne.edu`, from `config/drawbridge.example.yaml`** | Door | Path | Rule | Needs | | --- | --- | --- | --- | | D1 | `/up` | exact | public | | D2 | `/assets/` | prefix | public | | D3 | `/admin/` | prefix | login | | D4 | `/admin/payroll/` | prefix | login + context `c1` | | D5 | `/admin/reports/` | prefix | login + a group | | D6 | `/api/` | prefix | api | | D7 | `/telescope/` | prefix | deny | | D0 | *anything else* | default | login | ``` $ php bin/drawbridge explain app1.apps.wayne.edu /admin/users app1 /admin/users => login (matched as /admin/users, by the rule for /admin/) ``` This box runs the same matching rules in your browser, written to agree with `explain` for the example config. The output lines are the real command's wording. A-401 Detail · the assertion ### What crosses the bridge A compact JWT, made fresh for every request and valid for 60 seconds by default. The signing key stays in the signer. header ``` { "alg": "ES256", "typ": "drawbridge+jwt", "kid": "drawbridge-1" } ``` claims (sample) ``` { "iss": "https://auth.apps.wayne.edu", "aud": "app1.apps.wayne.edu", "sub": "ab1234", "iat": 1798000000, "nbf": 1798000000, "exp": 1798000060, "jti": "4f1c9a2e7b3d", "auth_time": 1797999400, "amr": ["pwd", "mfa"], "email": "…", "name": "…", "affiliations": ["staff"] } ``` Sent as `X-Sesame-Assertion`. An app gets the signed assertion or nothing: there is no unsigned mode. #### Left at the gate The guard removes these from every request, in any hyphen or underscore spelling, before authentication runs. Then the gateway sets its own. - ~~X-Authenticated-\*~~ - ~~X-Sesame-\*~~ - ~~X-Drawbridge-\*~~ - ~~Remote-User~~ - ~~X-Remote-User~~ - ~~X-Forwarded-\*~~ - ~~Forwarded~~ - ~~X-Real-IP~~ - ~~X-Auth-Request-\*~~ - ~~OIDC-Claim-\*~~ - ~~Proxy~~ `Connection` is trimmed to `close`, `keep-alive` and `upgrade`, so a client cannot ask the proxy to drop a header the gateway set. A-501 General notes ### Eighteen notes from 55 practices From `BEST_PRACTICES.md`: 55 practices, 43 of them enforced by a named test. The contractor shall not improvise. 1. **Strip first.** Inbound identity headers go, in any spelling, before authentication runs on any request. 2. **Fail closed.** No session, no signature, a refused path, a missing key or a bad config means no access. 3. **Public is a decision.** A path with no rule gets the app's default: `login`, or `deny` for an app that lists every path it has. Public paths carry no identity. 4. **Match the normalized path.** Encoded slashes, backslashes, semicolons and bad UTF-8 are treated as protected. 5. **Exact or prefix, nothing clever.** No wildcards or regular expressions. The Apache pattern is built from the literal path. 6. **Shut what nobody should reach.** A `deny` path gets the gateway's 403 page and never reaches the app. 7. **Groups come from the token.** A rule's groups are read from the validated ID token, whole and case-sensitive, never from a header. 8. **Sign narrowly and briefly.** ES256, a pinned `typ`, one audience per app, a fresh `jti` each time. 9. **Let the module do OpenID Connect.** Drawbridge writes no OAuth client. Forged callbacks and missing contexts are refused. 10. **One session per app host.** A session cookie carried to another host opens nothing there. 11. **Raise it on demand.** `drawbridge revoke` ends every session a person holds, on every app host, without waiting for it to expire. 12. **Sign out at the top level.** Every sign-out hop is a redirect, never an iframe, so it works with third-party cookies blocked. 13. **Overwrite forwarded headers.** `X-Forwarded-*` come from the gateway, never the client. 14. **Secrets stay out.** Keys are mounted files; the client secret and passphrase live in the environment. The event log names the person and a reason, never a cookie, a token or another claim. 15. **Do not trust the network.** The app verifies the signature even if only the gateway can reach it. 16. **Run small and boring.** Non-root, port above 1024, state under `/tmp`, logs to stdout. 17. **Watch the floor.** `composer audit` runs in CI, and `composer advisories` asks OSV.dev whether Debian has patched the image's Apache or mod_auth_openidc. 18. **Add headers, never overwrite.** The gateway's headers ride on proxied answers only where the app sent none, so HELMET's stay. A-601 Construction sequence ### Build the gatehouse You need Docker and nothing else. The PHP component needs PHP 8.3 or newer and Composer, and these steps run both inside the `composer:2.11.1` container. **Windows (PowerShell)** ``` PS> git clone https://git.wayne.edu/enterprise-apps/drawbridge.git drawbridge; cd drawbridge PS> docker run --rm -v "${PWD}:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer install --no-interaction PS> Copy-Item .env.example .env PS> Copy-Item config\drawbridge.example.yaml config\drawbridge.yaml PS> docker run --rm -v "${PWD}:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 php bin/drawbridge config:validate --config=config/drawbridge.yaml The config is valid: 1 app(s). OpenID Connect provider: https://login.microsoftonline.com//v2.0 … client id, secret (set or not, never its value), claims, amr map - app1 (app1.apps.wayne.edu): default login, 7 path rule(s), mode assertion, auth context: /admin/payroll/ c1 PS> docker build -f docker/gateway/Dockerfile -t drawbridge-gateway . ``` **Linux and macOS** ``` $ git clone https://git.wayne.edu/enterprise-apps/drawbridge.git drawbridge && cd drawbridge $ docker run --rm -v "$PWD:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer install --no-interaction $ cp .env.example .env $ cp config/drawbridge.example.yaml config/drawbridge.yaml $ docker run --rm -v "$PWD:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 php bin/drawbridge config:validate --config=config/drawbridge.yaml The config is valid: 1 app(s). OpenID Connect provider: https://login.microsoftonline.com//v2.0 … client id, secret (set or not, never its value), claims, amr map - app1 (app1.apps.wayne.edu): default login, 7 path rule(s), mode assertion, auth context: /admin/payroll/ c1 $ docker build -f docker/gateway/Dockerfile -t drawbridge-gateway . ``` #### Then raise it The entrypoint won't start without two files mounted read-only and two secrets in the environment. None of them goes in git. - `drawbridge.yaml` the per-app config - `signing.key` the ES256 key; `keys:generate` makes one - `DRAWBRIDGE_OIDC_CLIENT_SECRET` the Entra client secret, from the app registration - `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE` encrypts sessions; 32+ characters ``` $ docker run --rm -p 8080:8080 --env-file .env \ -v "$PWD/config/drawbridge.yaml:/etc/drawbridge/drawbridge.yaml:ro" \ -v "$PWD/secrets:/run/drawbridge:ro" drawbridge-gateway ``` #### The drafting kit `php bin/drawbridge ` - **`config:validate`**: checks the config and prints every problem at once - **`explain `**: says which rule applies, and why - **`render`**: writes `apps.conf` and `policy.lua` for Apache - **`keys:generate`**: an ES256 key pair; refuses to overwrite - **`keys:jwks`**: the key set file apps verify with: current and next public key - **`revoke `**: ends every session a person holds, on every app host, now - **`smoke`**: knocks on every door of a running gateway, without signing in ([A-602](https://drawbridge.apps.wayne.edu/#inspect-title)) ``` $ composer ci # manifest, unit tests, Pint, agent-ready pages, PHPStan level 8, composer audit, docs build PS> rig\run.ps1 # the real image, a mock OpenID Connect provider and an echo app (Windows) $ sh rig/run.sh # the same rig on Linux and macOS ``` The rig covers sign-in, public and protected paths, header spoofing (forged `OIDC_*` headers too), path tricks, forged callbacks, step-up to an authentication context, deny and group rules, revocation, the event log, signature checks against SESAME's rules, a sign-out that still works with third-party cookies blocked, a passphrase change rolled across two gateways on one Redis, and the trial kit as shipped, rolled back and inspected again. Nothing in it reaches Entra. A-602 Field inspection ### Inspect before the gate opens The rig proves the image. `drawbridge smoke` proves a deployment of it: one command inside the container that knocks on every door once, from the outside, without a key. It signs nobody in and changes nothing, so it is safe on a gateway that is already serving people. Field report - **Site**: `app1.apps.wayne.edu` - **Inspector**: `drawbridge smoke` - **Key used**: none ``` $ docker compose exec gateway /opt/drawbridge/bin/drawbridge smoke ``` 1. OKgateway up/\_drawbridge/up answers 200 ok 2. OKgateway unknown-hosta host that is not in the config gets 403 3. OKapp1 login/admin/ sends a visitor to sign in at login.microsoftonline.com, back to https://app1.apps.wayne.edu/\_drawbridge/oidc/callback, with a Secure state cookie 4. OKapp1 api/api/ answers a bare 401 without a session 5. OKapp1 deny/telescope/ answers 403 and never reaches the app 6. OKapp1 public/assets/ reaches the app (200) with no sign-in 7. OKapp1 headersthe proxied answer carries X-Content-Type-Options and Strict-Transport-Security 8. OKapp1 clockthe app's clock is 0 s from the gateway's (assertions allow 30 s of skew) 9. OKapp1 callbacka made-up code and state sign nobody in (400) 10. OKapp1 metrics/metrics answers 403 without the token and 200 with it (version 0.6.2) 10 passed, 0 failed, 0 skipped. The gateway reports version 0.6.2. Exit 0. Inspect a deployment that went wrong Every door answers the way the config says it should. Exit 0, and the version on the last line is the release now running. #### The trial kit Rehearse the first deployment on a pre-production host before any real app stands behind the gate. `trial/` is the smallest real deployment: the gateway and a throwaway app called whoami on the same image, with no capabilities, read-only mounts and the gateway on loopback only. 1. 1Copy the kit and fill in the files 2. 2Make the signing key and the key set file 3. 3Start it 4. 4Health, then `drawbridge smoke` 5. 5Sign in; whoami shows what it verified 6. 6Read the logs and `/metrics` 7. 7Roll the gateway back, smoke again 8. 8Tear it down ``` PS> rig\run.ps1 trial # Windows $ sh rig/run.sh trial # Linux and macOS ``` The rig runs the kit as shipped, with a mock provider in place of Entra, rolls the gateway back and inspects it again. Green there first, then the real host: [First deployment](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html) walks every step. A-603 Specifications ### Specs for your agent Your coding agent is the contractor. Copy a spec, or open it directly in OpenCode, Claude Code, Codex or ChatGPT. Each spec gives the task and what the agent must leave alone, and tells it to ask you before it guesses. #### Get started with Drawbridge Clone, validate the example config, ask explain about three doors, and run the rig against a mock provider. Nothing reaches Entra. A prompt for your coding agent. Copy it as it stands: ```text You are a coding agent helping a Wayne State University developer stand up Drawbridge on their own machine. Drawbridge is the Citadel auth gateway of WELD, the Wayne State application stack: Apache with mod_auth_openidc in front of every app, one OpenID Connect client for Microsoft Entra ID, a guard that strips every identity header a visitor brings, and a 60-second ES256 assertion that SESAME's gateway driver verifies. Read first: - https://drawbridge.apps.wayne.edu/llms.txt, the index of Drawbridge's pages, each one as Markdown. Work from them, not from memory. - ADVISOR, the stack's MCP server, if it is connected: read_project_docs with project drawbridge, and list_stack_rules with chapter auth. If it is not connected, say so and work from the pages. How to add it: https://advisor.apps.wayne.edu/llms.txt - The README's Install and quick start, Configuration and Commands sections, and config/drawbridge.example.yaml. Task: 1. If this folder is not a checkout, clone it with `git clone https://git.wayne.edu/enterprise-apps/drawbridge.git`. Install with `composer install`, or in the composer:2.11.1 container the README uses if there is no PHP 8.3 here. 2. Copy the example config and the example environment file to their working names, as the README does, then run `php bin/drawbridge config:validate --config=config/drawbridge.yaml`. 3. Run the explain command on three paths of app1 (one public, one protected, one api) and tell me which rule wins each time, and why. 4. Run the container rig: rig\run.ps1 on Windows, sh rig/run.sh on Linux and macOS. It signs in against a mock OpenID Connect provider and never reaches Entra. Constraints: - Never put a real tenant id, client id, client secret, crypto passphrase or signing key in a file git tracks. Keys and secrets are never in git. - Leave the guard and the path rules alone: exact or prefix only, no wildcards, no regular expressions. - Give separate commands for Windows (PowerShell), macOS and Linux wherever they differ. - Ask me before you guess, and before anything talks to a real Entra tenant. Output: the commands you ran, the three explain answers, the rig result, then your questions. ``` #### Or the spec for the app behind the gate #### A Laravel app behind Drawbridge Its door schedule for the gate, and SESAME's gateway driver checking the signed assertion on the way in. A prompt for your coding agent. Copy it as it stands: ```text You are a coding agent putting a Laravel app at Wayne State University behind Drawbridge, the Citadel auth gateway of WELD, the Wayne State application stack. Drawbridge signs the visitor in and sends the app a short-lived signed assertion in the X-Sesame-Assertion header. The app checks it with SESAME's gateway driver and never parses the token itself. Read first: - https://drawbridge.apps.wayne.edu/llms.txt, then the README's Using the assertion in an app and Configuration sections. - SESAME's pages, https://sesame.apps.wayne.edu/llms.txt: the gateway driver and its Laravel setup. - ADVISOR, the stack's MCP server, if it is connected: list_stack_rules with the permutation that fits this app (laravel-blade, laravel-blade-vue or laravel-inertia-vue) and chapter auth, and read_project_docs with project sesame. If it is not connected, say so and work from the pages. - This app's composer.json, config/, routes/ and .env.example. Task: 1. Draft this app's entry for Drawbridge's config: id, host, upstream, mode assertion, a default, and the public, protected and api paths the app really has (routes/ tells you). 2. Set up SESAME's gateway driver the way SESAME's docs say: the issuer Drawbridge signs with, this app's host as the audience, Drawbridge's key set file (SESAME_GATEWAY_JWKS_FILE, the current and next public keys), the X-Sesame-Assertion header and the trusted proxy ranges, all as placeholders in .env.example. 3. Put the auth.sesame middleware on the routes Drawbridge protects, and make sure the api routes answer 401 instead of redirecting. 4. If a path needs step-up (an Entra authentication context such as c1), mark it in the draft and add sesame.context:c1 to that route. What c1 demands is a Conditional Access policy in Entra, not app code. Constraints: - Assertion mode, not plain headers: a Laravel app can verify the token, so it does. - Never trust X-Authenticated-* or any other identity header in the app. Only the verified assertion counts. - Keep SESAME's replay guard on. Never commit a key, a secret or a real .env. - Ask me before you guess the host, the issuer or the proxy ranges, and before you change auth middleware that is already there. Output: the config entry, the SESAME settings as placeholders, the files you changed, then your questions. ``` #### A raw PHP app behind Drawbridge The same door schedule, and SESAME's gateway driver built by hand, with the check placed before any output. A prompt for your coding agent. Copy it as it stands: ```text You are a coding agent putting a raw PHP app (no framework) at Wayne State University behind Drawbridge, the Citadel auth gateway of WELD, the Wayne State application stack. Drawbridge signs the visitor in and sends the app a short-lived signed assertion in the X-Sesame-Assertion header. Read first: - https://drawbridge.apps.wayne.edu/llms.txt, then the README's Using the assertion in an app and Configuration sections. - SESAME's pages, https://sesame.apps.wayne.edu/llms.txt: the gateway driver and the Raw PHP section. - ADVISOR, the stack's MCP server, if it is connected: list_stack_rules with permutation raw-php (raw-php-vue if the app builds Vue) and chapter auth, and read_project_docs with project sesame. If it is not connected, say so and work from the pages. - This app's composer.json, its front controller or entry scripts, and how it signs people in today. Task: 1. Draft this app's entry for Drawbridge's config: id, host, upstream, mode assertion, a default, and the public, protected and api paths the app really has. 2. Build SESAME's gateway driver as its Raw PHP section shows (Drawbridge's key set file, issuer, audience, trusted proxies, and a PSR-16 cache for the replay guard), and sign the user in from the verified assertion. 3. Assertion is Drawbridge's only mode: there is no plain-header mode, so the app must verify the token. If you think this app cannot, say why and ask me before you go on. 4. Replace the app's own sign-in only on the paths Drawbridge protects, and show me the diff before you apply it. Constraints: - A raw PHP app has no framework to lean on: show exactly where the check runs, before any output is sent. - Never trust an identity header the app did not get from a verified assertion. - Keep the replay guard on. Never commit a key, a secret or a real .env. - Give separate commands for Windows (PowerShell), macOS and Linux wherever they differ. - Ask me before you guess, and before you touch anything that deploys. Output: the config entry, where the check runs and the diff, then your questions. ``` Agents read the same pages you do. [llms.txt](https://drawbridge.apps.wayne.edu/llms.txt) lists them, [llms-full.txt](https://drawbridge.apps.wayne.edu/llms-full.txt) has them all in one file, and this page has a [Markdown twin](https://drawbridge.apps.wayne.edu/index.md). The page sends nothing anywhere; the buttons only copy text or open the tool you picked. No spec lowers the bridge for anyone who hasn't signed in. A-701 Site plan ### Where the gate stands in the stack Drawbridge is one part of the Wayne State application stack. [WELD](https://weld.apps.wayne.edu/) is the Laravel starter app with the rest of it already set up. Once it's live, Drawbridge is the one door in Citadel's wall, and the apps and the stack's other parts run inside. 1. Drawbridgesigns the visitor in, once 2. [SESAME](https://sesame.apps.wayne.edu/)its gateway driver verifies the token 3. [HELMET](https://helmet.apps.wayne.edu/)sets the security headers 4. [WayneUI](https://wayneui.apps.wayne.edu/)renders the page #### Key - **[WayneUI](https://wayneui.apps.wayne.edu/)** the interface layer - **[CREED](https://creed.apps.wayne.edu/)** the shared rules and policy - **[PROCTOR](https://proctor.apps.wayne.edu/)** checks an app against the policy - **[Preflight](https://preflight.apps.wayne.edu/)** the shared CI components - **[SESAME](https://sesame.apps.wayne.edu/)** sign-in inside the app - **[HELMET](https://helmet.apps.wayne.edu/)** security headers and CSP reports - **[Pinstripe](https://pinstripe.apps.wayne.edu/)** code style presets - **[Sourdough](https://sourdough.apps.wayne.edu/)** starts an app in any of the five shapes, raw PHP to Inertia and Vue - **[WELD](https://weld.apps.wayne.edu/)** the Laravel starter, with the stack set up - **[Booster](https://booster.apps.wayne.edu/)** upgrades PHP and Laravel one version at a time - **[Rollcall](https://rollcall.apps.wayne.edu/)** every app answers "present" - **[ADVISOR](https://advisor.apps.wayne.edu/)** an MCP server your agent can ask - **[Squire](https://squire.apps.wayne.edu/)** the deploy kit for Citadel - **[Parity](https://parity.apps.wayne.edu/)** Citadel on your computer, a scale model of the castle - **Drawbridge** the sign-in gateway for Citadel's apps *you are here* A-801 Revision schedule ### Drawn, not yet built Release 0.6.2 is out. 0.2 swapped SAML for OpenID Connect with Entra ID, 0.3.0 added the key set file apps verify assertions with (`keys:jwks`), and 0.4.0 raised the bridge on demand: `drawbridge revoke` ends a person's sessions on every app host at once, an event log records each sign-in, sign-out and denial as one JSON line, and a path can be denied outright or kept to the people in named groups. 0.5.0 posted a lookout on the wall (`composer advisories` calls out when Debian ships a fix above the module floor), and a claim with a long directory-extension name crosses under a short one (`{from, as}` in `oidc.extra_claims`). 0.6.0 hangs a calendar in the guardroom: set `DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES` and `config:validate`, `/metrics` and the container log count down to the day the Entra client secret runs out. Sessions can live in a shared Redis store (`gateway.session_store: redis`, out in 0.2.1), so several instances can serve the same hosts and a restart or a graceful reload signs nobody out, and neither does changing the castle password while the old one is kept as the previous passphrase (proven by `rig/run.sh redis-rotation`); the signer's counters reach /metrics through a shared file-backed store (out in 0.1.1). The guard, the signer and the rig work as before. The gateway image is built, but nothing sits behind the bridge yet: it will run as a service on Citadel, and the routing in front of it is still the platform team's to design. The items below come from `OPEN_QUESTIONS.md`: the newest issued revision first, then each open one with the safer default the code uses until it's built. **Planned revisions** | Rev | Item | Until then | | --- | --- | --- | | done | A first deployment you can rehearse | On main for the next release: the trial kit in `trial/` and `drawbridge smoke` (A-602). The rig runs the kit as shipped, rolls the gateway back and inspects it again. The first real run waits on a pre-production host. | | done | Two gateways changing the passphrase together | Proven by `rig/run.sh multi`: two instances on one Redis open each other's sessions before the change and while both hold the new and the old value, and both refuse the old one once it is gone. Take each step on every instance promptly: one still on the old value sends a visitor with a new session to sign in again. | | done | A passphrase rotation proven over Redis | Proven by `rig/run.sh redis-rotation`: with `gateway.session_store: redis` and the old value kept as the previous passphrase, nobody signs in again. Once it is dropped, a session sealed under it is sent to sign in, not shown an error. | | next | Where the signing keys and the key set file live on Citadel | The scheme is built (ADR-0001, `keys:jwks`, SESAME's `gateway.jwks_file`): apps read a key set file of the current and next key, so rotation needs no coordinated window. The platform team picks where the keys and the file live. | | later | The rig as an automatic pipeline job | The GitLab rig job runs by hand until the runners can run Docker; locally it is `rig\run.ps1` or `sh rig/run.sh`. | | no | Bearer tokens on API paths | Decided against: an `api` path takes the browser session, and without one it gets a plain 401. | | no | Identity on public paths | Decided against: public means no identity, ever. | --- Source: https://drawbridge.apps.wayne.edu/docs/changelog.html ## Changelog [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#changelog) All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Unreleased [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#unreleased) - Docs: the README says the accessibility checker is vendored from Preflight 0.9.0 (it said 0.5.0), the copy CI pins. Content only. - Changed: `deploy/` requires PROCTOR `^0.16` (was `^0.15`, which does not allow 0.16), whose `ci-pipelines` check no longer asks for a GitHub workflow (D-069). - Changed: the deploy kit is Squire 0.11.1 (was 0.10.7): the release script fetches PROCTOR when `--no-dev` left it out and installs the frontend from a `yarn.lock`, the HAProxy pin is current, the fallback base follows the app's PHP line, and the parity scripts carry the deprecation note. - Changed: CI pins Preflight 0.9.0 (components and the a11y checker copy). - CI: the GitHub workflow calls Preflight 0.9.0's reusable workflow (commit fb73b53), the release the GitLab pipeline pins. - Added: `drawbridge smoke` checks a running gateway from the outside without signing anyone in, the first command to run after a deploy, a restart or a rollback. It asks `/_drawbridge/up`, a host that is not configured (403), and for each app a login path (a redirect to the provider carrying the redirect URI, client id and PKCE the config and `DRAWBRIDGE_PUBLIC_SCHEME` imply, which is the URI Entra must have registered), an api path (a bare 401), a deny path (403), a public path (the app answers, so the upstream is reachable, and spoofed identity headers sent with it never arrive), a made-up callback (no session) and `/metrics` (403 to a stranger, 200 to `DRAWBRIDGE_METRICS_TOKEN`, and the version it reports). Read-only; exit 1 when a check fails, `--format=json` for a test record. Inside the container every default is right: `docker exec /opt/drawbridge/bin/drawbridge smoke`. The rig runs it both ways: in-process against the gateway (`SmokeTest`, which also shows it fails when pointed past the gateway at the app, or with the wrong public scheme) and inside the gateway container with no options, after every default rig run. - Fixed: `/metrics` reported `drawbridge_build_info{version="1.0.0.0"}` from the gateway image, Composer's guess for a tree with no git metadata, instead of the release. The CLI and the gauge now read one constant, `Version::CURRENT` in `src/Version.php`, and `VersionTest` keeps it equal to the newest release heading in this file. Found by the smoke check's first rig run. - Added: the trial kit in `trial/`, the smallest real deployment for a first run on a pre-production host. It has a compose file with the gateway and a throwaway whoami app on the same image (no capabilities, no new privileges, read-only mounts, rotated logs, the gateway on loopback only, whoami unpublished), an example config with one path of every kind, an `.env.example` with the secrets left empty, and whoami itself: one PHP file that verifies the assertion with openssl and shows what it checked. The new guide [First deployment](https://git.wayne.edu/enterprise-apps/drawbridge/-/blob/main/docs/deploying/first-deployment.md) walks it: the files and keys, the compose and `docker run` shapes, health, the smoke check, logs, metrics, a rollback (`up -d --no-deps gateway`) and the teardown. - Rig: `sh rig/run.sh trial` (`rig\run.ps1 trial`) runs the trial kit as shipped, with the mock provider added. It signs in through whoami, sends whoami a forged assertion around the gateway (refused) and runs the smoke check. Then it rolls the gateway back to another image and checks that whoami was not recreated and that both checks still pass (`TrialTest`). `TrialConfigTest` keeps the kit's config, compose hardening and `.env.example` honest. Both CI rig jobs run it too, and the Proof page has a section for it. - Added: on an https host the smoke check's login line also reads the state cookie the sign-in redirect sets, and fails when it lacks `Secure`: the gateway marks the session cookie the same way, and a `__Host-` session cookie without `Secure` is dropped by every browser. A gateway that misreads its scheme behind the front proxy now shows up before anyone signs in. A login answer of 500 names the likely cause, the provider's metadata (a wrong `oidc.issuer` or no outbound HTTPS). - Changed: the smoke check's public-path line says "the app saw none of the spoofed identity headers" (it said "the echo app", whichever app answered). - Added: the smoke check's `clock` line compares the app host's clock with the gateway's, from the `Date` headers of the app's answer on a public path and of the gateway's own `/_drawbridge/up` (Apache keeps a proxied `Date`). An assertion lives 60 seconds and SESAME allows 30 seconds of skew, so more than 10 seconds apart fails, before any assertion is refused (BEST_PRACTICES.md D42; host time sync is still the platform's to confirm). `SmokeClockTest` covers the pass, the early warning, the refusal, and the skips. - Docs: the Overview's "Pick your path" and "Related" lists link First deployment, so the docs' front door reaches it, not only the guides and references that mention it. - Site: a new front-page sheet, A-602 Field inspection, shows `drawbridge smoke` as an inspector's field report: one stamp per finding in the command's own wording for the example config's app1, a verdict stamp, and three mistakes to try (a wrong tenant, a misread scheme, a drifting clock) that swap in the failing line and exit 1. Beside it, the trial kit's eight steps and a link to First deployment. The drafting kit lists `smoke`, the rig paragraph and the revision table mention the trial kit, and the specs sheet is now A-603. ### 0.6.2 (2026-11-10) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-6-2-2026-11-10) - Fixed: the gateway image is built for linux/amd64, the architecture of Citadel's docker hosts. The `gateway-image:publish` job now carries the `amd64` runner tag; 0.6.1's image was built on an arm64 runner and does not run on Citadel. - Docs: the Where it fits tables no longer say Parity 0.1.0 is coming (it is out). - Docs: the README names the Preflight checker version the a11y gate actually vendors (0.5.0). - Changed: the deploy layer requires PROCTOR ^0.15 (locked 0.15.0, was ^0.12): 0.13 checks the release cooldown against the CREED policy, 0.14 adds `script-pair` and 0.15 adds `mysql56-ci`; all only warn, nothing breaks. - Changed: the GitHub workflow calls Preflight 0.5.0's reusable workflow (pinned to its release commit), the same release as the GitLab pipeline; it was on 0.1.4 because GitHub's copy of Preflight had no later tag. - Changed: the deploy layer requires PROCTOR ^0.12 (locked 0.12.0, was ^0.11): two new warning-only checks, nothing breaks. - Site: the front page's stale facts are current (the party list links Parity's site; it no longer says "site coming"). - Changed: the deploy kit is Squire 0.10.7 (was 0.10.6): it ships a `.gitattributes` that pins line endings, so the deploy layer clears PROCTOR's line-ending warnings. - Changed: the docs, agent-ready and deploy kits are Squire 0.10.6 (was 0.10.5): the docs builder and agent-ready generator see every file on Docker Desktop mounts. - Site: `assets/stack-env.js` knows Parity, so a pre-production page links Parity's pre-production site and a dev page links its local `site/` folder. Until now Parity, of all parts, was the one link that ignored its environment. - Rig: `sh rig/run.sh multi` (`rig\run.ps1 multi`, and a step in both CI rig jobs) rolls a crypto passphrase change across two gateway instances on one Redis: once both hold the new and the old value a session either one seals opens the app on the other, once the old value is gone both send its sessions to sign in, and mid-roll an instance still on the old value sends a session sealed under the new one to sign in; `rig/run.sh` now also runs from Git Bash on Windows (`MSYS_NO_PATHCONV=1`). - Changed: CI's rig job also runs the `redis` and `redis-rotation` modes. - Deploy kit refreshed to Squire 0.10.5. ### 0.6.1 (2026-11-09) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-6-1-2026-11-09) - Docs: the upgrading guide has a 0.6.1 section (no breaks; the gateway image's Apache and module floors do not change), and the README, docs, CLI version, gatehouse drawing and front page say 0.6.1. - Changed: CI pins the Preflight components to 0.5.0 (was 0.4.0), and the composer-audit job takes the component's own image instead of naming one; the a11y pin test expects 0.5.0 (the a11y template is the same in both). - Docs: Parity joins the party. The README cast and "Where it fits in the stack" table, the docs overview, How it works and the front page's key plan carry Parity next to Squire, with its spirit-level mark: the stack's new tool that runs Citadel on your computer (its PHP image, its proxy and MySQL 5.6). 0.1.0 is coming and it has no site yet, so its entries link nowhere. A scale model of the castle, built on the level. - Changed: refreshed version mentions. The "Where it fits in the stack" table in the README, the docs overview and How it works now seats the whole garrison in the cast's order (Squire, Booster, Rollcall, ADVISOR and WELD were left outside the walls), and the dev dependency Pinstripe moves to ^0.3 (locked 0.3.0; it bans joined SQL and turned-off TLS checks). - Changed: the `wayneui-copies`, `composer-ci` and `advisories` CI jobs, the rig's install step and the documented Docker commands run Composer 2.11.1 (was 2.10.3, no longer maintained), pinned by its multi-arch list digest; 2.11 fixes GHSA-c968-33g3-wh7p and GHSA-fm2w-xgf2-f9fh. - Changed: the front page deploy kit is Squire 0.10.2 (was 0.10.1): the kit's `php.ini` sets `session.cookie_samesite = Lax`, the fallback base names its images in full (`docker.io/library/...`) with Composer as a build argument, and the portable image drops `node_modules/` after the build. The gateway image does not change. - Changed: the front page deploy layer requires HELMET ^1.3 (was ^1.0) and CREED ^0.1.8 (was ^0.1), and its lock moves to HELMET 1.3.0, CREED 0.1.8 and PROCTOR 0.11.1; the dev dependency Pinstripe is ^0.1.4 (was ^0.1, locked 0.1.0, now 0.1.4). - Docs: MAINTAINING names the maintainer as a role, reached through an issue on git.wayne.edu, and the test and CI comments say what they hold in plain words instead of internal item numbers. - Rig: `sh rig/run.sh redis-rotation` (`rig\run.ps1 redis-rotation`) proves a crypto passphrase change over the Redis session store signs nobody out: a session from passphrase A survives a reload with B current and A previous, a new sign-in works under B, once A is dropped its session is sent to sign in (not a 500), and the B session survives a gateway restart; the docs and the front page drop "expected, not proven" and the README and Sessions guide gain the three rotation steps. ### 0.6.0 (2026-11-09) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-6-0-2026-11-09) - Changed: the deploy kit is Squire 0.10.1 (was 0.10.0): the fallback base image copies Composer 2.11.1 (was 2.10.3, no longer maintained), and the front page deploy layer requires PROCTOR ^0.11 (locked 0.11.0, was ^0.8 at 0.8.0). - Changed: the deploy kit is Squire 0.10.0 (was 0.7.1): release.sh keeps Composer and npm download caches in the app folder and the gate takes SQUIRE_PHP_RUNTIME; the compose file, health.php and .env.squire.example follow the template, and the portable image files are added. - Added: a reminder for the Entra client secret's expiry date (OPEN_QUESTIONS.md E-6). Set the optional `DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES` (`YYYY-MM-DD`) and `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` (worked out on every scrape, negative once expired), and `render` writes one `drawbridge: warning:` line to the container log at start from `soon` on. Nothing refuses a request; unset changes nothing, and a value that is not a real date is refused at start like any other bad setting. ### 0.5.0 (2026-11-09) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-5-0-2026-11-09) - Docs: the Entra registration guide says a claim that arrives under a long directory extension name can be renamed with `{from, as}` in `oidc.extra_claims` (it still said a rename option was not built). - Fixed: scripts/a11y.ps1 works on a Windows checkout with CRLF line endings; it strips the carriage returns from the shell command it hands to Docker, which sh rejected with a syntax error. - Docs: the front page and docs pages follow the reader's dark mode. The front page had none (it rendered the light sheet even on a dark system); it now gets the docs' after-hours palette, a graphite board with chalk grid, linework in a light tint of the brand green, filled tags in the green itself and gold still gold, with a desk lamp over the hero drawing that flickers on once when motion is allowed. The light page is unchanged, and the a11y gate passes both schemes at 320 and 1280 px. - Added: `oidc.extra_claims` entries can rename a claim with `{from, as}`, so a long directory-extension claim reaches the app under a short name. - Docs: the front page catches up with 0.4.0. The door schedule and its explain box carry the example config's step-up, group and deny rows and print `explain`'s real wording (notes and the deciding rule); the passage outcomes add deny and groups (both 403); the general notes become eighteen from the 55 practices (deny, groups, revoke, top-level sign-out, the event log, the advisory watch); the drafting kit lists `revoke`; the validate output says 7 path rules; the revision schedule follows OPEN_QUESTIONS.md (bearer tokens and identity on public paths are decided against). The README no longer says one person's sessions cannot be ended (that is `drawbridge revoke`), and the README art is re-taken (the gatehouse drawing read Rev 0.3; the kit keeps its door cells to the unauthenticated actions). On a 320 px phone the door schedule fits its column: paths break only at a slash and a door's note drops under its key. - Added: `composer ci` now holds the offline half of signing out with third-party cookies blocked (DRAWBRIDGE-25, D50). The browser proofs need the rig, so `tests/Unit/SignOutFlowTest.php` checks everything in the repository the chain depends on: every app host answers `?logout=` itself (uncached, unframeable, never proxied), the session cookie is `SameSite=Lax` on every host, no directive widens the return or turns on front-channel logout, the rig's provider has none either, the strip hook leaves the endpoint its cookies, the error pages embed nothing, and `tools/a11y/signout.mjs` still drives the link the guide names. - Added: the advisory watch (D37). `composer advisories` reads the apache2 and mod_auth_openidc floors and the Debian release from the gateway Dockerfile, asks OSV.dev (Debian's security tracker in the OSV format) which advisories still affect each floor, and exits 1 when Debian has a fixed build above one, naming the advisory and the fix; an advisory with no fix yet is listed to watch. It needs the network, so it stays out of `composer ci`: the new GitLab `advisories` job runs it from a pipeline schedule or by hand, never on a merge request. `FloorWatchTest` covers it with canned feed answers. - Fixed: the gateway image's mod_auth_openidc floor is 2.4.17-1+deb13u1 (was 2.4.17-1), Debian's fix for CVE-2026-54789, an out-of-bounds read and one-byte write in the state-cookie parser that the advisory watch found on its first run. A mirror or base image that serves the unpatched build now fails the image build instead of shipping it. - Changed: CI pins the Preflight components to 0.4.0 (the proctor job clones the full history, so the override-approver check can read git blame). - Changed: the deploy layer runs Squire's kit 0.7.1 (was 0.6.0): `.squire/php.ini` no longer sets the deprecated `session.sid_*` lines, web requests get a `disable_functions` list and Apache hardening (`.squire/php-web.ini`, `.squire/apache-hardening.conf`), and opcache gets production settings with `SQUIRE_OPCACHE_VALIDATE` as the one switch. - Changed: the front page deploy layer requires HELMET ^1.0 (lock at 1.0.1, was 0.4.0), like the rest of the stack; its shared front controller already runs on HELMET 1.0 in Squire, Sourdough and Pinstripe. - Changed: the local a11y scripts run Preflight's own checker (vendored from 0.3.1 and pinned by a test), so they check what CI checks: axe-core 4.14.0, 320 and 1280 px, and the reflow check. - Added: CI runs Preflight's a11y component (0.3.1) on site/, every page in light and dark at 320 and 1280 px with the WCAG 1.4.10 reflow check, blocking. - Changed: CI pins the Preflight components to 0.3.1 (fixed cache keys, and caches saved even when a job fails; D-072). - Changed: CI saves its Composer and npm caches even when a job fails, so a retry after a dropped download fetches only what is missing (D-072). - Changed: CI caches Composer and npm downloads under a fixed key, so a lock change downloads only what changed (D-072). - Added: an end-to-end test replays a used OIDC callback and proves it no longer signs anyone in (D22). - Added: a test pins the gateway image to a non-root user (`1001:0`, last `USER` line) on port 8080 (D60). - Changed: the PROCTOR job in the GitLab pipeline blocks again (it passes today), and OPEN_QUESTIONS.md marks seven answered or built items as such. - Fixed: the docs menu closes with Escape and hands focus back to its button (docs kit synced from Squire). - Fixed: the docs kit's copy button no longer covers the first line of code when it says Copied or Failed: over the code it keeps its resting width and shows a check or a cross when the word does not fit (docs kit synced from Squire). - Fixed: the front page's version chip shows the full version the docs show (Rev 0.4.0, was Rev 0.4). It carries `data-docs-version` now, so the docs builder (synced from Squire) rewrites it at every release and `composer docs:check` fails while it is stale. - Changed: the deploy layer requires PROCTOR ^0.8 (locked 0.8.0). ### 0.4.0 (2026-11-08) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-4-0-2026-11-08) #### Added [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#added) - Added: `tools/a11y/signout.mjs`, a sign-out check in a real browser engine with third-party cookies blocked (DRAWBRIDGE-25). A Chromium whose engine blocks them signs the rig's test user in through the keycloak profile, shows the gateway session cookie not crossing the site boundary in a cross-site iframe, follows the documented `?logout=` chain back to the app host, and replays the old session cookie against a protected path to show it is dead; `--skip-signout` leaves the session alive, so that run must fail. Run it from `tools/a11y` with the rig's keycloak profile left up: `npm ci`, `npx playwright install chromium`, `npm run signout`. - Added: signing out is proven to work when the browser blocks third-party cookies (DRAWBRIDGE-25). `tests/E2E/LogoutTest.php`, in the default rig, walks every sign-out hop with a browser that holds only the app host's cookies: each answer is a top-level redirect or the final page, none holds an iframe, a frame, a provider image or a navigating script, the chain ends on the app host and the old session is dead, even with no provider cookie at all. Signing out explains the three hops and why none of them depends on a third-party cookie. - Added: the event log (DRAWBRIDGE-18). Besides the access log, the gateway writes one JSON line for each `drawbridge.signin`, `drawbridge.signin_failed`, `drawbridge.signout`, `drawbridge.denied` and `drawbridge.revoked`, with `v`, `time`, `host`, `path` (never the query string), `status`, `user`, `rule`, `reason` and `client`, and nothing for an ordinary request. A Lua log hook names the event and cleans every value, so a line is always valid JSON; no cookie, token, header or claim but the subject is ever written. `DRAWBRIDGE_EVENT_LOG` picks the file (default `/dev/stdout`). New reference page, Log events. `tests/Unit/EventLogFormatTest.php` keeps the format and the page in step, and `tests/E2E/EventLogTest.php` checks every event against the real gateway. - Added: `drawbridge revoke ...` ends every gateway session a person holds now, on every app host, without waiting for it to expire (DRAWBRIDGE-13). It writes ` ` to the revocation list (`DRAWBRIDGE_REVOCATION_FILE`, default `/tmp/drawbridge/revoked.txt`) under a lock and in one rename, and drops entries older than `gateway.session_seconds`; `--list` prints it. The gateway rereads the list at most once a second and refuses a session whose ID token was issued at or before the time: a browser is sent through the `?logout=` sign-out (gateway and Entra) back to the app's front door, an `api` caller gets 401, and nothing is signed. A later sign-in works as before. Several gateway instances must share one mounted file. Signing out now documents the whole chain, and why there is no front-channel (iframe) logout. `tests/Unit/RevocationTest.php` and `tests/E2E/RevocationTest.php` cover the list, the command and the gateway. - Added: per-path protection gets two more answers (DRAWBRIDGE-33). A `deny` list of paths that never reach the app (the gateway answers 403 with its own page, signed in or not, and asks nobody to sign in), and `default: deny`, so only the paths an app lists exist at all. A `protected` or `api` rule can name up to 20 `groups`; a signed-in person who holds none of them in the ID token claim `oidc.groups_claim` (`wsu_roles` at WSU) gets 403 and nothing reaches the app. The group check reads the validated ID token itself, whole and case-sensitive, so a client header or a value with a comma in it cannot pass it. The most specific rule decides alone: a child rule replaces its parent's groups and context, and a public path under a deny prefix is open. The config is refused when a rule names groups without `oidc.groups_claim`, when a public or deny rule names groups or a context, or when a group name has a space or a comma. `explain` names the groups, the deny and the rule that decided. Each app host now also lets the gateway's own error pages through, whatever its default. Unit tests pin the precedence and the rendered config; `tests/E2E/PathRulesTest.php` proves it through the rig. #### Changed [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#changed) - Changed: the pipeline pins every Preflight CI component to 0.3.0 ([preflight@0.3.0](mailto:preflight@0.3.0)); component image inputs are plain image names, since Preflight adds the Dependency Proxy prefix itself. - Changed: best practice D36 (flag apps that read raw identity headers) is `Documented`, not `Not yet`: PROCTOR's `raw-identity-header` rule holds it (DRAWBRIDGE-34). - Changed: the GitLab pipeline pins the Preflight components to 0.2.0 (was 0.1.4). - The front page's deploy layer (`deploy/`) runs Squire's kit 0.6.0 (was 0.5.0): `scripts/release.sh` asks PROCTOR's deploy gate for a go or no-go on each release (a report, not a stop, unless `SQUIRE_PROCTOR=enforce`), and `.env.squire.example` lists the new setting. The layer's pins move to HELMET `^0.4` (locked 0.4.0) and PROCTOR `^0.7` (locked 0.7.0). - Changed: `BEST_PRACTICES.md` is rewritten in the shape the other stack repos use (DRAWBRIDGE-34). The 14 short rules became 55 numbered practices, D1 to D61, each with a statement, why, sources and exactly one tag (`Enforced`, `Checked`, `Documented` or `Not yet`), keeping the numbers of the research done before the gateway was built. It covers the new deny rules, group rules, revocation, the event log and sign-out with third-party cookies blocked, and lists the SAML-only items as retired. `BestPracticesTest` now checks one tag per practice, that every `Enforced` practice names its tests, that each named method is in the class named, and that the Best practices docs page carries the same list. - CI caches Composer downloads per lock file (`.composer-cache`, keyed on `composer.lock` and `deploy/composer.lock`), so a pipeline stops fetching every package from Packagist on every run. Images already come through the Dependency Proxy. - Docs: source comments, messages and art titles write Drawbridge as a word, not in capitals; wordmarks keep their display type. #### Fixed [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#fixed) - Fixed: the rig's keycloak realm sets the post-logout redirect list under `post.logout.redirect.uris`, the attribute key Keycloak 26.7 reads. The legacy `post.logout.redirects` key was ignored, so the end-session endpoint validated the return address against the client's redirect URIs only and refused the app host's logout address. - Fixed: the pipeline's PROCTOR jobs no longer pass `--policy`, which PROCTOR 0.7 refuses in CI; PROCTOR checks against the CREED policy it bundles. - Fixed: the rig's first-party-only browser now binds each copied cookie to its host. It used to set them with no domain, so they were sent to the provider too, the opposite of a browser that blocks third-party cookies; `KeycloakTest::testLogoutWithThirdPartyCookiesBlocked` still passes with the stricter copy. - Fixed: the front page reads Rev 0.3 and says release 0.3.0 is out (it said release 0.2 was not released yet), and its cast says Sourdough starts all five app shapes, not raw PHP only. - Fixed: the README and the upgrading guide pull the 0.3.0 gateway image in their examples, and MAINTAINING.md says the project is released but not deployed. - Fixed: the CLI reports the release it ships: `php bin/drawbridge --version` prints `Drawbridge 0.3.0` (it printed `DRAWBRIDGE 0.2.0-dev`). The front page's revision schedule moves the shared session store (out in 0.2.1) and the live signer counters on /metrics (out in 0.1.1) out of the planned revisions into its account of what is out; the three unbuilt items stay. `OPEN_QUESTIONS.md` likewise moves the shared session store and graceful passphrase rotation (0.2.1) out of "Not built yet". ### 0.3.0 (2026-11-07) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-3-0-2026-11-07) #### Added [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#added-1) - Added: The Proof page records its last run. - Added: `keys:jwks`, which writes the key set file apps verify assertions with: a JWKS of the gateway's ES256 public keys by `kid`, the current key and the next one. It refuses a private key, another curve, a `kid` given twice or unusable, and more than 8 keys. SESAME reads the file with `gateway.jwks_file` (`SESAME_GATEWAY_JWKS_FILE`). - Added: ADR-0001, signing key distribution and rotation (C-7): a key set file of the current and the next key, a yearly rotation, and at least 5 minutes before a retired key leaves the file. - Docs: "Rotating the signing key", the runbook for the first key set, a rotation and an emergency; a troubleshooting entry for a gateway that switched to a key the apps never got. #### Changed [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#changed-1) - Changed: the gateway image moves to the stack's image registry: `/enterprise-apps/images/drawbridge-gateway:` instead of this project's own registry (`.../drawbridge/gateway:`, which stays readable for the releases already there; they are also copied to the new path with the same digests). `gateway-image:publish` no longer uses `$CI_REGISTRY` or `$CI_JOB_TOKEN`: it logs in with the `NOUGAT_REGISTRY_USER` and `NOUGAT_REGISTRY_TOKEN` deploy token at the registry the `NOUGAT_REGISTRY` project variable names (protected variables, so release tags must be protected), and fails and says why when they are missing. Both image jobs use the dependency proxy only where the GitLab has one, and otherwise pull the Dockerfile's pinned base images straight from Docker Hub. Update `docker pull` lines to the new path. - Changed: The canonical repository is git.wayne.edu (ADR-0021); docs, links and package metadata no longer point at the archived nougat copy. ### 0.2.2 (2026-11-06) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-2-2-2026-11-06) #### Added [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#added-2) - Added: a committed accessibility gate (`scripts/a11y.sh`, `scripts/a11y.ps1`) runs axe-core (WCAG 2.2 AA) in a real Chromium browser inside Docker against the front page and every docs page, in light and dark mode at two viewport widths; the first run found nothing to fix. #### Changed [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#changed-2) - Changed: the gateway image's vendor build stage takes the refreshed `composer:2.11.1` manifest digest (Renovate). The runtime stage and the rendered Apache config are unchanged. #### Fixed [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#fixed-1) - Fixed: `gateway.session_store: redis` with a password-protected Redis works. `render` never read `DRAWBRIDGE_REDIS_PASSWORD` (the variable was missing from the list the commands collect), so the gateway rendered no `OIDCRedisCachePassword`, Redis answered NOAUTH, and every sign-in was a 500. New `tests/Unit/EnvTest.php` fails if any variable the render options read is not collected. - Fixed: the rig's `rig/config/drawbridge-redis.yaml` is a real config again (the base rig config with `session_store: redis` and `redis_host: redis`); the committed file held a stray placeholder line instead, so the redis run could not start the gateway. `rig/run.ps1 redis` passes both phases: the session survives a graceful reload. - Fixed: the default container rig (`rig/run.ps1`, `sh rig/run.sh`) starts again under current Docker Compose. Since the Redis session store landed, the gateway service held a hard dependency on the `redis` service, which only exists under the `redis` profile, so Compose refused the whole project ("depends on undefined service"). The dependency is now `required: false`; the redis run still waits for a healthy Redis. The drawbridge was stuck up; it comes down for signed-in people again. #### Security [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#security) - The front-page deploy layer moves to Symfony 7.4.23 (symfony/http-foundation and symfony/yaml advisories, including CVE-2026-118514). ### 0.2.1 (2026-11-05) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-2-1-2026-11-05) #### Added [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#added-3) - Added: `gateway.session_store: redis` (with `redis_host`, `redis_port` and the `DRAWBRIDGE_REDIS_PASSWORD` variable) keeps the gateway sessions in a Redis the operator runs, so they survive a restart and a graceful passphrase rotation and several gateway instances can share them; `shm` stays the default and renders byte for byte as before. The rig gains a Redis service and `tests/E2E/RedisTest.php`. - Added: `DRAWBRIDGE_OIDC_CLIENT_SECRET_FILE`, `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_FILE` and `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS_FILE` load those secrets from a file (Docker secrets, Kubernetes volumes); a plain variable still wins, and the trailing newline is stripped. #### Changed [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#changed-3) - Changed: the docs pages wear the front page's drafting look: the same masthead and sheet index (Docs marked current), each page a ruled sheet on the drafting grid with a Big Shoulders Stencil title, commands in the front page's terminal with the gold Copy button in its bar, callouts as tagged drawing notes, the title block as the footer, and a dark mode derived from the terminal skin. Motion only when the reader allows it. The look lives in `docs/_header.html` and `docs/theme/drawbridge.css`. - Changed: the docs dark mode is no longer a green wallpaper: the board goes graphite under a faint chalk grid, linework and headings take a light tint of the brand green, tags and table header rows keep the brand green itself, and the terminal stays the one deep green surface, as on the front page. The theme now restates the kit's dark colors, which had been handing the page WayneUI's dark green surface. Each sheet carries the front page's enlarged detail bubble with the app icon stamped in, and section rules ink in as they scroll into view (motion only when the reader allows it). Wide tables show a shade at the edge that scrolls, and the footer's full-bleed band no longer leaves the page scrollable sideways. - Changed: proxied answers on protected and api paths get Cache-Control: no-store when the app sends none (setifempty); public paths are untouched. - Changed: the GitHub mirror is retired (GitHub is only for projects published to Packagist or npm); clone URLs, the README cast strip and the docs mirror list now point at nougat, with git.wayne.edu as the read-only mirror. #### Tests [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#tests) - Tests: `RenderTest::testProtectedAndApiPathsAddANoStoreDefault` and `RenderTest::testPublicPathsAddNoCacheHeaderAndSetTheFlag` pin the rendered no-store default on login and api blocks and the DRAWBRIDGE_PUBLIC_PATH flag on public ones, and `GatewayTest::testProtectedAndApiAnswersCarryNoStoreByDefault` and `GatewayTest::testPublicAnswersAddNoCacheHeader` check the headers end to end on the rig. - Tests: `GatewayTest::testLoginReturnsOnlyToTheSameHost` proves a third-party-initiated login whose target_link_uri names another host (plain, protocol-relative and userinfo tricks) never answers with that host in the Location header or the body, decoded or not, and that a same-host target is not refused as hostile. - Tests: `SecretFilesShellTest` and the `RuntimeSecretsTest` cases cover the `_FILE` secrets (newline stripping, precedence, empty and unreadable files). ### 0.2.0 (2026-11-03) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-2-0-2026-11-03) - 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". #### Changed [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#changed-4) - Changed: header mode removed for 1.0. Config validation rejects mode "headers" and "both"; assertion is the only mode. The renderer code stays for a later, gated return. Reason: an unsigned identity header cannot be trusted while app containers may reach each other directly, and the stack's contract is a signed assertion, never a bare header. #### Tests [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#tests-1) - Tests: `ConfigLoaderTest::testHeadersModeIsRefused` and `testBothModeIsRefused` pin the config rejection of the removed modes, `testAssertionModeStillLoads` pins that the default still loads, and `SpoofingTest::testAssertionAppsNeverSeeAClientsIdentityHeaders` replaces the header-mode E2E check on the rig's second host. ### 0.1.2 (2026-11-03) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-1-2-2026-11-03) #### Added [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#added-4) - Added: a docs site (site/docs/) built by the shared docs builder from docs/, checked in composer ci. - 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 with `dpkg --compare-versions` right after the install, and `DockerfileFloorTest` pins the floor, its position after the install, and the README documentation. - 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). - Changed: CI pins Preflight 0.1.4 (GitLab component includes and the GitHub reusable workflow at its tag commit); the deploy layer sets minimum-stability to stable. - Docs: README "Three sessions, three clocks" table says how the Entra, gateway and app sessions relate: each lifetime, what ends it, and how to keep the app session from outliving the gateway sign-in (D30). ### 0.1.1 (2026-11-03) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-1-1-2026-11-03) #### Added [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#added-5) - Rig: an opt-in `keycloak` argument (`rig/run.sh keycloak`, `rig/run.ps1 keycloak`) 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; the Keycloak tests sign one of them in and out through the gateway. - A shared file-backed metrics store: 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`), one JSON file per metric family, written atomically while a per-family lock is held, so a reader always sees a whole file and two writers never lose an increment. When the store cannot be created or written, the signer counts in memory and the endpoint serves build info only. - The gateway image serves `/metrics` itself: it installs php-cgi, and `render` maps `^/metrics$` to `bin/metrics` with a virtual-host-level `ScriptAliasMatch` beside a `` that stands outside sign-in and signing. Apache passes no server environment to a CGI child, so a fixup hook hands the child the access rules (`DRAWBRIDGE_METRICS_TOKEN`, `DRAWBRIDGE_METRICS_ALLOW`, `DRAWBRIDGE_METRICS_DIR`) from the request, where the environment is still whole. - Rig: the gateway runs with a throwaway metrics token, and the end-to-end tests check every app host answers `/metrics` to the bearer token (200, `text/plain`, `Cache-Control: no-store`) and refuses it otherwise (403). - Rig: an opt-in `rotation` argument (`rig/run.sh rotation`, `rig/run.ps1 rotation`) walks a crypto passphrase change through the running gateway: it signs in, re-renders the Apache config with the new passphrase while keeping the old one as mod_auth_openidc's documented previous value, sends Apache a graceful reload, and replays the saved session cookie. It documents that the pinned module accepts the two values but rebuilds its shared-memory session store empty on every reload, so the saved cookie is refused and the browser is sent to sign in again; the same refusal holds once the old passphrase is dropped and after the gateway container is recreated. - Tests: the rendered session cookie flags are pinned: `OIDCCookieSameSite Lax` and `OIDCCookieHTTPOnly On` hold whether secure cookies are on or off, and `OIDCCookieSameSite None` never appears. - Tests: `GatewayTest::testTheSessionCookieIsHttpOnlyAndLaxAtCallback` signs in through the rig and reads the session cookie the gateway actually set out of the BrowserKit cookie jar: it is HttpOnly, SameSite=Lax, scoped to path `/`, and carries no Domain attribute beyond the app host. - Tests: `BestPracticesTest` verifies that every test method and class cited in `BEST_PRACTICES.md` still exists under `tests/`, so the document cannot drift from the suite. - Tests: the gateway error pages are pinned to WCAG 2.2 AA properties: text contrast of at least 4.5:1 in both the light and dark color schemes, a viewport that does not block zoom, a visible focus outline of at least 2px, and a body text size of at least 16px with headings set in rem or em. - Tests: `KeycloakTest::testLogoutWithThirdPartyCookiesBlocked` signs alice in through the Keycloak rig profile, then strips every identity-provider cookie from the browser's cookie jar (a simulation of a browser that blocks third-party cookies, not a real-browser run) and proves the gateway logout still ends the gateway session with only the app host's cookies left. - Tests: `RealSesameTest::testAReplayedTokenFails` presents one signed assertion twice to one SESAME GatewayDriver instance (through a new optional `repeat` field in `tests/Support/sesame-verify.php`) and proves the first presentation passes while the second is refused as a replay. - Tests: `SpoofingTest::testADuplicatedIdentityHeaderNeverReachesTheApp` sends the identity header twice in one raw request (two values, two spellings, and twice beside the email header) and proves no `X-Authenticated-*` value reaches the echo app, anonymous on a public path and signed in on a protected one. - Tests: `E2eProvidersTest` pins the shape of `SpoofingTest::duplicatedIdentityHeaders`, so each data set stays one list argument instead of spreading into a string per line. - Tests: `GatewayTest::testAnApiPathAnswers401ForADeadSession` signs in, keeps a copy of the session cookie, ends the session through the logout callback, then replays the dead cookie on an api path with an `Accept: application/json` header and proves the answer is a bare 401 with no Location header. - Docs/Tests: `BEST_PRACTICES.md` no longer claims that every rule has a test. Each rule now names the tests that prove it, or says plainly that it has none yet, and `BestPracticesTest::testEveryRuleNamesItsTestsOrSaysNotTested` fails when a rule names neither. - Tests: the default catch-all host's hardened headers are pinned: `Referrer-Policy: strict-origin-when-cross-origin` and `Content-Security-Policy: frame-ancestors 'none'` stand at host level beside the existing `no-store` and `nosniff`, both `setifempty` so a location that sets its own value keeps it, and the `/_drawbridge/up` location keeps its own plain `set`. - Tests: the rendered session lifetimes are pinned: `OIDCSessionMaxDuration` follows `gateway.session_seconds` (default 28800, 300 to 604800) and `OIDCSessionInactivityTimeout` follows `gateway.session_idle_seconds` (default 3600, 60 to 86400), checked with the fixture defaults and with configured values. - Tests: `SignerMapTest::testTheLogCarriesAReasonCodeAndNoSubjectOrToken` proves a refused signing request leaves exactly one reason-code line in the signer's log, with no subject, attribute or token, and `SignerMapTest::testAFailureLogsOnlyTheExceptionClass` proves a signing failure logs only the exception class, never its message. #### Changed [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#changed-5) - 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. - CI pulls its Docker Hub images through the GitLab Dependency Proxy (the group's CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX), including the base images of the gateway image build, so pipelines no longer hit Docker Hub's anonymous pull limit. - 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 [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#fixed-2) - Fixed: the CI buildah image pin points at the current digest (the old one was re-pushed upstream and no longer resolves). - 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. ### 0.1.0 (2026-11-02) [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#0-1-0-2026-11-02) 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. #### Added [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#added-6) - 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. - `README.md`, `BEST_PRACTICES.md`, `OPEN_QUESTIONS.md`, `.env.example`, MIT licence. - README section on getting WSU values from Playbook. - Added: agent-ready site (prompt blocks, Markdown twins, llms.txt), from Squire's kit. - Gateway error pages: 403, 502, 503 and 504 answer with a small self-contained page (inline CSS, system fonts, no scripts, no external assets, dark-mode aware) 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, sending a signed-in visitor without it back to step up (`api` paths answer 401). - Rig tests for step-up, forged callbacks and forged `OIDC_*` headers. - GitLab pipeline builds the gateway image with Buildah (unprivileged, pinned by tag and digest) on every merge request and the default branch, and publishes it to the project's container registry when a tag is pushed (`gateway:`, no `latest`). The image carries OCI labels (source, revision, version, licenses). - An off-by-default Prometheus `/metrics` endpoint (`bin/metrics`), on when `DRAWBRIDGE_METRICS_TOKEN` (bearer token) or `DRAWBRIDGE_METRICS_ALLOW` (client IPs/CIDRs) is set; a disabled or misconfigured endpoint answers 404 and an unauthorized request 403. Reports `drawbridge_build_info`; the assertion-signing counters (`drawbridge_signing_requests_total`, `drawbridge_assertions_signed_total`, `drawbridge_assertion_errors_total{reason}`) are kept in the signer for in-process use and are not registered on the endpoint until a shared store lets it see the signer's counters; labels carry no identity, claim, or token. - 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. The `/_drawbridge/` locations the gateway answers itself get `Cache-Control: no-store` and `Content-Security-Policy: frame-ancestors 'none'`, and the default host answers its 403 and error pages with `no-store` too. HSTS carries no `includeSubDomains` and no `preload`: the gateway serves many hosts and must not decide that for them. - Docs: ENTRA_TEST.md (first real Entra test checklist) and a "Try it without Entra" README section. #### Changed [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#changed-6) - mod_auth_openidc (Debian package, pinned like the rest of the image). Authorization code flow with PKCE, one client for every app host, the redirect URI at `/_drawbridge/oidc/callback` on each host, sessions in an encrypted shared-memory cache with a passphrase per host. - Config: the `oidc` block (`issuer`, `metadata_url`, `client_id`, `client_secret_env`, `user_claim`, `attribute_claims`, `extra_claims`, `amr_map`). The issuer must be https (http only for a `.test` host). `config:validate` and `explain` print the fields, never the secret. - The signer reads the validated ID token: `sub` from the user claim (`preferred_username` by default, configurable, for example to `accessid`), `auth_time`, `amr` (Entra values through the default map), `acrs`, the attribute claims and any `extra_claims` such as `wsuRoles`. An ID token from another issuer is not signed. The signer's input line is `v2`. - The guard strips `OIDC_CLAIM_*`, `OIDC_access_token` and the module's other token and claim names, and removes every header under an owned prefix whatever follows it. - `render` refuses to write anything when the client secret or crypto passphrase is missing or unsafe to substitute, so Apache never starts with a literal `${...}` for a secret. - Rig: [mock-oauth2-server](https://github.com/navikt/mock-oauth2-server) 6.1.3 as the test IdP. - Config: the example and rig set `oidc.user_claim: accessid`, the AccessID the Entra app registration sends (transformed from the user principal name with `ExtractMailPrefix`); `preferred_username` works for a tenant that does not send `accessid`. The example also lists `wsuRoles` in `extra_claims`, a mapped claim that needs no custom signing key. The gatehouse takes names as the AccessID, because even a drawbridge only lifts for barges it knows. - Coding standard: the PHPStan settings include Pinstripe's raw PHP cut (`waynestate/pinstripe` is a dev dependency, and `phpstan.neon` keeps only this repository's paths and PHP version range). Two findings from the preset's deprecation and @var checks are fixed: the signer builds JWTs with `Builder::new()` instead of the deprecated lcobucci/jwt constructor, and the metrics allow-list keeps its runtime entry validation in a dedicated helper. - Changed: project names written as words except acronyms. - Changed: examples, docs and tests use wsu_roles, the roles claim name Entra sends (the directory attribute stays user.wsuRoles). #### Fixed [#](https://drawbridge.apps.wayne.edu/docs/changelog.html#fixed-3) - Fixed: stale capability claims in the site and README. --- Source: https://drawbridge.apps.wayne.edu/docs/contributing.html ## Contributing [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#contributing) This page tells you what Drawbridge is, where changes go, how to build and check them, and the rules a change must keep. ### What the project is [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#what-the-project-is) Drawbridge is the Citadel auth gateway: one OpenID Connect client to Microsoft Entra ID (through Apache mod_auth_openidc) in front of apps, which signs a short assertion for SESAME's `gateway` driver. It is a container image (`docker/gateway/Dockerfile`) plus a PHP signer and CLI (`bin/drawbridge`). It is not installed with Composer by apps and is not on Packagist. Its consumer is SESAME's `gateway` driver. The assertion (header, claims, signing algorithm, lifetime) is a contract between the two; change both together. Integration tests run against a SESAME checkout when `SESAME_PATH` is set. ### Where it lives [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#where-it-lives) Development happens on git.wayne.edu, the canonical repository ([enterprise-apps/drawbridge](https://git.wayne.edu/enterprise-apps/drawbridge)). Changes, issues and merge requests go there. Tags are made there, by the maintainer, with an approver. Drawbridge is not on GitHub: git.wayne.edu is its only home. ### Build and test [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#build-and-test) | Task | Windows (PowerShell) | Linux and macOS | | --- | --- | --- | | Install | `composer install` | `composer install` | | All checks (what CI runs) | `composer ci` | `composer ci` | | Validate a config file | `php bin/drawbridge config:validate --config=config/drawbridge.yaml` | same | | Build the gateway image | `docker build -f docker/gateway/Dockerfile -t drawbridge-gateway .` | same | | End-to-end rig (mock IdP by default, gateway, echo app, tests) | `rig\run.ps1 [keycloak]` | `sh rig/run.sh [keycloak]` | `composer ci` runs `composer validate --strict`, PHPUnit (unit and integration suites), Pint, the agent-ready check, PHPStan, `composer audit` and the docs check (`composer docs:check`). The end-to-end suite (`phpunit.e2e.xml.dist`) runs inside the rig. The rig's keys and passwords are throwaway values made for the rig only. The optional `keycloak` argument swaps the mock for a pinned Keycloak started from `rig/keycloak/realm.json` and runs the Keycloak tests instead; that provider checks the client secret and PKCE and knows only the realm's two synthetic users. The docs pages wear the front page's look through two files: `docs/_header.html` (the masthead and sheet index) and `docs/theme/drawbridge.css` (the front page's tokens mapped onto the docs kit, plus the dark mode it shares with the front page's section 11 in `site/assets/drawbridge.css`; change one, change both). Change the look there, never in `site/assets/docs.css` or `site/assets/docs.js`, which are Squire's kit and are checked by hash. Rebuild with `composer docs`. ### CI [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#ci) - **GitLab:** Preflight's `php-test` (PHP 8.3, 8.4, 8.5) and `composer-audit` components, a `composer-ci` job, `gateway-image:build` (Buildah, on merge requests and `main`), `gateway-image:publish` (on tags only), a manual `rig` job, and the `advisories` job (scheduled or by hand only). - **GitHub:** `.github/workflows/ci.yml` calls Preflight's reusable workflow with `composer ci`, plus the `rig` job. - Green means `composer ci` passes on all three PHP versions on both, and the rig passes on GitHub. ### Rules a change must keep [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#rules-a-change-must-keep) BEST_PRACTICES.md lists the 55 practices the gateway holds itself to, each with one tag (`Enforced`, `Checked`, `Documented` or `Not yet`), and every `Enforced` practice names the tests that prove it. A change must keep all of them, among them: strip first, fail closed, public is a decision not a default, match the normalized path never the raw one, exact or prefix nothing clever, sign narrowly and briefly, let the module do OpenID Connect, one session per app host, overwrite forwarded headers, keep secrets out of git and out of logs, do not trust the network, run small and boring, bounded dependencies, add headers never overwrite. See [Best practices](https://drawbridge.apps.wayne.edu/docs/reference/best-practices.html) for the full rules and the tests behind each one. Warning Keys, PEM files and real config stay out of git (`.gitignore` covers them). Before a release, a secrets scan of the history must show nothing internal in the tree: no server names, people, tenant or client IDs. ### Where open work is listed [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#where-open-work-is-listed) `OPEN_QUESTIONS.md` lists what is still to be verified against a real tenant and what is not built yet, in three sections: questions (the identity provider rows E-1 to E-8, the platform rows C-1 to C-7, and questions that came up while building), missing configuration, and not built yet. Each "default built" is what the code does today, and each default is the safer choice. `ENTRA_TEST.md` is the checklist for the first real Entra test. ### Releasing [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#releasing) 1. Move the lines under the top heading of `CHANGELOG.md` (Keep a Changelog) to `## X.Y.Z (YYYY-MM-DD)`. 2. `composer ci` and the rig green locally, then both pipelines green for that commit. 3. Run a secrets scan of the history and check that nothing internal (server names, people, tenant or client IDs) is in the tree. 4. Tag `X.Y.Z` (no `v`) on git.wayne.edu. The tag runs `gateway-image:publish`, which pushes the image to the stack's image registry: the group's `images` project, repository `drawbridge-gateway`, at the registry the `NOUGAT_REGISTRY` project variable names, logging in with the `NOUGAT_REGISTRY_USER` and `NOUGAT_REGISTRY_TOKEN` deploy token (protected variables, so release tags must be protected). 5. A release needs a maintainer's approval. Running it in front of real apps also needs the Citadel platform team. ### Who maintains it [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#who-maintains-it) Wayne State University Enterprise Applications maintains Drawbridge. The internal runbook (accounts, the app registration, secret storage, platform contacts) is held by Enterprise Applications: ask them. ### Related [#](https://drawbridge.apps.wayne.edu/docs/contributing.html#related) - [Best practices](https://drawbridge.apps.wayne.edu/docs/reference/best-practices.html) - [Proof](https://drawbridge.apps.wayne.edu/docs/reference/proof.html) - [Releasing](https://drawbridge.apps.wayne.edu/docs/deploying/releasing.html) - [Getting the image](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html) --- Source: https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html ## First deployment [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#first-deployment) This page takes a released gateway image onto a pre-production host for the first time, using the trial kit in `trial/`. You start one gateway and one throwaway app, sign in, check health and logs, roll back, and tear it down. No real app is behind the gateway. The trial kit is the drill before the drawbridge goes over a real moat. ### What the trial kit is [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#what-the-trial-kit-is) `trial/` holds the smallest real deployment, ready to copy onto a host: | File | What it is | | --- | --- | | `compose.yaml` | Two services: `gateway` (the image under trial) and `whoami` (a one-file app, run on the same image). | | `drawbridge.example.yaml` | The gateway config: one app with a path of every kind, so `drawbridge smoke` checks every rule. | | `.env.example` | The image tag, the port, the platform settings and the empty secrets. | | `whoami/index.php` | The throwaway app. It answers one JSON page: who the gateway says you are, and whether that holds up. | | `.gitignore` | Keeps `.env`, `drawbridge.yaml` and `keys/` out of git. | The whoami app checks the signed assertion the way an app's SESAME `gateway` driver would (the ES256 signature against the key set file, `typ`, audience, expiry) with nothing but PHP's openssl, so the host pulls one image and nothing else. It has no published port: the only way to it is through the gateway. It is a test instrument, not an example to copy; a real app verifies with SESAME. `rig/run.sh trial` (`rig\run.ps1 trial` on Windows) runs this same compose file with the rig's mock provider in place of Entra, signs in through whoami, runs the smoke check, then rolls back and checks again. If that is green on your machine, the kit works; what is left to prove is the host. ### Before you start [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#before-you-start) - Docker with the compose plugin on the host, and a way to pull the release from the stack's image registry ([Getting the image](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html)). - A host name for the trial app, sent by the front proxy (or a load balancer) to this host's port. - An Entra app registration for the trial, with the redirect URI `https:///_drawbridge/oidc/callback` ([Register Drawbridge in Entra ID](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html)). Use a trial registration, not a real app's. - Outbound HTTPS from the host to `login.microsoftonline.com`: the gateway fetches the provider's metadata and keys. ### Step 1: Copy the kit and fill in the files [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#step-1-copy-the-kit-and-fill-in-the-files) Copy `trial/` to the host and work inside it. ```sh cp .env.example .env cp drawbridge.example.yaml drawbridge.yaml ``` In `.env`, set `DRAWBRIDGE_IMAGE` to the release (a tag, or better its digest), the client secret and the date it expires (`YYYY-MM-DD`, as Entra shows it), a crypto passphrase of at least 32 characters, and a metrics token. In `drawbridge.yaml`, set the three values marked `CHANGE`: the gateway's issuer, the tenant issuer and client id, and the app's host. Then check the config with the image itself: ```sh IMAGE= docker run --rm --entrypoint php -v "$PWD/drawbridge.yaml:/etc/drawbridge/drawbridge.yaml:ro" "$IMAGE" \ /opt/drawbridge/bin/drawbridge config:validate --config=/etc/drawbridge/drawbridge.yaml ``` ### Step 2: Make the signing key and the key set file [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#step-2-make-the-signing-key-and-the-key-set-file) The gateway signs every assertion with a private key; whoami (and any real app) verifies with the public key set file. The kit keeps the two apart: `keys/private` goes to the gateway only, `keys/public` to whoami only. ```sh mkdir -p keys/private keys/public docker run --rm --user "$(id -u):$(id -g)" --entrypoint php -v "$PWD/keys:/keys" "$IMAGE" \ /opt/drawbridge/bin/drawbridge keys:generate --private=/keys/private/signing.key --public=/keys/public/signing.pub docker run --rm --user "$(id -u):$(id -g)" --entrypoint php -v "$PWD/keys:/keys" "$IMAGE" \ /opt/drawbridge/bin/drawbridge keys:jwks --key=trial-1=/keys/public/signing.pub --out=/keys/public/jwks.json sudo chown -R 1001:0 keys/private ``` `keys:generate` writes the private key readable by its owner only, and the gateway runs as user 1001, so the last line hands the folder to that user. The kid (`trial-1`) must match `DRAWBRIDGE_SIGNING_KEY_ID` in `.env`. The key is for this trial only: never reuse it for a real deployment. ### Step 3: Start it [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#step-3-start-it) The compose shape, from the kit's folder: ```sh docker compose up -d docker compose ps ``` The gateway publishes `127.0.0.1:8080` by default (`DRAWBRIDGE_TRIAL_BIND` and `DRAWBRIDGE_TRIAL_PORT` move it), so only the front proxy on the same host, or an SSH tunnel, reaches it. Both containers drop every Linux capability, cannot gain privileges, restart unless stopped, and rotate their logs at 10 MB. The same gateway without compose, for a platform that runs plain containers. The upstream in `drawbridge.yaml` is `http://whoami:8080`, so both containers share a network: ```sh docker network create drawbridge-trial docker run -d --name whoami --network drawbridge-trial --restart unless-stopped \ --cap-drop ALL --security-opt no-new-privileges:true --no-healthcheck \ -e WHOAMI_JWKS_FILE=/keys/jwks.json -v "$PWD/whoami:/whoami:ro" -v "$PWD/keys/public:/keys:ro" \ --entrypoint php "$IMAGE" -S 0.0.0.0:8080 /whoami/index.php docker run -d --name drawbridge-gateway --network drawbridge-trial --restart unless-stopped \ --cap-drop ALL --security-opt no-new-privileges:true \ --env-file .env -e DRAWBRIDGE_CONFIG=/etc/drawbridge/drawbridge.yaml \ -e DRAWBRIDGE_SIGNING_KEY_FILE=/run/drawbridge/signing.key \ -v "$PWD/drawbridge.yaml:/etc/drawbridge/drawbridge.yaml:ro" -v "$PWD/keys/private:/run/drawbridge:ro" \ -p 127.0.0.1:8080:8080 "$IMAGE" ``` The rest of this page uses the compose commands; with plain containers, use `docker exec drawbridge-gateway` and `docker logs drawbridge-gateway` in their place. ### Step 4: Health and the smoke check [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#step-4-health-and-the-smoke-check) The image's health check asks the gateway for `/_drawbridge/up` on its default host every 15 seconds. `docker compose ps` shows `healthy` once Apache answers. To ask yourself: ```sh curl -fsS http://127.0.0.1:8080/_drawbridge/up ``` Then run the smoke check inside the gateway container. It needs no sign-in, no browser and no options: it reads the config, the public scheme and port, and the metrics token from the container. ```sh docker compose exec gateway /opt/drawbridge/bin/drawbridge smoke ``` It checks that the gateway is up and refuses an unknown host, and, for the whoami app, that a protected path sends a visitor to sign in with the right redirect URI (and, on https, a state cookie marked `Secure`), an api path answers 401, a deny path answers 403, a public path reaches whoami without a spoofed identity header getting through, the security headers are set, whoami's clock is within 10 seconds of the gateway's, a forged callback gets no session, and `/metrics` refuses a stranger and serves the token. It ends with the version the gateway reports. Exit code 0 means every check passed. [Commands](https://drawbridge.apps.wayne.edu/docs/reference/commands.html) lists the checks and exit codes. Two first-run failures, both seen while this page was tested: | What you see | Why | Fix | | --- | --- | --- | | The gateway restarts over and over, and its log says `cannot read /run/drawbridge/signing.key` | The key is readable by its owner only, and that is not user 1001. | The `chown` line in step 2. | | Smoke's `login` line fails with `answers 500 ... could not get the provider's metadata` | The gateway fetches the provider's metadata on the first sign-in, not at start, so a wrong `oidc.issuer` or no outbound HTTPS shows up here. | Read the `auth_openidc:error` lines in `docker compose logs gateway`; they name the cause (an unknown tenant, a refused connection). | ### Step 5: Sign in [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#step-5-sign-in) Open `https:///` in a browser, sign in with Entra, and read the page. A good sign-in shows `"signed_in": true`, your user name, and every entry under `checks` true. `https:///up` is the public path: it shows no assertion at all. In the browser's developer tools, look at the cookies for the trial host. With `DRAWBRIDGE_COOKIE_SECURE=true` the session cookie is `__Host-drawbridge` and carries `Secure`, `HttpOnly` and `SameSite=Lax`. A browser drops a `__Host-` cookie that lacks `Secure`, so if the gateway misread the scheme behind the front proxy you would not stay signed in at all: it fails closed. This is the one cookie check the rig cannot make, because the rig is plain http. Note what you saw (it closes an open question). ### Step 6: Logs and metrics [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#step-6-logs-and-metrics) ```sh docker compose logs gateway --since 10m docker compose logs gateway | grep '^{"v":1,' ``` The gateway writes the access log (no query strings) and the event log to standard output. Event lines start with `{"v":1,` and cover sign-ins, failed sign-ins, sign-outs, refusals and revoked sessions ([Log events](https://drawbridge.apps.wayne.edu/docs/reference/log-events.html)). They never hold a token, a cookie or a secret. Set `DRAWBRIDGE_EVENT_LOG` to a file on a mounted volume to keep them apart for a log shipper. `/metrics` answers on the app's host to the metrics token: ```sh curl -fsS -H "Host: " -H "Authorization: Bearer " http://127.0.0.1:8080/metrics ``` `drawbridge_build_info` names the running release, and `drawbridge_oidc_client_secret_days_left` counts down to the expiry date in `.env` ([Metrics](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html)). ### Step 7: Roll back [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#step-7-roll-back) Rolling back moves the gateway to the previous release and leaves whoami running. Put the previous release in `DRAWBRIDGE_IMAGE` in `.env`, then: ```sh docker compose up -d --no-deps gateway docker compose exec gateway /opt/drawbridge/bin/drawbridge smoke ``` `--no-deps` recreates the gateway only. The smoke check's last line names the release now running. Sessions live in the gateway's memory by default, so everyone signs in again after a rollback (or any restart); with the Redis session store they carry over ([Sessions and lifetimes](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html)). The signing key and the key set file do not change, so nothing downstream needs to know. To roll forward, put the new release back and run the same two lines. ### Step 8: Tear it down [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#step-8-tear-it-down) ```sh docker compose down ``` Then remove the kit's folder, which holds the trial key and the secrets. Delete the trial's client secret in Entra when the trial is over. ### What to send back [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#what-to-send-back) - The release you ran (the smoke check's last line) and its digest. - The smoke check's output, from the first start and after the rollback. - Whether the browser sign-in showed every check true, and the session cookie's name and flags. - Any event lines with a `reason`, and anything in the logs you did not expect. ### Related [#](https://drawbridge.apps.wayne.edu/docs/deploying/first-deployment.html#related) - [Getting the image](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html) - [Register Drawbridge in Entra ID](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html) - [Try it without Entra](https://drawbridge.apps.wayne.edu/docs/guides/try-without-entra.html) - [Commands](https://drawbridge.apps.wayne.edu/docs/reference/commands.html) - [Log events](https://drawbridge.apps.wayne.edu/docs/reference/log-events.html) - [Troubleshooting](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html) --- Source: https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html ## Getting the image [#](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html#getting-the-image) Pull the gateway image the pipeline publishes, and verify the one you pulled against the digest the publish job printed. ### Build and publish [#](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html#build-and-publish) The GitLab pipeline runs Preflight's `php-test` (PHP 8.3, 8.4, 8.5) and `composer-audit` components, a `composer-ci` job, `gateway-image:build` (Buildah, on merge requests and `main`), `gateway-image:publish` (on tags only) and a manual `rig` job. 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 (base images come through the dependency proxy where there is one, else straight from Docker Hub, pinned by the Dockerfile either way). The image is at `/enterprise-apps/images/drawbridge-gateway:` (for example `/enterprise-apps/images/drawbridge-gateway:0.6.2`). `` is the stack's container registry; Enterprise Applications has its address. There is no `latest` tag: pin a release. The image is built for linux/amd64, the architecture of Citadel's docker hosts. Check before you deploy: `docker manifest inspect :` should list `amd64`. The 0.6.1 image was built for arm64 by mistake; use 0.6.2 or later. ### Pull the image [#](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html#pull-the-image) ```sh docker pull /enterprise-apps/images/drawbridge-gateway:0.6.2 ``` ### Verify the digest [#](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html#verify-the-digest) The publish job prints the digest it pushed. Verify the image you pulled against it: ```sh docker inspect --format='{{index .RepoDigests 0}}' /enterprise-apps/images/drawbridge-gateway:0.6.2 ``` ### OCI labels [#](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html#oci-labels) The image carries OCI labels (`org.opencontainers.image.source`, `.revision`, `.version`, `.licenses`) set from the pipeline's commit; a local `docker build` leaves them empty. ### The module floor [#](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html#the-module-floor) The image also refuses to build if Debian serves apache2 or mod_auth_openidc below the versions the rig tested: the Dockerfile checks the installed versions with `dpkg --compare-versions` right after the install (apt-get has no `>=` syntax) and stops the build with a clear message when one is lower. The floor is apache2 2.4.69-1~deb13u1 (checked 2026-11-03) and mod_auth_openidc 2.4.17-1+deb13u1 (raised 2026-11-08 for CVE-2026-54789, a bug in the state-cookie parser), both against debian:trixie-slim. `DockerfileFloorTest` pins the floor, its position after the install, and the README documentation. Note To raise the floor, bump the two versions in the Dockerfile's install step and in `tests/Unit/DockerfileFloorTest.php`, which pins them. ### When to raise it [#](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html#when-to-raise-it) `composer advisories` is the advisory watch. It reads the floors and the Debian release from the Dockerfile, asks [OSV.dev](https://osv.dev/) (which republishes Debian's security tracker) which advisories still affect each floor version, and exits 1 when Debian has a fixed build above a floor, naming the advisory and the fix. An advisory Debian has not fixed yet is listed to watch and does not fail, and one Debian rates unimportant is only counted. Exit 2 means the Dockerfile or the feed could not be read, never a pass. It needs the network, so it is not part of `composer ci`. The GitLab `advisories` job runs it from a pipeline schedule (weekly is plenty) or by hand from the pipeline page, and never on a merge request. ### The deploy layer [#](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html#the-deploy-layer) `site/` is the front page, a static sheet set for the gatehouse. On Citadel it is served by the raw-PHP deploy layer in `deploy/`: a Squire kit whose front controller serves `site/` behind HELMET's security headers. For local development, keep serving `site/` directly. ### Related [#](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html#related) - [Releasing](https://drawbridge.apps.wayne.edu/docs/deploying/releasing.html) - [Proof](https://drawbridge.apps.wayne.edu/docs/reference/proof.html) - [Try it without Entra](https://drawbridge.apps.wayne.edu/docs/guides/try-without-entra.html) --- Source: https://drawbridge.apps.wayne.edu/docs/deploying/releasing.html ## Releasing [#](https://drawbridge.apps.wayne.edu/docs/deploying/releasing.html#releasing) Release Drawbridge in five steps, from the changelog to the tag that publishes the gateway image. ### The steps [#](https://drawbridge.apps.wayne.edu/docs/deploying/releasing.html#the-steps) 1. Move the lines under the top heading of `CHANGELOG.md` (Keep a Changelog) to `## X.Y.Z (YYYY-MM-DD)`, and set `Version::CURRENT` in `src/Version.php` to `X.Y.Z`: the CLI prints it and `/metrics` reports it, and `VersionTest` fails until the two agree. 2. `composer ci` and the rig green locally, then both pipelines green for that commit. 3. Run a secrets scan of the history and check that nothing internal (server names, people, tenant or client IDs) is in the tree. 4. Tag `X.Y.Z` (no `v`) on git.wayne.edu. The tag runs `gateway-image:publish`, which pushes the image to the stack's image registry: the group's `images` project, repository `drawbridge-gateway`, at the registry the `NOUGAT_REGISTRY` project variable names, logging in with the `NOUGAT_REGISTRY_USER` and `NOUGAT_REGISTRY_TOKEN` deploy token (protected variables, so release tags must be protected). 5. A release needs a maintainer's approval. Running it in front of real apps also needs the Citadel platform team. Warning A release needs a maintainer's approval. Running it in front of real apps also needs the Citadel platform team. ### The front page [#](https://drawbridge.apps.wayne.edu/docs/deploying/releasing.html#the-front-page) The front page is not part of this release. `site/` is the static front page, served on Citadel through a small raw-PHP `deploy/` layer generated with Squire. The gateway itself is a separate deploy. ### Who maintains it [#](https://drawbridge.apps.wayne.edu/docs/deploying/releasing.html#who-maintains-it) Wayne State University Enterprise Applications maintains Drawbridge. For the internal runbook (accounts, the app registration, secret storage, platform contacts), ask Enterprise Applications. ### What has shipped [#](https://drawbridge.apps.wayne.edu/docs/deploying/releasing.html#what-has-shipped) What has shipped, with dates, is in the [Changelog](https://drawbridge.apps.wayne.edu/docs/changelog.html); this page states no release date or number beyond it. ### Related [#](https://drawbridge.apps.wayne.edu/docs/deploying/releasing.html#related) - [Getting the image](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html) - [Changelog](https://drawbridge.apps.wayne.edu/docs/changelog.html) - [Proof](https://drawbridge.apps.wayne.edu/docs/reference/proof.html) --- Source: https://drawbridge.apps.wayne.edu/docs/guides/error-pages-and-headers.html ## Error pages and response headers [#](https://drawbridge.apps.wayne.edu/docs/guides/error-pages-and-headers.html#error-pages-and-response-headers) This page covers the two answers the gateway gives on its own: the small error pages it serves, and the response headers it adds to proxied answers without overriding the app's own. ### Error pages [#](https://drawbridge.apps.wayne.edu/docs/guides/error-pages-and-headers.html#error-pages) The errors the gateway answers itself get a small page of their own instead of Apache's default English wall: 403 (an unknown host or a refused path), 502 and 504 (the app is down or taking too long) and 503 (the signer cannot sign). Each page is one self-contained HTML file under `docker/gateway/errors/`: inline CSS, system fonts, no scripts, no external assets, dark-mode aware, and no hostname or product name in the text. They are served from `/_drawbridge/errors/`, which the app hosts keep out of the proxy. Two answers stay deliberately plain: an `api` path keeps its bare 401, because a script must never be handed an HTML login page, and the `/metrics` endpoint keeps its empty-body 403 (and 404), because a scrape must not look like a page. The endpoint is not routed by the gateway config, so these pages cannot reach it; if you wire it up as the [Metrics](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html) section describes, keep the empty body inside that location. `tests/Unit/ErrorPagesTest.php` also pins their accessibility: WCAG 2.2 AA text contrast in both color schemes, a viewport that does not block zoom, a visible focus outline of at least 2px, and a body text size of at least 16px with headings set in rem or em. ### Response headers [#](https://drawbridge.apps.wayne.edu/docs/guides/error-pages-and-headers.html#response-headers) Apps send their own security headers through HELMET, so the gateway never overrides one. On every proxied answer it adds `X-Content-Type-Options: nosniff` and `Referrer-Policy: strict-origin-when-cross-origin` with `setifempty`, and an app that sends either keeps its own. When the public scheme is https it also adds `Strict-Transport-Security: max-age=31536000` the same way, with no `includeSubDomains` and no `preload`: the gateway serves many hosts and must not decide subdomain or preload policy for them. Protected and api paths also get `Cache-Control: no-store` with `setifempty`, so a signed-in page an app leaves uncached cannot be served by a shared cache after the session ends. Public paths are untouched: the gateway adds no `Cache-Control` there, and an app that wants its protected assets cached sends its own `Cache-Control`, which the gateway never overrides. The pages the gateway answers itself are not behind HELMET and carry their own headers, set plainly because no app header is expected there. The `/_drawbridge/` locations it owns (the OpenID Connect endpoint on each app host, the `/up` check on the default host) get `Cache-Control: no-store` and `Content-Security-Policy: frame-ancestors 'none'`. The default catch-all host adds `X-Content-Type-Options: nosniff` and `Cache-Control: no-store` to everything it answers, including the unknown-host 403 and the error pages. | Header | Value | Set on | How | | --- | --- | --- | --- | | `X-Content-Type-Options` | `nosniff` | every proxied answer | `setifempty` | | `Referrer-Policy` | `strict-origin-when-cross-origin` | every proxied answer | `setifempty` | | `Strict-Transport-Security` | `max-age=31536000` | every proxied answer when the public scheme is https | `setifempty` | | `Cache-Control` | `no-store` | answers on paths with `login` or `api` protection | `setifempty` | | `Cache-Control` | `no-store` | the `/_drawbridge/` locations the gateway owns | `set` | | `Content-Security-Policy` | `frame-ancestors 'none'` | the `/_drawbridge/` locations the gateway owns | `set` | | `X-Content-Type-Options` | `nosniff` | everything the default catch-all host answers, including the unknown-host 403 and the error pages | `set` | | `Cache-Control` | `no-store` | everything the default catch-all host answers, including the unknown-host 403 and the error pages | `set` | Note Add headers, never overwrite: the gateway's own response headers ride on proxied answers with `setifempty`, so an app that sends its own (through HELMET) keeps it; only the pages the gateway answers itself carry plain `set`. ### Related [#](https://drawbridge.apps.wayne.edu/docs/guides/error-pages-and-headers.html#related) - [How it works](https://drawbridge.apps.wayne.edu/docs/guides/how-it-works.html) - [Metrics](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html) - [Best practices](https://drawbridge.apps.wayne.edu/docs/reference/best-practices.html) - [Troubleshooting](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html) --- Source: https://drawbridge.apps.wayne.edu/docs/guides/how-it-works.html ## How it works [#](https://drawbridge.apps.wayne.edu/docs/guides/how-it-works.html#how-it-works) This page walks a request through the gatehouse in the order the gateway handles it, and shows where Drawbridge sits in the Wayne State application stack. ### Where it fits in the stack [#](https://drawbridge.apps.wayne.edu/docs/guides/how-it-works.html#where-it-fits-in-the-stack) Drawbridge is one part of the Wayne State application stack: one contract, several paths that agree, accessibility as a gate, and decisions written down. WELD is the Laravel starter app with the rest of it already set up. | Part | Job | | --- | --- | | WayneUI | the interface layer (project 0 of the stack) | | CREED | the shared rules and policy format | | PROCTOR | checks an app against the version policy | | SESAME | sign-in inside the app; its `gateway` driver verifies what Drawbridge signs | | HELMET | security headers and CSP reporting | | Sourdough | the starter that keeps the stack fed | | Squire | the Citadel deploy kit; the layer that serves this repo's front page is one | | Parity | Citadel on your computer: its PHP image, its proxy and MySQL 5.6, so an app that works here works on Citadel | | Preflight | the shared CI components | | Pinstripe | the coding standard presets (Pint, PHPStan, ESLint, Rector) | | Booster | upgrades an app's PHP, Laravel and front end, one hop at a time | | Rollcall | the fleet census: which apps run what, and how close each is to end of life | | **Drawbridge** | **the one OpenID Connect front door for the Citadel** | | ADVISOR | the read-only MCP server that answers a coding agent's stack questions | | WELD | the Laravel starter app with the rest of the stack already set up | ### The request path [#](https://drawbridge.apps.wayne.edu/docs/guides/how-it-works.html#the-request-path) ``` browser --> Apache httpd (Drawbridge) --> app container | mod_auth_openidc : OpenID Connect client (Entra ID), one session cookie per app host | mod_lua : strips identity headers on every request, before anything else | mod_rewrite : asks the PHP signer for an assertion (prg: map) | mod_proxy : forwards to the app `- PHP component : validates the config, renders the Apache config, signs assertions (ES256) ``` ![An architect's section through the gatehouse. 1, the guard: removes X-Authenticated-, X-Drawbridge-, X-Sesame-\* and OIDC-Claim-\* headers, and trims Connection to close, keep-alive and upgrade. 2, the OpenID Connect client: response type code, PKCE S256, callback /\_drawbridge/oidc/callback, claims kept in the environment. 3, the signer: a drawbridge+jwt signed with ES256, good for 60 seconds, sent as X-Sesame-Assertion; if it cannot sign, the answer is 503. A door schedule: /up and /assets/ public, /admin/ and anything else login, /api/ api.](https://drawbridge.apps.wayne.edu/docs/readme/gatehouse.svg) *Detail 1, enlarged: the three rooms of the passage, labeled from the source. The drawing inks itself in, and holds still if you have asked your system for less motion.* - A request for a **protected** path without a session goes to Entra to sign in (authorization code flow with PKCE) and comes back. For an **api** path it gets a plain 401, so a script never receives an HTML login page. A **public** path passes through with no identity attached. - mod_auth_openidc checks the ID token (signature, issuer, audience, nonce, expiry) and keeps the session. The claims reach the gateway in the request environment only, never as headers, and no Entra token is passed to an app. - The assertion is a compact JWT with `typ: drawbridge+jwt` and a `kid`. Claims: `iss` (Drawbridge, never Entra), `aud` (the app's host), `sub` (the configured user claim, `accessid` in the example config and `preferred_username` if unset), `iat`, `nbf`, `exp` (60 seconds by default), `jti`; `auth_time`, `amr` and `acrs` when the ID token carries them; `email`, `name` and `affiliations` when configured; and any `extra_claims` (for example `wsu_roles`). A new one is signed for every request, and only from an ID token whose `iss` is the configured provider. - 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). Warning Strip first: the guard removes every inbound `X-Authenticated-*`, `X-Sesame-*`, `X-Drawbridge-*`, `OIDC_CLAIM_*`, `OIDC_access_token` (and the module's other token names), `Remote-User`, `X-Forwarded-*`, `Forwarded` and similar header, in any hyphen or underscore spelling, on every request, before authentication runs. Every header under an owned prefix goes, whatever follows the prefix. It also trims `Connection` to `close`, `keep-alive` and `upgrade`, so a client cannot ask the proxy to drop a header the gateway set. ### Related [#](https://drawbridge.apps.wayne.edu/docs/guides/how-it-works.html#related) - [Protecting paths](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html) - [Step-up sign-in](https://drawbridge.apps.wayne.edu/docs/guides/step-up.html) - [Overview](https://drawbridge.apps.wayne.edu/docs/index.html) - [Install](https://drawbridge.apps.wayne.edu/docs/install.html) --- Source: https://drawbridge.apps.wayne.edu/docs/guides/metrics.html ## Metrics [#](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html#metrics) This page explains how to turn on and protect the Prometheus `/metrics` endpoint, and the counters it serves about signing requests and assertions. ### Turn it on [#](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html#turn-it-on) Drawbridge can expose a Prometheus `/metrics` endpoint, off by default. It is on when `DRAWBRIDGE_METRICS_TOKEN` (a bearer token) or `DRAWBRIDGE_METRICS_ALLOW` (a comma list of client IPs/CIDRs) is set, and a request is served when it presents the token or comes from an allowed address. A disabled or misconfigured endpoint answers 404 and an unauthorized request answers 403, so the route is never advertised and never served to a stranger. The client address is `REMOTE_ADDR` (the real client), never a client-supplied header, so a spoofed `X-Forwarded-For` cannot grant access, and the token is compared in constant time. ### Serve it [#](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html#serve-it) When you wire it up yourself, point a web server at `bin/metrics` for the path. In Apache, a location such as: ```apache SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 ScriptAlias /metrics /opt/drawbridge/bin/metrics ``` serves it (the `SetEnvIf` passes the bearer token through; without it only the allow list works). In the gateway image the endpoint is a php-cgi child: `render` maps `^/metrics$` to `bin/metrics` with a virtual-host-level `ScriptAliasMatch` beside the Location block that stands outside sign-in and signing, and a fixup hook hands the child the access rules (`DRAWBRIDGE_METRICS_TOKEN`, `DRAWBRIDGE_METRICS_ALLOW`, `DRAWBRIDGE_METRICS_DIR`) and the client secret's expiry date (`DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES`) from the request, where the environment is still whole, because Apache passes no server environment to a CGI child. The end-to-end tests run the gateway with a throwaway metrics token and check every app host answers `/metrics` to the bearer token (200, `text/plain`, `Cache-Control: no-store`) and refuses it otherwise (403). ### What it serves [#](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html#what-it-serves) The endpoint serves only what it can see truthfully: | Metric | Type | Meaning | | --- | --- | --- | | `drawbridge_build_info{version}` | gauge | the gateway is up, and which release (`Version::CURRENT` in `src/Version.php`, the same value `drawbridge --version` prints) | | `drawbridge_signing_requests_total` | counter | signing requests the assertion signer received | | `drawbridge_assertions_signed_total` | counter | assertions the signer signed successfully | | `drawbridge_assertion_errors_total{reason}` | counter | signing requests the signer refused or failed, by reason | | `drawbridge_oidc_client_secret_days_left` | gauge | whole days until the Entra client secret expires, negative once it has; only when `DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES` is set ([the expiry date](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html#client-secret-expiry)) | The days-left gauge is worked out from the date on every scrape and never kept in the shared store, so it disappears with the setting instead of counting down a secret that was already replaced. Alert when it drops to 30 and again at 7. ### The shared file-backed store [#](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html#the-shared-file-backed-store) The signing counters cross from the long-running signer to the per-request endpoint through a shared file-backed store: one JSON file per metric family in a directory (default `/tmp/drawbridge-metrics`, moved by `DRAWBRIDGE_METRICS_DIR`), written atomically while a per-family lock is held, so a reader always sees a whole file and two writers never lose an increment. Every process in the gateway container runs as the same UID, so plain file permissions are enough. Without a shared store the endpoint registers no counters at all, because a counter that is always zero is not shown. When the store cannot be created or written, the signer counts in memory and the endpoint serves build info only. ### What it does not serve [#](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html#what-it-does-not-serve) Apache, not PHP, serves the requests, so request counts by path class are not exposed here either, and public requests and sign-in failures never reach the PHP side; mod_auth_openidc would need its own status or log scraping to expose those. Labels carry no identity, claim, or token, and the `reason` label is folded to a fixed set (refused, failed, other), so it stays low-cardinality. ### Related [#](https://drawbridge.apps.wayne.edu/docs/guides/metrics.html#related) - [Using the assertion in an app](https://drawbridge.apps.wayne.edu/docs/guides/using-the-assertion.html) - [Commands](https://drawbridge.apps.wayne.edu/docs/reference/commands.html) - [Changelog](https://drawbridge.apps.wayne.edu/docs/changelog.html) --- Source: https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html ## Protecting paths [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#protecting-paths) This page shows how each app declares its public, protected, api and deny paths in the config file, how a rule can name groups, and how the gateway picks the one rule that applies to a request. ### The per-app config [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#the-per-app-config) One YAML (or PHP array) file declares the gateway, the OpenID Connect provider and each app. `config/drawbridge.example.yaml` is annotated. The per-app entry from that file, verbatim: ```yaml apps: - id: app1 host: app1.apps.wayne.edu # Where the app's container listens, as seen from the gateway. No path. upstream: http://app1:8080 # Only "assertion" (a signed JWT) is accepted in 1.0. mode: assertion # What a path with no rule gets. "login" (default) is the safe choice. "deny" refuses every path no rule # names, so only the paths listed below exist at all. "public" opens them. default: login # A path ending in "/" is a prefix ("/assets/" covers /assets and everything under it). Any other path is exact. # No wildcards or regular expressions. Query strings are never part of the match. public: - /up - /assets/ protected: - /admin/ # A rule can also need an Entra authentication context (c1 to c99): the gateway asks Entra for it, and lets # the request through only when the ID token's "acrs" lists it. Conditional Access decides what c1 means. - path: /admin/payroll/ auth_context: c1 # A rule can also name groups: the person must hold at least one of them in the groups claim (above), or # the gateway answers 403. A coarse gate in front of the app; the app still decides what each person may do. - path: /admin/reports/ groups: [app1-reports, app1-admins] # Like protected, but an unauthenticated caller gets a 401 instead of a redirect to sign in. api: - /api/ # Never reaches the app, signed in or not: the gateway answers 403. For tools that must not be on the internet. # The most specific rule wins, so a deny prefix can still hold a public or protected path under it. deny: - /telescope/ ``` What each key does: - `id`: the app's name in the config (`app1` in the example). - `host`: the host name of the app the entry fronts; the gateway keeps one session cookie per app host. - `upstream`: where the app's container listens, as seen from the gateway. No path. - `mode`: how the gateway passes the identity on. Only `assertion` (a signed JWT that SESAME's `gateway` driver verifies) is accepted in 1.0; the header modes (`headers`, `both`) were removed. - `default`: what a path with no rule gets: `login` (the default), `deny` or `public`. - `public`: the paths that pass through with no identity attached. - `protected`: the paths that need a sign-in. A rule here can also need an Entra authentication context on top (see [Step-up sign-in](https://drawbridge.apps.wayne.edu/docs/guides/step-up.html)), or groups (below). - `api`: like `protected`, but an unauthenticated caller gets a 401 instead of a redirect to sign in. - `deny`: the paths that never reach the app. The gateway answers 403 with its own page, signed in or not, and asks nobody to sign in first. A path may appear in only one list. A `public` or `deny` rule cannot name an authentication context or groups: there is nobody signed in to check. ### Path rules and precedence [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#path-rules-and-precedence) Path rules are exact (`/up`) or prefix (a trailing slash, `/assets/`). There are no wildcards and no regular expressions. Query strings are never part of the match. One rule decides each request, and it is the most specific one that matches: 1. The longest matching path wins, whichever list it is in. `/admin/open` (public) beats `/admin/` (protected), and `/telescope/` (deny) beats a `login` default. 2. At the same length, an exact rule beats a prefix: `/up` beats `/up/`. 3. No rule matches: the app's `default` decides. The winning rule is the whole answer. A more specific rule does not inherit anything from a shorter one: if `/admin/` names groups and `/admin/reports/` names other groups, `/admin/reports/q3` needs the second set only, and a `public` path under a `deny` prefix is open. The gateway renders the rules least specific first, so Apache's own section merging gives the same answer (the unit tests check both). ### Groups [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#groups) A `protected` or `api` rule can name up to 20 groups. The signed-in person must hold at least one of them, or the gateway answers 403 with its own page and sends nothing to the app: ```yaml oidc: groups_claim: wsu_roles apps: - id: app1 protected: - path: /admin/reports/ groups: [app1-reports, app1-admins] ``` - `oidc.groups_claim` names the ID token claim that lists the person's groups. A config with a group rule and no `groups_claim` is refused, so a rule can never be quietly skipped. For WSU's tenant the claim is `wsu_roles`; another tenant might send Entra's own `groups` or `roles` claim. - A group name is 1 to 64 letters, digits and `.`, `_`, `@` or `-`. The match is exact and case-sensitive. - The check happens inside the gateway, after sign-in, on every request. A person who loses a group loses the path when their ID token is next refreshed, which is at the next sign-in. - Groups are a coarse gate in front of the app, for a tool only a few people should even reach. They do not replace the app's own authorization: the app still decides what each person may do, with the same claim from the assertion. ### Deny by default [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#deny-by-default) `default: deny` refuses every path that no rule names. Use it for an app where only a few paths should exist on the internet at all: ```yaml apps: - id: tool host: tool.apps.wayne.edu upstream: http://tool:8080 default: deny public: [/up] protected: [/app/] deny: [/app/debug/] ``` Here `/up` is open, everything under `/app/` needs a sign-in, `/app/debug/` and everything under it is refused, and every other path (`/`, `/.env`, `/vendor/`) is refused without asking anyone to sign in. Note Public is a decision, not a default. A path with no rule gets `login` unless the app says `deny` or `public`. Public paths carry no identity at all. The gateway's own error pages stay readable whatever the default is. ### Normalization [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#normalization) A path with an encoded slash, a backslash, a semicolon, a control character or bad UTF-8 is refused: the guard answers 400 before any rule is read. The gateway matches the normalized path, never the raw one, so `/app/x/../debug/` is matched as `/app/debug/`. `/_drawbridge` belongs to the gateway. ### Check a path with explain [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#check-a-path-with-explain) The `explain ` command says which rule applies to a request, what it needs, and which rule decided: ```sh php bin/drawbridge explain app1.apps.wayne.edu /admin/reports/monthly --config=config/drawbridge.yaml ``` ```text app1 /admin/reports/monthly => login, needs one of the groups app1-reports, app1-admins in the ID token's wsu_roles claim (403 without) (matched as /admin/reports/monthly, by the rule for /admin/reports/) ``` ### Related [#](https://drawbridge.apps.wayne.edu/docs/guides/protecting-paths.html#related) - [How it works](https://drawbridge.apps.wayne.edu/docs/guides/how-it-works.html) - [Step-up sign-in](https://drawbridge.apps.wayne.edu/docs/guides/step-up.html) - [Log events](https://drawbridge.apps.wayne.edu/docs/reference/log-events.html) - [Commands](https://drawbridge.apps.wayne.edu/docs/reference/commands.html) --- Source: https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html ## Quick start [#](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html#quick-start) This quick start copies the example config and environment file, validates them, builds the gateway image, and runs the rig against a mock provider. You need Docker and nothing else; the steps run PHP and Composer inside the `composer:2.11.1` container. ### Step 1: Clone the repository and install dependencies [#](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html#step-1-clone-the-repository-and-install-dependencies) PowerShell ```powershell git clone https://git.wayne.edu/enterprise-apps/drawbridge.git; cd drawbridge docker run --rm -v "${PWD}:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer install --no-interaction ``` sh ```sh git clone https://git.wayne.edu/enterprise-apps/drawbridge.git && cd drawbridge docker run --rm -v "$PWD:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 composer install --no-interaction ``` ### Step 2: Copy the example config and environment file [#](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html#step-2-copy-the-example-config-and-environment-file) PowerShell ```powershell Copy-Item .env.example .env Copy-Item config\drawbridge.example.yaml config\drawbridge.yaml ``` sh ```sh cp .env.example .env cp config/drawbridge.example.yaml config/drawbridge.yaml ``` You now have `.env` and `config/drawbridge.yaml`, both copied from the examples. The gateway image also needs the `signing.key` file and the two secrets in its environment to start; the rig supplies throwaway values for all of them. ### Step 3: Validate the config [#](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html#step-3-validate-the-config) ```sh docker run --rm -v "$PWD:/app" -w /app composer:2.11.1@sha256:8de2184c6de224f4689e8f80ed5f5edaf0030b6b8b7839a22a2bcb6722ac87d0 php bin/drawbridge config:validate --config=config/drawbridge.yaml ``` The same command runs on Windows (PowerShell), with `${PWD}` in place of `$PWD`. See [Commands](https://drawbridge.apps.wayne.edu/docs/reference/commands.html) for what `config:validate` reports. ### Step 4: Build the gateway image [#](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html#step-4-build-the-gateway-image) ```sh docker build -f docker/gateway/Dockerfile -t drawbridge-gateway . ``` Expected result: the image is built and tagged `drawbridge-gateway`. ### Step 5: Run the rig against the mock provider [#](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html#step-5-run-the-rig-against-the-mock-provider) The container rig is the local trial: the real gateway image, a mock OpenID Connect provider standing in for Entra, and a tiny echo app. It signs in synthetic users through the mock and checks protected and public paths, spoofed headers, forged callbacks, logout and step-up to an authentication context. Nothing in the rig reaches Entra. PowerShell ```powershell rig\run.ps1 # Windows ``` sh ```sh sh rig/run.sh # Linux, macOS ``` Expected result: the rig is green. When the rig is green, the next step is the first real sign-in, which ENTRA_TEST.md walks through. Tip For the local trial in depth, including the `keycloak`, `rotation`, `redis`, `redis-rotation`, `multi` and `trial` arguments, see [Try it without Entra](https://drawbridge.apps.wayne.edu/docs/guides/try-without-entra.html). ### What you built [#](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html#what-you-built) You have the gateway image `drawbridge-gateway` built from `docker/gateway/Dockerfile`, a validated `config/drawbridge.yaml` copied from the example, and a green rig run: the real gateway image in front of a mock OpenID Connect provider and a tiny echo app, with protected and public paths, spoofed headers, forged callbacks, logout and step-up all checked. ### Next steps [#](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html#next-steps) - [Try it without Entra](https://drawbridge.apps.wayne.edu/docs/guides/try-without-entra.html): the rig, its arguments and what it proves. - [Register Drawbridge in Entra ID](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html): the app registration before the first real sign-in. - [Getting the image](https://drawbridge.apps.wayne.edu/docs/deploying/getting-the-image.html): pull the published image instead of building it. - [Install](https://drawbridge.apps.wayne.edu/docs/install.html): requirements and the full install for each OS. ### Related [#](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html#related) - [Overview](https://drawbridge.apps.wayne.edu/docs/index.html) - [Install](https://drawbridge.apps.wayne.edu/docs/install.html) - [Try it without Entra](https://drawbridge.apps.wayne.edu/docs/guides/try-without-entra.html) - [How it works](https://drawbridge.apps.wayne.edu/docs/guides/how-it-works.html) - [Changelog](https://drawbridge.apps.wayne.edu/docs/changelog.html) --- Source: https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html ## Register Drawbridge in Entra ID [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#register-drawbridge-in-entra-id) Register one app registration in Entra ID that covers every app host, so the gateway has one OpenID Connect client for all of them. ### Before you start [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#before-you-start) You need: - A **test app registration** in a tenant that is safe for a first test (single tenant, platform Web). Not the production registration. - A **test host** where the gateway image can run with TLS terminated in front of it: the issuer must be https, and the session cookie is Secure. - **Two throwaway users** in that tenant: one for the run sheet, and one to confirm that sessions are separate per user and that signing one out touches nothing of the other. - The deployment's secret store, ready to hold `DRAWBRIDGE_OIDC_CLIENT_SECRET` and `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE`, and a fresh assertion signing key made with `keys:generate`. ### In the Entra admin center [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#in-the-entra-admin-center) One app registration covers every app host. In the Entra admin center, under App registrations: 1. **New registration.** Single tenant. Platform **Web**. 2. **Redirect URIs.** One per app host: `https:///_drawbridge/oidc/callback` (for example `https://app1.apps.wayne.edu/_drawbridge/oidc/callback`). Each host gets its own session, so each needs its own redirect URI; add one whenever an app is added to the config. Leave the implicit grant boxes unticked: the gateway uses the authorization code flow with PKCE. 3. **Certificates & secrets.** Make a client secret and put it in the deployment's secret store as `DRAWBRIDGE_OIDC_CLIENT_SECRET`. Put its expiry date in `DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES` (`YYYY-MM-DD`): Entra secrets expire, the gateway cannot sign anyone in once it has, and with the date set `config:validate`, `/metrics` and the container log count down to it ([the expiry date](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html#client-secret-expiry)). 4. **Token configuration.** Add the optional ID token claims the config reads: `accessid` (the AccessID, transformed from the user principal name with `ExtractMailPrefix`; this is what the example config uses for `oidc.user_claim`), `email`, `auth_time`, and `acrs` if any path uses an authentication context. Add `wsu_roles` as a mapped claim (the source attribute is `user.wsuRoles`, an on-premises AD attribute; the emitted claim is `wsu_roles`) and set `acceptMappedClaims: true` in the app manifest, so no custom signing key is needed and the metadata URL stays plain; list it in `oidc.extra_claims`. A tenant that does not send `accessid` leaves `oidc.user_claim` at `preferred_username`. 5. **Overview.** Copy the Directory (tenant) ID into `oidc.issuer` (`https://login.microsoftonline.com//v2.0`) and the Application (client) ID into `oidc.client_id`. Neither is a secret, but neither belongs in this repository either. The issuer is in Playbook as `SESAME_OAUTH2_ISSUER`. 6. **Authentication contexts** (only if a path uses `auth_context`): in Conditional Access, create the context (`c1` ...), and a policy that targets it with whatever it should demand. Warning The client secret never goes in this repository: put the value in the deployment's secret store as `DRAWBRIDGE_OIDC_CLIENT_SECRET`, and only the name of the variable goes in the config. Entra secrets expire, and the gateway cannot sign anyone in once it has, so note the expiry date. To rotate without signing anyone out: add a new secret in Entra, update `DRAWBRIDGE_OIDC_CLIENT_SECRET`, restart the gateway, check a sign-in, then delete the old secret. ### What to check [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#what-to-check) Before the first real sign-in, walk the first real Entra test: every setting by name, and what to check for each open question E-1 to E-8. Start the gateway the way the quick start shows: mount `drawbridge.yaml` and the signing key read-only, put the two secrets in the environment, and run the image. Then sign in as the first throwaway user and work through the rows. Inspect the claims in the ID token and in the assertion (for example through the app or a token inspector); never paste a token into a ticket. | Row | What to look at | What it answers | | --- | --- | --- | | E-1 | the `amr` values in the ID token after a normal sign-in and after an MFA sign-in | which real values the default `amr_map` passes through, and that an unknown value gives no `amr` | | E-2 | whether `auth_time` is present in the ID token | whether the tenant releases it as an optional claim | | E-3 | the `sub` claim in the assertion | that `accessid` (the UPN mail prefix) is the user identifier every app stores | | E-4 | the `wsu_roles` claim in the ID token | that the mapped claim arrives under that exact name, as a list of role strings | | E-5 | request a path with `auth_context: c1` and look at `acrs` in the ID token | that Entra honors the `claims` request parameter and returns the context, and what the context demands | | E-6 | the client secret's expiry date and who receives the notice | the rotation procedure and its owner | | E-7 | the redirect URI list after the test host is added | that one URI per app host works as apps join | | E-8 | sign out through `/_drawbridge/oidc/callback?logout=` and see where the browser lands | that Entra accepts the post-logout address on the app host, and that another host is refused | For E-5, sign in without the context first, then request the step-up path: the visitor should be sent back to Entra and come back with the context listed in `acrs`. For E-8, also try a logout address on another host and confirm the gateway refuses it. Danger Never commit values: keys, secrets, the passphrase, a real tenant ID or client ID stay out of git. This page carries names and placeholders only. Never use a production tenant for the first test. Never reuse the rig secrets: the values in `rig/compose.yaml` are throwaway and exist only for the mock provider. Never paste an ID token or an assertion into a ticket; describe the claims instead. Never write a tenant ID by hand; copy the issuer from the app registration Overview. ### Report back [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#report-back) Update the rows you checked in `OPEN_QUESTIONS.md`, in the table "The identity provider: Microsoft Entra ID (E-1 to E-8)": mark each answered row with the date and a short answer, in the style the file already uses (`**Answered YYYY-MM-DD:** ...`). If a claim arrives under a different name than expected (for example a long directory extension name instead of `wsu_roles`), say so on E-4: the config can list the exact name, or rename it to `wsu_roles` with a `{from, as}` entry in `oidc.extra_claims`. Leave a row open when the check could not be done, and note what is missing. ### Related [#](https://drawbridge.apps.wayne.edu/docs/guides/register-in-entra.html#related) - [Try it without Entra](https://drawbridge.apps.wayne.edu/docs/guides/try-without-entra.html) - [WSU values (Playbook)](https://drawbridge.apps.wayne.edu/docs/guides/wsu-values.html) - [Configuration](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html) - [Quick start](https://drawbridge.apps.wayne.edu/docs/guides/quick-start.html) --- Source: https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html ## Rotating the signing key [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#rotating-the-signing-key) This page covers how every app gets the public half of Drawbridge's signing key, and how to move the gateway to a new key without a moment where apps refuse sign-ins. The reasoning, and the options that were not chosen, are in [ADR-0001](https://git.wayne.edu/enterprise-apps/drawbridge/-/blob/main/ADR/ADR-0001-signing-key-distribution-and-rotation.md). ### The idea: current plus next [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#the-idea-current-plus-next) Drawbridge signs with one key at a time and names it in the `kid` header of every assertion. Apps verify with SESAME's `gateway` driver, which can hold several public keys and picks the one the `kid` names. The keys reach the apps as one small **key set file**, a standard JSON Web Key Set, that always holds two public keys: - the **current** key, which signs today; - the **next** key, which will sign after the next rotation. Because every app already trusts the next key, switching the gateway to it needs no app change at all. The apps only need to pick up a fresh file afterwards, and until they do, the file they have still works. The file holds public keys only, so it is not a secret: it may live in an app's repository or on a read-only mount. The private keys never leave the gateway's secret store. ### The schedule [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#the-schedule) | What | When | | --- | --- | | Rotate the signing key | every 12 months, and at once if a private key may have been exposed or someone who could read it leaves the team | | Remove a retired key from the file | no sooner than 5 minutes after the switch | | Name a key | by date, for example `drawbridge-2026-11`, so a `kid` never repeats | Why 5 minutes: an assertion signed just before the switch lives 60 seconds, plus SESAME's 30 seconds of clock skew. Five minutes also covers SESAME's `gateway.max_lifetime` ceiling of 300 seconds, so even a misconfigured lifetime cannot strand a request. ### The first key set [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#the-first-key-set) Make two key pairs, the current one and the next one, and write the file from their public halves: ```sh php bin/drawbridge keys:generate --private=drawbridge-2026-11.key --public=drawbridge-2026-11.pub php bin/drawbridge keys:generate --private=drawbridge-2027-11.key --public=drawbridge-2027-11.pub php bin/drawbridge keys:jwks --key=drawbridge-2026-11=drawbridge-2026-11.pub --key=drawbridge-2027-11=drawbridge-2027-11.pub --out=drawbridge-keys.json ``` The commands are the same in PowerShell. Use `--out` rather than redirecting the output: Windows PowerShell 5.1 writes redirected text as UTF-16, which is not JSON any app can read. Then: 1. Run the gateway with the current pair: `DRAWBRIDGE_SIGNING_KEY_FILE` points at `drawbridge-2026-11.key` and `DRAWBRIDGE_SIGNING_KEY_ID` is `drawbridge-2026-11`. 2. Keep `drawbridge-2027-11.key` in the same secret store, unused. 3. Hand `drawbridge-keys.json` to every app. Each app sets `SESAME_GATEWAY_JWKS_FILE` to its path (SESAME's [gateway driver guide](https://sesame.apps.wayne.edu/docs/guides/driver-gateway.html) has the app's side). `keys:jwks` refuses a private key, a key that is not ES256 (P-256), a `kid` given twice and more than 8 keys. SESAME checks the same things when it reads the file, and stops at boot on a bad one. ### A rotation [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#a-rotation) 1. **Switch the gateway to the next key.** Set `DRAWBRIDGE_SIGNING_KEY_FILE` to the next private key and `DRAWBRIDGE_SIGNING_KEY_ID` to its `kid`, then restart the gateway. The signer reads its key at start-up, so the change needs the restart. A restart rebuilds the shared-memory session store empty, so everyone signs in to the gateway again unless the [Redis session store](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html) is on: pick a quiet time. 2. **Check a sign-in** through the gateway to one app. 3. **Wait at least 5 minutes.** Assertions signed with the old key expire. 4. **Make a new next key and publish a new file** of the new current key and the new next key. The retired key is not in it. ```sh php bin/drawbridge keys:generate --private=drawbridge-2028-11.key --public=drawbridge-2028-11.pub php bin/drawbridge keys:jwks --key=drawbridge-2027-11=drawbridge-2027-11.pub --key=drawbridge-2028-11=drawbridge-2028-11.pub --out=drawbridge-keys.json ``` 5. **Hand the new file to every app.** There is no deadline for this step beyond the next rotation: an app still on the old file trusts the key that now signs. 6. **Destroy the retired private key** once the new file is out. The drawbridge goes up, the drawbridge comes down, and the castle never notices the chain was swapped. ### In an emergency [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#in-an-emergency) **The current private key may have leaked.** Do step 1 at once: every app already trusts the next key, so nothing breaks. Then do steps 4 and 5 the same day, so the leaked key leaves every app's file. Until an app picks up the new file it would still accept a token forged with the leaked key, so chase the stragglers. **The next key may have leaked too** (it usually sits next to the current one). Make a brand-new key pair, publish a file that holds only that key, and switch the gateway to it in the same window. Apps that have not picked up the file refuse every sign-in until they do. That is the price of a full compromise, and it fails closed, not open. ### Where the keys live [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#where-the-keys-live) Where the private keys are kept on Citadel, who can read them, how the key set file reaches the apps there (each app's repository, a shared read-only mount, or Playbook) and who runs the yearly rotation are the platform team's decisions; they are listed as open in `OPEN_QUESTIONS.md` (C-7). Off Citadel, the same two environment variables and one file work on any container platform. ### Related [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#related) - [Using the assertion in an app](https://drawbridge.apps.wayne.edu/docs/guides/using-the-assertion.html) - [Sessions and lifetimes](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html) - [Commands](https://drawbridge.apps.wayne.edu/docs/reference/commands.html) - [Troubleshooting](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html) --- Source: https://drawbridge.apps.wayne.edu/docs/guides/sessions.html ## Sessions and lifetimes [#](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html#sessions-and-lifetimes) This page explains the three sessions a signed-in visitor holds at once, how long each lasts, and what ends each one. ### Session lifetimes [#](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html#session-lifetimes) The `gateway` block sets how long a sign-in lasts and how long it may sit unused: `session_seconds` (default 28800 seconds, 300 to 604800) and `session_idle_seconds` (default 3600 seconds, 60 to 86400). Each app host renders them as mod_auth_openidc's `OIDCSessionMaxDuration` and `OIDCSessionInactivityTimeout`. ### Three sessions, three clocks [#](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html#three-sessions-three-clocks) A signed-in visitor has up to three sessions at once. Each has its own lifetime and its own owner, and ending one does not end the others. | Layer | Default lifetime | What ends it | What the visitor sees next | | --- | --- | --- | --- | | Entra (the identity provider) | set by Entra and its Conditional Access policy, not by Drawbridge | Entra's own policy, or the visitor signing out of Entra | Entra may sign them in again without a prompt, or ask for credentials | | Gateway (mod_auth_openidc, one per app host) | 8 hours total, 1 hour idle (`session_seconds`, `session_idle_seconds`) | either clock, the [`?logout=` link](https://drawbridge.apps.wayne.edu/docs/guides/signing-out.html), [`drawbridge revoke`](https://drawbridge.apps.wayne.edu/docs/guides/signing-out.html#ending-a-person-s-sessions-from-outside) (every host at once), or, with the default `shm` store, a restart or reload of the gateway (the cache lives in shared memory and starts empty) | a protected path sends them to Entra; an `api` path answers 401 | | App (SESAME) | 720 minutes total, 120 minutes idle (`session.absolute_minutes`, `session.idle_minutes`) | either clock, or the app calling `sesame_logout()` | the app's login route asks the gateway for a fresh assertion | How they fit together: - The assertion is used once, when the app signs the visitor in (it lives 60 seconds and SESAME's replay guard refuses a second use). After that the app's session runs on SESAME's clocks; a protected page reads SESAME's session, not the gateway. - So the app session can outlast the gateway session. With the defaults it can: the app allows 12 hours, the gateway 8. The gateway session ending does not sign anyone out of the app; the visitor finds out the next time the app sends them through its login route. To make the app never outlive the gateway sign-in, set the app's `session.absolute_minutes` to `session_seconds / 60` or less (480 for the default). - Signing out through the `?logout=` link ends the gateway session and asks Entra to end its own for that browser, not the app's. The app ends its own session first (`sesame_logout()`), then sends the browser to the link. - With the default `shm` store, a gateway restart signs everyone out of the gateway layer only; apps keep their sessions until their own clocks run out. Warning To make the app never outlive the gateway sign-in, set the app's `session.absolute_minutes` to `session_seconds / 60` or less (480 for the default). ### Where the sessions live [#](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html#where-the-sessions-live) By default the gateway keeps its sessions in Apache's shared memory, encrypted per host: one instance, nothing extra to run, and a restart or reload signs everyone in again. Set `gateway.session_store: redis` and `gateway.redis_host` (and `redis_port`, default 6379) to keep them in a Redis server you run. Sessions then survive a restart and a graceful reload (the rig's `redis` run proves the reload: `RedisTest::testSessionSurvivesAGatewayReload`; the last step of `redis-rotation` proves the restart: `RedisRotationTest::testRestartTheSessionSurvivesAGatewayRecreatedFromItsEnvironment`), and more than one gateway instance can serve the same hosts when every instance uses the same Redis and passphrase. That also gives `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS` a session to decrypt during a passphrase change, so nobody is signed out by it, proven by `rig/run.sh redis-rotation` (`RedisRotationTest`): see [Changing the passphrase](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html#changing-the-passphrase). The password comes from `DRAWBRIDGE_REDIS_PASSWORD`, never from the config file. Redis holds the sessions; ending one person's sessions from outside is `drawbridge revoke` and its revocation list, which every instance must share (see [Signing out](https://drawbridge.apps.wayne.edu/docs/guides/signing-out.html#ending-a-person-s-sessions-from-outside)). ### Changing the passphrase [#](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html#changing-the-passphrase) With the default `shm` store a new `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE` and a restart sign everyone in again: safe, but noisy. With `gateway.session_store: redis` you can change the castle password without locking out the people already inside the walls: 1. Set `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS` to the value in use now and `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE` to a new one (32+ characters), then restart the gateway. Sessions sealed under the old value keep working; new sign-ins use the new one. 2. Wait `session_seconds` (8 hours by default), so the sessions sealed under the old value run out on their own. 3. Remove `DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS` and restart again. A session still sealed under the old value is sent to sign in (a redirect, not an error page); the rest carry on. `rig/run.sh redis-rotation` (`rig\run.ps1 redis-rotation` on Windows) walks these steps against the pinned mod_auth_openidc on one gateway instance, with in-place reloads and a final restart of the gateway container: `RedisRotationTest`. With several instances, take each step on all of them before the next. `rig/run.sh multi` (`rig\run.ps1 multi`) proves it with two instances on one Redis (`MultiInstanceRotationTest`): once both hold the new and the old value, a session either one issues opens the app on the other, and once the old value is gone from both, both send a session sealed under it to sign in. It also shows the cost of a slow roll: while one instance holds only the old value, it cannot read a session another instance sealed under the new one, and sends that visitor to sign in again (a redirect, not an error page). ### One session per app host [#](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html#one-session-per-app-host) Each host encrypts its sessions with a passphrase of its own, so a session cookie carried to another host opens nothing there. The session and state cookies are removed before the request is proxied, and no provider token (ID, access or refresh) ever reaches an app. ### Related [#](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html#related) - [Signing out](https://drawbridge.apps.wayne.edu/docs/guides/signing-out.html) - [Using the assertion in an app](https://drawbridge.apps.wayne.edu/docs/guides/using-the-assertion.html) - [Configuration](https://drawbridge.apps.wayne.edu/docs/reference/configuration.html) - [Best practices](https://drawbridge.apps.wayne.edu/docs/reference/best-practices.html) --- Source: https://drawbridge.apps.wayne.edu/docs/guides/signing-out.html ## Signing out [#](https://drawbridge.apps.wayne.edu/docs/guides/signing-out.html#signing-out) This page shows how an app signs a visitor out: what the logout link does, which of the three sessions it ends and which it leaves to the app, and how an operator ends every gateway session a person holds, on every app host, without waiting for them to expire. ### The logout link [#](https://drawbridge.apps.wayne.edu/docs/guides/signing-out.html#the-logout-link) An app links to `/_drawbridge/oidc/callback?logout=`. mod_auth_openidc ends the gateway session for that host and sends the browser through Entra's sign-out endpoint (named in the provider's discovery document) back to the address. An address on another host is refused, so the link cannot be used to bounce visitors elsewhere. Signing in is held the same way: a sign-in started with a `target_link_uri` on another host (written plainly, protocol-relative or with a userinfo trick) never sends the visitor there, and the answer never names that host. The rig proves it (`GatewayTest::testLoginReturnsOnlyToTheSameHost`). ### What ends, and what does not [#](https://drawbridge.apps.wayne.edu/docs/guides/signing-out.html#what-ends-and-what-does-not) A signed-in visitor holds up to three sessions at once ([Sessions and lifetimes](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html)). The `?logout=` link touches the gateway and Entra layers, and leaves the app's session to the app: - **Gateway (mod_auth_openidc, one per app host).** Ends. mod_auth_openidc drops the session for that host, so a protected path sends the visitor back to Entra and an `api` path answers 401. - **Entra (the identity provider).** Asked to end. The browser is sent through Entra's sign-out endpoint, so Entra may end its own session for that browser. - **App (SESAME).** Left to the app. The app ends its own session first (`sesame_logout()`), then sends the browser to the link. Note Signing out through the `?logout=` link ends the gateway session and asks Entra to end its own for that browser, not the app's. The app ends its own session first (`sesame_logout()`), then sends the browser to the link. ### Single sign-out, and what Entra offers [#](https://drawbridge.apps.wayne.edu/docs/guides/signing-out.html#single-sign-out-and-what-entra-offers) The `?logout=` link is RP-initiated logout: mod_auth_openidc ends the session for the host the link is on, then sends the browser, as a top-level redirect, to the end-session endpoint in Entra's discovery document. Entra ends its own session for that browser and sends it back to the address. That is the whole chain, and every hop is a normal redirect the browser follows itself. What it does not do is end the person's gateway sessions on the other app hosts. Entra tells other apps about a sign-out only by front-channel logout: it loads each registered logout URL in a hidden iframe on its own sign-out page. Browsers that block or partition third-party cookies send no session cookie with that iframe, so the call cannot end anything, and Microsoft documents that it is not reliable across browsers. Entra documents no OpenID Connect back-channel logout (a server-to-server call) for app registrations. So Drawbridge registers no front-channel URL and renders no iframe, and the other hosts' sessions end on their own clocks, or at once with `drawbridge revoke` below. The next section shows why the `?logout=` link itself keeps working when third-party cookies are blocked. ### Signing out with third-party cookies blocked [#](https://drawbridge.apps.wayne.edu/docs/guides/signing-out.html#signing-out-with-third-party-cookies-blocked) Safari, Firefox and Chrome with tracking protection block or partition third-party cookies: a site loaded inside another site's page (an iframe, an image, a script) gets no cookies of its own. A sign-out built on that, such as front-channel logout, silently does nothing. The `?logout=` sign-out never needs it: 1. The app's link (or the redirect after its own `sesame_logout()`) is a top-level navigation to the app host, so the browser sends the gateway session cookie, a first-party cookie, as always. 2. mod_auth_openidc ends that session, answers `302` with `Cache-Control: no-store`, and sends the browser to Entra's end-session endpoint as a top-level redirect. At Entra, Entra's cookies are first-party. 3. Entra sends the browser back to the address, again a top-level redirect, and the session cookie for the app host is first-party there too (it is `SameSite=Lax`, which a top-level `GET` carries). No hop is an iframe, an image or a script, so blocking third-party cookies changes nothing. Even a browser that holds no Entra cookie at all (cleared, or partitioned away) ends the gateway session in step 2, before Entra is asked anything. The rig walks the hops one by one with a browser that holds only the app host's cookies (`tests/E2E/LogoutTest.php`): every answer is a redirect or the final page, none holds an `