Rotating client credentials

Why credentials change

A client credential is replaced for ordinary reasons as well as alarming ones. A policy may require secrets to be replaced every year, or the server may issue them with an expiry date. A developer who had access to the secret may leave the company. The printer may move from a client secret to a key pair, or from one signing algorithm to another. And sometimes a credential turns up somewhere it should not be, such as a public repository or a log file.

Because replacement is certain to happen, it should be routine: practiced, documented, and possible without downtime. A rotation that only happens during an emergency tends to go badly, because the first time anyone tries the procedure is the moment it matters most.

Overlapping old and new

The outage above happened because the old and new secrets were never valid at the same time. Many authorization servers avoid that by allowing a client to hold two secrets during a change. The rotation then has four steps:

1. Add. Create a second secret for photo-printer. The old one keeps working.
2. Deploy. Put the new secret in the secrets store and restart or reload every server, at whatever pace is safe.
3. Confirm. Check that requests are now arriving with the new secret. A server that records which secret each request used, or when each secret was last used, makes this a fact rather than a guess.
4. Remove. Delete the old secret.

Each step can be undone until the last one. If a server turns out to have its own forgotten copy of the configuration, the confirm step shows it still using the old secret, and the team fixes that before removing anything.

When a server allows only one secret per client, the overlap disappears. Replacing it becomes a coordinated switch: change the secret and the deployed configuration as close together as possible, and accept a short window of failures. Knowing which kind of server you are dealing with before the day of the rotation is part of planning it.

Rotating a key pair

Key pairs make overlap natural. The Storing and using keys lesson described publishing public keys in a set, each labeled with a key identifier. If the printer registered the address of its published key set (the jwks_uri registration field) rather than a single key, it can rotate without asking the photo service to change anything:

GET /.well-known/oauth-client-keys.json HTTP/1.1
Host: printer.example

{
  "keys": [
    { "kid": "printer-2026-10", "kty": "EC", "crv": "P-256", "x": "...", "y": "..." },
    { "kid": "printer-2027-01", "kty": "EC", "crv": "P-256", "x": "...", "y": "..." }
  ]
}

The key values are shortened here. The path is the printer's choice; what matters is that the registration points to it.

The printer first adds the new public key, printer-2027-01, to the set while still signing with the old one. Once the photo service can see the new key, the printer starts signing assertions with it. The server sees an unfamiliar kid, fetches the set again if its cached copy does not include it, and verifies the signature. After the last assertion signed with the old key has expired, a matter of minutes, the printer removes the old key from the set.

At no point does a secret need to be copied between servers, and at no point is there a moment where the only valid credential is one the printer has not deployed yet. If the registration holds a single key instead of an address, the same steps apply, but adding and removing keys means updating the registration.

When a credential has leaked

A careful overlap assumes no one else holds the old credential. If the printer's secret has appeared in a public repository, that assumption is gone. Every minute the old secret remains valid, someone else can use it.

The order changes. Revoke the leaked credential first, even if that breaks the printer until the new one is deployed. A short, honest outage is better than leaving a working credential in a stranger's hands while the deployment proceeds at a comfortable pace.

Then consider what the credential could already have been used for. Tokens issued before the revocation do not disappear on their own. Access tokens remain usable until they expire, unless the service can revoke them. Refresh tokens are bound to the client, so someone holding both the leaked secret and a stolen refresh token could have kept obtaining access. Depending on what the logs show, the photo service may revoke the tokens issued to the client, and the printing company may need to tell affected customers.

Logs help most when they were written before anything went wrong. Records of token requests that show the client, the authentication method, which credential was used, and where the request came from let the team tell normal use from misuse. They must never contain the secret or the assertion itself.

This completes the picture of a client: how it is registered, where its responses may go, how it proves itself, and how it changes that proof safely. The next section turns to the other side of the token, the resource servers that receive it.