---
title: "Rotating the signing key | DRAWBRIDGE docs"
description: "How apps get Drawbridge's public keys (a JWKS file of the current and the next key) and how to rotate the signing key without locking anyone out, including the emergency steps."
url: https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html
llms: https://drawbridge.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# Rotating the signing key [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#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](https://git.wayne.edu/enterprise-apps/drawbridge/-/blob/main/ADR/ADR-0001-signing-key-distribution-and-rotation.md).

## The idea: current plus next [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#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 [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#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 [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#the-first-key-set)

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

```sh
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](https://sesame.apps.wayne.edu/docs/guides/driver-gateway.html) 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 [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#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](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html) 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.
   ```sh
   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 [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#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 [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#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.

## Related [#](https://drawbridge.apps.wayne.edu/docs/guides/rotating-the-signing-key.html#related)

- [Using the assertion in an app](https://drawbridge.apps.wayne.edu/docs/guides/using-the-assertion.html)
- [Sessions and lifetimes](https://drawbridge.apps.wayne.edu/docs/guides/sessions.html)
- [Commands](https://drawbridge.apps.wayne.edu/docs/reference/commands.html)
- [Troubleshooting](https://drawbridge.apps.wayne.edu/docs/troubleshooting.html)
