Skip to content
Menu

Rotating the signing key#

This page covers how every app gets the public half of Drawbridge's signing key, and how to move the gateway to a new key without a moment where apps refuse sign-ins. The reasoning, and the options that were not chosen, are in ADR-0001.

The idea: current plus next#

Drawbridge signs with one key at a time and names it in the kid header of every assertion. Apps verify with SESAME's gateway driver, which can hold several public keys and picks the one the kid names.

The keys reach the apps as one small key set file, a standard JSON Web Key Set, that always holds two public keys:

  • the current key, which signs today;
  • the next key, which will sign after the next rotation.

Because every app already trusts the next key, switching the gateway to it needs no app change at all. The apps only need to pick up a fresh file afterwards, and until they do, the file they have still works.

The file holds public keys only, so it is not a secret: it may live in an app's repository or on a read-only mount. The private keys never leave the gateway's secret store.

The schedule#

What When
Rotate the signing key every 12 months, and at once if a private key may have been exposed or someone who could read it leaves the team
Remove a retired key from the file no sooner than 5 minutes after the switch
Name a key by date, for example drawbridge-2026-11, so a kid never repeats

Why 5 minutes: an assertion signed just before the switch lives 60 seconds, plus SESAME's 30 seconds of clock skew. Five minutes also covers SESAME's gateway.max_lifetime ceiling of 300 seconds, so even a misconfigured lifetime cannot strand a request.

The first key set#

Make two key pairs, the current one and the next one, and write the file from their public halves:

php bin/drawbridge keys:generate --private=drawbridge-2026-11.key --public=drawbridge-2026-11.pub
php bin/drawbridge keys:generate --private=drawbridge-2027-11.key --public=drawbridge-2027-11.pub
php bin/drawbridge keys:jwks --key=drawbridge-2026-11=drawbridge-2026-11.pub --key=drawbridge-2027-11=drawbridge-2027-11.pub --out=drawbridge-keys.json

The commands are the same in PowerShell. Use --out rather than redirecting the output: Windows PowerShell 5.1 writes redirected text as UTF-16, which is not JSON any app can read.

Then:

  1. Run the gateway with the current pair: DRAWBRIDGE_SIGNING_KEY_FILE points at drawbridge-2026-11.key and DRAWBRIDGE_SIGNING_KEY_ID is drawbridge-2026-11.
  2. Keep drawbridge-2027-11.key in the same secret store, unused.
  3. Hand drawbridge-keys.json to every app. Each app sets SESAME_GATEWAY_JWKS_FILE to its path (SESAME's gateway driver guide has the app's side).

keys:jwks refuses a private key, a key that is not ES256 (P-256), a kid given twice and more than 8 keys. SESAME checks the same things when it reads the file, and stops at boot on a bad one.

A rotation#

  1. Switch the gateway to the next key. Set DRAWBRIDGE_SIGNING_KEY_FILE to the next private key and DRAWBRIDGE_SIGNING_KEY_ID to its kid, then restart the gateway. The signer reads its key at start-up, so the change needs the restart. A restart rebuilds the shared-memory session store empty, so everyone signs in to the gateway again unless the Redis session store is on: pick a quiet time.
  2. Check a sign-in through the gateway to one app.
  3. Wait at least 5 minutes. Assertions signed with the old key expire.
  4. Make a new next key and publish a new file of the new current key and the new next key. The retired key is not in it.
    php bin/drawbridge keys:generate --private=drawbridge-2028-11.key --public=drawbridge-2028-11.pub
    php bin/drawbridge keys:jwks --key=drawbridge-2027-11=drawbridge-2027-11.pub --key=drawbridge-2028-11=drawbridge-2028-11.pub --out=drawbridge-keys.json
    
  5. Hand the new file to every app. There is no deadline for this step beyond the next rotation: an app still on the old file trusts the key that now signs.
  6. Destroy the retired private key once the new file is out.

The drawbridge goes up, the drawbridge comes down, and the castle never notices the chain was swapped.

In an emergency#

The current private key may have leaked. Do step 1 at once: every app already trusts the next key, so nothing breaks. Then do steps 4 and 5 the same day, so the leaked key leaves every app's file. Until an app picks up the new file it would still accept a token forged with the leaked key, so chase the stragglers.

The next key may have leaked too (it usually sits next to the current one). Make a brand-new key pair, publish a file that holds only that key, and switch the gateway to it in the same window. Apps that have not picked up the file refuse every sign-in until they do. That is the price of a full compromise, and it fails closed, not open.

Where the keys live#

Where the private keys are kept on Citadel, who can read them, how the key set file reaches the apps there (each app's repository, a shared read-only mount, or Playbook) and who runs the yearly rotation are the platform team's decisions; they are listed as open in OPEN_QUESTIONS.md (C-7). Off Citadel, the same two environment variables and one file work on any container platform.