Skip to content

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.

Build the gatehouse Read the section

Drawbridge mark: a cream gatehouse tower on a green tile, its bridge lowered on a gold chain
Section through the Drawbridge gatehouse An architect's section: a visitor stands on the approach bank, a moat lies between the bank and the gatehouse, and the drawbridge hangs from a gold chain. Inside the gatehouse are the header guard, the OpenID Connect client and the assertion signer; Entra ID, the identity provider, sits off the sheet; the passage leads to the app. 1 2 3 signed in drawbridge+jwt span: one sign-in 14 rules high moat: 60 s deep guard OIDC sign the approach the Citadel → Entra ID (OIDC) off this sheet, by others A section A-A · scale: one request
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
DoorPathRuleNeeds
D1/upexactpublic
D2/assets/prefixpublic
D3/admin/prefix
D4/admin/payroll/prefix + context c1
D5/admin/reports/prefix + a group
D6/api/prefixapi
D7/telescope/prefixdeny
D0anything elsedefault

$ 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.

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 .

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 <command>

config:validate
checks the config and prints every problem at once
explain <host> <path>
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 <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

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 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.

  1. Drawbridgesigns the visitor in, once
  2. SESAMEits gateway driver verifies the token
  3. HELMETsets the security headers
  4. 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.

Planned revisions
RevItemUntil then
doneA first deployment you can rehearseOn 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.
doneTwo gateways changing the passphrase togetherProven 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.
doneA passphrase rotation proven over RedisProven 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.
nextWhere the signing keys and the key set file live on CitadelThe 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.
laterThe rig as an automatic pipeline jobThe GitLab rig job runs by hand until the runners can run Docker; locally it is rig\run.ps1 or sh rig/run.sh.
noBearer tokens on API pathsDecided against: an api path takes the browser session, and without one it gets a plain 401.
noIdentity on public pathsDecided against: public means no identity, ever.