Skip to content
Menu

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 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: a fresh one on every request
  • auth_time, amr and acrs when the ID token carries them
  • email, name and affiliations when configured
  • any extra_claims, for example wsu_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.