Skip to content
Menu

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#

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#

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.

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