Signing keys

Rotate the keys that sign your organization's ID tokens and access tokens, and make sure your apps always have the keys they need to verify them.

Permission

Rotating keys needs Change sign-in, branding, domains and keys.

Each organization has its own keys: RSA 2048-bit, signing with RS256. Apps verify tokens against your organization's JWKS:

https://acme.fobauth.com/oauth/jwks

Each token's header names its key in kid. The console lists the 20 most recent keys on Settings > Signing keys.

SAML apps use a separate certificate, which rotating these keys doesn't change. See SAML apps.

Rotate a key

Fob doesn't rotate keys on a schedule. To rotate one, open Settings > Signing keys and choose Rotate key.

Rotation is safe to do at any time. It happens in three steps, so your apps never see a token signed by a key they haven't fetched:

1. The new key appears in the JWKS straight away. The current key keeps signing.
2. 10 minutes later, the new key starts signing.
3. The old key stays in the JWKS for 2 more days, so tokens it signed keep verifying until they expire.

You can't start another rotation during those 10 minutes.

Status in the console	Meaning
Starts signing at (time)	In the JWKS, not signing yet
Signing	Signs every new token
Retired, still published	Stopped signing in the last 2 days. Its tokens still verify.
Retired	No longer in the JWKS. Its tokens don't verify.

Replace a leaked key

If a key may have leaked, choose Rotate key and check Switch now. Fob creates a new key that signs from that moment, and removes every older key from the JWKS.

Warning

Every ID token and access token signed by the old keys stops verifying, within 15 seconds at Fob's endpoints and as soon as your apps refresh their JWKS cache. Users stay signed in to Fob, and apps holding a refresh token get new tokens on their next refresh, but anything relying on an existing access token fails until then.

Every rotation is recorded in the audit log as keys.rotated, and sent as a webhook.

Caching the JWKS in your app

Most libraries fetch the JWKS again when a token arrives with a kid they don't have, so you don't need to do anything. If you cache the JWKS yourself:

• Refresh it at least every 10 minutes. Fob's response can be cached for 5 minutes.
• Refresh it straight away when you see a kid you don't have.

That way normal rotations never break your app, and an emergency replacement takes effect quickly.