Renewing a client secret or a signing key should be a routine operation. In practice, it is often the operation one postpones, because last time it caused an interruption: a consumer kept the old secret, a gateway kept the old key in cache, and calls failed for long minutes.

The strategy we apply comes down to one idea: never replace one value with another in a single step, but let them coexist for the duration of the cutover. It applies whatever the authorisation server and whatever the gateway, provided one checks what each component supports.

The mechanisms described here are generic. Exact capabilities (several active secrets per client, key cache duration, and so on) vary by product and version: check them in your own environment before planning a rotation.

Two different rotations

“OAuth2 rotation” is often used to mean two distinct operations:

  1. rotation of a client secret (or of its private key, if it authenticates with a key or a certificate): this is the identity of the application requesting tokens;
  2. rotation of the authorisation server’s signing keys: these are the keys that sign tokens, and that gateways and APIs use to verify them.

Both follow the same overlap principle, but not with the same actors.

Rotating a client secret

The problem

A client secret is known on two sides: the authorisation server, which verifies it, and the application, which presents it. If it is changed first on the server, the application fails until it is updated. If it is changed first on the application, the server rejects it.

The overlap sequence

  1. Create the new secret without revoking the old one. Both are accepted by the authorisation server. Depending on the product, this uses a native rotation feature, or a temporary second client if only one active secret is possible.
  2. Distribute the new secret to the application, ideally through a secrets vault rather than a configuration file.
  3. Verify that the application is actually using the new secret: authorisation-server logs, token-issuance metrics. Do not settle for “the configuration has been deployed”.
  4. Revoke the old secret, once the cutover has been confirmed for every instance.

Access tokens already issued generally remain valid until they expire: rotating the secret does not necessarily invalidate them. If the aim is to cut off a compromised access, in-flight tokens must also be handled (revocation, short lifetime), which is a different operation.

The pitfalls

  • Forgotten instances: a batch job, a standby environment, a container that has not restarted. They fail at the moment of revocation.
  • Application caches: some applications read the secret at startup and never reread it. This needs to be known before the rotation, not after.
  • Shared secrets: the same client used by several applications makes the cutover much harder to verify. One client per application simplifies everything.

Rotating signing keys

The problem

Gateways and APIs verify token signatures using the public keys published by the authorisation server, usually through a JWKS endpoint. For performance reasons, they cache these keys. If the server starts signing with a new key that verifiers do not yet know, tokens are rejected.

The overlap sequence

  1. Publish the new public key without using it. The JWKS now contains both the old and the new key, each with its identifier (kid).
  2. Wait until every verifier has refreshed its cache. The delay depends on the configuration of each gateway and library: it must be known, and checked on your own components, before the rotation is planned.
  3. Start signing with the new key. New tokens carry the new kid; verifiers find it in their cache.
  4. Keep the old public key in the JWKS at least until the last tokens signed with it have expired.
  5. Remove the old key.

The pitfalls

  • Hard-coded keys: some components were configured with a fixed public key rather than with the JWKS URL. They will not follow the rotation.
  • Caches that do not refresh on an unknown kid: some implementations refresh the JWKS when they meet an unknown identifier, others do not. The behaviour must be checked.
  • “Ghost caches”: an intermediate cache (proxy, CDN, application cache) that serves an old JWKS after the source has changed.

Making rotation routine

A rare rotation is a risky rotation, because nobody remembers the procedure. What makes it ordinary:

  • automating it in a pipeline, with the same steps every time;
  • verifying each step through a real observation (tokens obtained, tokens accepted), not through the return code of a command;
  • testing it in staging under continuous traffic before running it in production;
  • scheduling it at a frequency adapted to the risk and to the security requirements, rather than in reaction to an incident.

What if shared secrets could be avoided?

The shared client secret remains the most widespread mode, but it is not the only one. Client authentication with a private key (for example private_key_jwt) or with a certificate (mTLS) avoids circulating a secret known on both sides: only the public key is deposited on the server. Rotation then follows the same overlap principle, applied to keys. It is an evolution worth considering, without making it a prerequisite.

What to take away

A rotation without downtime always rests on the same sequence: add the new value, wait until everyone knows it, cut over, verify, then withdraw the old one. The difficulty is not cryptographic: it lies in the inventory of the components involved and in knowledge of their caches. That is true on every gateway and every authorisation server we have encountered.

Alongside its consulting work, CAB Ingénierie develops STOA, a sovereign iPaaS and API integration platform.

Let's talk about your project

Do your secret or key rotations cause interruptions, or do you postpone them for lack of a reliable procedure? Tell us about your context in a few lines: cab-ingenierie.com · contact@cab-ingenierie.com