[id="con-secret-rotation_{context}"]
[[_secret_rotation]]
= Client Secret Rotation
[role="_abstract"]

ifeval::[{project_product}==true]
:tech_feature_name: Client Secret Rotation
:tech_feature_setting: -Dkeycloak.profile.feature.client_secret_rotation=enabled
:tech_feature_id: client-secret-rotation
include::../../templates/techpreview.adoc[]
endif::[]

ifeval::[{project_community}==true]

[IMPORTANT]
====
Please note that Client Secret Rotation support is in development. Use this feature experimentally.
====

endif::[]

ifeval::[{project_community}==true]
For a client with <<_client-credentials, Confidential>> <<_access-type, Client authentication>> {project_name} supports the functionality of rotating client secrets through <<_client_policies, Client Policies>>.
endif::[]
ifeval::[{project_product}==true]
For a client with <<_client-credentials, Confidential>> <<_access-type, Access Type>> {project_name} supports the functionality of rotating client secrets through <<_client_policies, Client Policies>>.
endif::[]

The client secrets rotation policy provides greater security in order to alleviate problems such as secret leakage. Once enabled, {project_name} supports up to two concurrently active secrets for each client. The policy manages rotations according to the following settings:

* *Secret expiration:* [seconds] - When the secret is rotated, this is the expiration of time of the new secret. The amount, _in seconds_, added to the secret creation date. Calculated at policy execution time.
* *Rotated secret expiration:* [seconds] - When the secret is rotated, this value is the remaining expiration time for the old secret. This value should be always smaller than Secret expiration. When the value is 0, the old secret will be immediately removed during client rotation. The amount, _in seconds_, added to the secret rotation date. Calculated at policy execution time.
* *Remaining expiration time for rotation during update:* [seconds] - Time period when an update to a dynamic client should perform client secret rotation. Calculated at policy execution time.

When a client secret rotation occurs, a new main secret is generated and the old client main secret becomes the secondary secret with a new expiration date.

== Rules for client secret rotation
Rotations do not occur automatically or through a background process. In order to perform the rotation, an update action is required on the client, either through the {project_name} Admin Console through the function of *Regenerate Secret*, in the client's credentials tab or Admin REST API. When invoking a client update action, secret rotation occurs according to the rules:

* When the value of *Secret expiration* is less than the current date.
* During dynamic client registration client-update request, the client secret will be automatically rotated if the value of  *Remaining expiration time for rotation during update* match the period between the current date and the *Secret expiration*.

Additionally it is possible through Admin REST API to force a client secret rotation at any time.

[NOTE]
====
During the creation of new clients, if the client secret rotation policy is active, the behavior will be applied automatically.
====

WARNING: To apply the secret rotation behavior to an existing client, update that client after you define the policy so that the behavior is applied.
