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. 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 directly for now. Once the gateway is live, Citadel apps switch SESAME to its gateway driver.
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.
-
Browser
Sends whatever headers it wants, forged ones included.
the approach
-
Guard
Strips every inbound identity header, in every hyphen and underscore spelling, before anything else runs.
mod_lua
-
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
-
Signer
Signs a new ES256 assertion for each request. If signing fails, the visitor gets a 503.
mod_rewrite prg: map + PHP
-
App
Receives the request with one signed header and checks it with SESAME's
gatewaydriver.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 | Path | Rule | Needs |
|---|---|---|---|
| D1 | /up | exact | public |
| D2 | /assets/ | prefix | public |
| D3 | /admin/ | prefix | login |
| D4 | /admin/ | prefix | login + context c1 |
| D5 | /admin/ | 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
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-UserX-Remote-UserX-Forwarded-*ForwardedX-Real-IPX-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.
- Strip first. Inbound identity headers go, in any spelling, before authentication runs on any request.
- Fail closed. No session, no signature, a refused path, a missing key or a bad config means no access.
- Public is a decision. A path with no rule gets the app's default:
login, ordenyfor an app that lists every path it has. Public paths carry no identity. - Match the normalized path. Encoded slashes, backslashes, semicolons and bad UTF-8 are treated as protected.
- Exact or prefix, nothing clever. No wildcards or regular expressions. The Apache pattern is built from the literal path.
- Shut what nobody should reach. A
denypath gets the gateway's 403 page and never reaches the app. - Groups come from the token. A rule's groups are read from the validated ID token, whole and case-sensitive, never from a header.
- Sign narrowly and briefly. ES256, a pinned
typ, one audience per app, a freshjtieach time. - Let the module do OpenID Connect. Drawbridge writes no OAuth client. Forged callbacks and missing contexts are refused.
- One session per app host. A session cookie carried to another host opens nothing there.
- Raise it on demand.
drawbridge revokeends every session a person holds, on every app host, without waiting for it to expire. - Sign out at the top level. Every sign-out hop is a redirect, never an iframe, so it works with third-party cookies blocked.
- Overwrite forwarded headers.
X-Forwarded-*come from the gateway, never the client. - 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.
- Do not trust the network. The app verifies the signature even if only the gateway can reach it.
- Run small and boring. Non-root, port above 1024, state under
/tmp, logs to stdout. - Watch the floor.
composer auditruns in CI, andcomposer advisoriesasks OSV.dev whether Debian has patched the image's Apache or mod_auth_openidc. - 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.
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/<tenant-id>/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 .
$ 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/<tenant-id>/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.yamlthe per-app configsigning.keythe ES256 key;keys:generatemakes oneDRAWBRIDGE_OIDC_CLIENT_SECRETthe Entra client secret, from the app registrationDRAWBRIDGE_OIDC_CRYPTO_PASSPHRASEencrypts 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 <command>
config:validate- checks the config and prints every problem at once
explain <host> <path>- says which rule applies, and why
render- writes
apps.confandpolicy.luafor 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 <subject>- 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)
$ 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
$ docker compose exec gateway /opt/drawbridge/bin/drawbridge smoke
- OKgateway up/_drawbridge/up answers 200 ok
- OKgateway unknown-hosta host that is not in the config gets 403
- 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
- OKapp1 api/api/ answers a bare 401 without a session
- OKapp1 deny/telescope/ answers 403 and never reaches the app
- OKapp1 public/assets/ reaches the app (200) with no sign-in
- OKapp1 headersthe proxied answer carries X-Content-Type-Options and Strict-Transport-Security
- OKapp1 clockthe app's clock is 0 s from the gateway's (assertions allow 30 s of skew)
- OKapp1 callbacka made-up code and state sign nobody in (400)
- 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.
- 1Copy the kit and fill in the files
- 2Make the signing key and the key set file
- 3Start it
- 4Health, then
drawbridge smoke - 5Sign in; whoami shows what it verified
- 6Read the logs and
/metrics - 7Roll the gateway back, smoke again
- 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 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.
Spec 01 · The gatehouse, on your machine
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.
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
Spec 02 · Laravel, Blade or Inertia
A Laravel app behind Drawbridge
Its door schedule for the gate, and SESAME's gateway driver checking the signed assertion on the way in.
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.
Spec 03 · Raw PHP, no framework
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.
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 lists them, llms-full.txt has them all in one file, and this page has a Markdown twin. 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 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.
-
Drawbridgesigns the visitor in, once
-
SESAMEits gateway driver verifies the token
-
HELMETsets the security headers
-
WayneUIrenders the page
Key
WayneUI the interface layer
CREED the shared rules and policy
PROCTOR checks an app against the policy
Preflight the shared CI components
SESAME sign-in inside the app
HELMET security headers and CSP reports
Pinstripe code style presets
Sourdough starts an app in any of the five shapes, raw PHP to Inertia and Vue
WELD the Laravel starter, with the stack set up
Booster upgrades PHP and Laravel one version at a time
Rollcall every app answers "present"
ADVISOR an MCP server your agent can ask
Squire the deploy kit for Citadel
Parity 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.
| 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. |