Client secret rotation in Keycloak lets a confidential client have two valid secrets at the same time, so you can give the new secret to your applications before the old one stops working. The feature was a preview before Keycloak 26.8.0, and the 26.8.0 release notes promote it to supported. It is configured with a client policy, and one detail is easy to miss: nothing rotates the secret on a timer, while the secret does expire on a timer. If no rotation happens before the expiry, Keycloak rejects the expired secret and the client can no longer authenticate, so you need something that triggers rotations on time.
This guide explains how the feature works, how to set it up, how to roll a new secret out without downtime, and where the limits are. Everything below is taken from the Keycloak 26.8 documentation, release notes and server source code.
Why does rotating a client secret cause downtime?
A client secret is a shared password between an application and Keycloak, and it is used when the application authenticates to the token endpoint, for example in the client credentials grant or when redeeming an authorization code. Without a rotation policy a client has one secret, so replacing it means the old value stops working at the moment the new one is created. Every instance of the application then needs the new value immediately, and any instance that has not picked it up yet gets authentication errors until it does.
The 26.8.0 release notes describe the same problem: rotating client secrets in production “required manual coordination and risked service interruptions if the old secret was invalidated before all consumers switched to the new one”. Teams that wanted to rotate regularly, for example because a secret may have appeared in a log or because a compliance policy asks for it, tended to postpone it for exactly this reason. Rotating regularly also limits how long a leaked secret stays useful, which matters given how often secrets leak through configuration files and logs; our write-up of a Keycloak vault client secret exposure is one example.
How does Keycloak client secret rotation work?
Once you enable the rotation policy, Keycloak supports up to two concurrently active secrets for each client. When a rotation happens, Keycloak generates a new main secret, and the previous main secret becomes the secondary secret with a new, shorter expiry. During the overlap, the client can authenticate with either one. When the secondary secret expires, only the new one remains.
The policy has three settings, all in seconds:
| Setting | What it controls |
|---|---|
| Secret expiration | How long a new secret lives. It is counted from the moment the policy sets the expiry, which is the rotation time for a new secret. |
| Rotated secret expiration | How long the old secret stays valid after a rotation. It should be smaller than Secret expiration (Keycloak rejects a larger value). A value of 0 removes the old secret immediately, which brings back the downtime risk. |
| Remaining expiration time for rotation during update | For dynamic client registration: the window before the secret expires in which an update to the client triggers a rotation. |
The Keycloak guide’s example uses one week for each secret, two days for the rotated secret and a one-day update window.
Rotation is triggered by a request, not by a schedule
The feature name suggests automatic rotation, but the Server Administration Guide states that rotations do not occur automatically or through a background process. Keycloak records an expiry time for the secret, but it does not rotate it when that time arrives. A rotation happens only when something asks for one: Regenerate Secret on the client’s Credentials tab in the Admin Console, or POST /admin/realms/{realm}/clients/{id}/client-secret on the Admin REST API, which forces a rotation at any time. For dynamic client registration, an update inside the configured window before expiry also rotates the secret.
A plain client update through the Admin REST API is not a reliable trigger. In the 26.8.1 source, an ordinary update rotates the secret only after it has already expired, and by then the client is failing to authenticate.
If nothing rotates the secret before Secret expiration passes, Keycloak rejects the expired secret (ClientIdAndSecretAuthenticator treats an expired secret as a failed authentication), and the application receives authentication errors until someone rotates it. Something must rotate the secret before it expires, not after. In practice that is a scheduled job or pipeline in your own tooling that calls the Admin REST API, or a person with a calendar reminder. If a secret does expire, Regenerate Secret recovers the client at once, because the expired secret becomes the rotated secret with a new rotated-secret expiry while you distribute the new one.
How do you set up a client secret rotation policy?
The setup uses Keycloak’s client policies, in three steps. All of this is in the Admin Console under Realm settings, on the Client policies tab.
- Create a client profile. Choose Create client profile, give it a name such as “Weekly client secret rotation”, and save it.
- Add the executor. Inside the profile, select Add executor, choose the executor type
secret-rotation, and enter the Secret expiration, Rotated secret expiration and Remaining expiration time values. - Create a policy that uses the profile. On the Policies sub-tab choose Create client policy, add a condition, and attach your profile. To cover all confidential clients, use the
client-access-typecondition with the valueconfidential. To cover only some clients, theclient-rolescondition lets you give different rotation settings to clients that hold different roles.
Two rules are worth remembering. New clients get the behavior automatically at creation. Existing clients do not get an expiry until something touches them once the policy matches. An admin update or Regenerate Secret sets one, and so does the client’s next authorization request or authorization code exchange. A client that only uses the client credentials grant gets no expiry from its token requests, so it stays on a single secret with no expiry until you update or rotate it. Because an expiry can be set without any rotation, enable a policy for all confidential clients only after your rotation job is in place, otherwise a matched client can stop authenticating one Secret expiration period after the policy first touches it.
How do you roll a new secret out without downtime?
With the policy in place, the rollout for one client follows a fixed order:
- Trigger the rotation with Regenerate Secret in the Admin Console, or
POST /admin/realms/{realm}/clients/{id}/client-secret, before the current secret expires. Keycloak creates the new main secret, and the old one becomes the secondary secret with the rotated-secret expiry. - Distribute the new secret to every application instance and every place it is stored, such as your secrets manager, CI variables and Kubernetes secrets. Redeploy or reload the applications. While you do this, instances still using the old secret keep working.
- Confirm that nothing uses the old secret anymore. Before the old secret expires, check the realm’s login events for the client (with Save events enabled under Realm settings, Events) and look for the detail
client_auth_detail=rotated_secret. The events API cannot filter on details, so list the client’s events and inspect them, or watch for the detail in an event listener or your log pipeline. Keycloak records that detail when a client authenticates with the old secret, so any client still producing it has not picked up the new one. - Let the old secret expire. After the Rotated secret expiration, only the new secret works. If you are certain every consumer has switched,
DELETE /admin/realms/{realm}/clients/{id}/client-secret/rotatedends the overlap early.
Pick a Rotated secret expiration that is longer than your slowest deployment path. If production deploys happen once a week, a one-hour overlap is not enough. The overlap exists to absorb that delay, so size it to your release process and not to the ideal case.
What does client secret rotation not cover?
- It applies to confidential clients that authenticate with a client secret. Public clients have no secret to rotate, and clients that authenticate with signed JWTs or certificates use different credentials, which are rotated separately.
- It does not distribute the secret for you. Getting the new value into your applications is still your job, and a secrets manager with a rotation workflow makes that far easier. See our secrets management guide for Keycloak’s vault options.
- It does not remove the need for monitoring. The two-secret window hides a missed deployment until the old secret expires, so use the
rotated_secretevents described above to find stragglers first.
Rotation matters most for machine-to-machine clients. To compare client secrets with other approaches, see API keys vs OAuth and our API authentication best practices. If you manage clients declaratively, for example through the operator, see Admin API v2 and declarative clients, since a rotating secret and a declared configuration need to agree on where the secret value lives.
Frequently asked questions
Is Keycloak client secret rotation supported in 26.8?
Yes. The 26.8.0 release notes state that Client Secret Rotation is promoted from preview to supported in that release.
Does Keycloak rotate secrets automatically on a schedule?
No. According to the Server Administration Guide, rotations do not happen automatically or through a background process. The expiration settings define when a rotation is due, and Regenerate Secret in the Admin Console or the client-secret endpoint of the Admin REST API performs it. A secret that passes its expiry without a rotation stops working.
How many secrets can a client have at once?
Up to two while the policy is active: the current main secret and the previous one, which remains valid until its Rotated secret expiration.
Which clients does the policy apply to?
It applies to confidential clients that match the policy’s conditions. You can target all confidential clients with the client-access-type condition, or select clients by role with the client-roles condition.
Does it work for clients that already exist?
Partly. An existing client gets an expiry date only when it is updated or rotated through the Admin Console or Admin REST API, or, for clients that use browser logins, at its next authorization request or authorization code exchange. Clients that only use the client credentials grant are not picked up by token requests, so update or rotate each one once, for example with Regenerate Secret on its Credentials tab.
What should Rotated secret expiration be?
Longer than the time it takes to roll the new secret out to every instance of the application, and always shorter than Secret expiration. Setting it to 0 removes the old secret immediately and gives up the zero-downtime benefit.
Summary
Keycloak 26.8 makes two-secret client rotation a supported feature, and it works through a client policy with a secret-rotation executor. Set the expiry values around your real deployment cadence, enable the policy for confidential clients, update existing clients once so the policy applies, and run the rotation from a job or pipeline that calls the Admin REST API before each expiry, because Keycloak does not rotate on its own and rejects a secret that has expired. After each rotation, check for rotated_secret events before the old secret expires.