Using the assertion in an app#
This page shows how your app receives the signed assertion Drawbridge signs on every protected request, and how SESAME's gateway driver checks it so the app never parses the token itself.
What the app receives#
On every request to a protected path, Drawbridge signs a new assertion and forwards the request to the app with it in the header X-Sesame-Assertion. 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 nothing reaches the app unsigned.
The token shape#
The assertion is a compact JWT signed with ES256, with typ: drawbridge+jwt and a kid in its header. Its claims are:
iss: Drawbridge, never Entraaud: the app's hostsub: the configured user claim,accessidin the example config andpreferred_usernameif unsetiat,nbf,exp: 60 seconds by defaultjti: a fresh one on every requestauth_time,amrandacrswhen the ID token carries thememail,nameandaffiliationswhen configured- any
extra_claims, for examplewsu_roles
That shape is the front page's general note "Sign narrowly and briefly", held by best practices D4 to D8 and D41: ES256, a pinned typ, one audience per app, 60 seconds by default, a fresh jti on every request, and the key never leaves the signer.
Point SESAME's gateway driver at Drawbridge#
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.
The gateway block in config/drawbridge.yaml names the two halves of the contract:
gateway:
# The "iss" claim of the assertion Drawbridge signs. SESAME's gateway.issuer must match it exactly.
issuer: https://auth.apps.wayne.edu
# The header that carries the signed assertion. SESAME's default is X-Sesame-Assertion.
assertion_header: X-Sesame-Assertion
SESAME's gateway.issuer must match the iss claim exactly. The public keys reach the app as one key set file (a JWKS of the current and the next key, written by keys:jwks), and the app points SESAME_GATEWAY_JWKS_FILE at it, so a key rotation needs no change in the app; see Rotating the signing key. The assertion (header, claims, signing algorithm, lifetime) is a contract between the two; change both together.
One assertion, one use#
SESAME's gateway driver requires jti, refuses assertions that live longer than its maximum, and checks each jti with a replay guard (in-memory or PSR-16). Drawbridge puts a fresh jti in every token, so a replayed assertion is refused.