Add images and new adoc files about client secret rotation (#1449)

Closes #10610

release_notes/topics/18_0_0.adoc

@@ -4,6 +4,12 @@
 
 Recovery Codes as another way to do two-factor authentication is now available as a preview feature.
 
+== Client secret rotation
+
+{project_name} now supports Client Secret Rotation through customer policies. This feature is now available as a preview feature and allows that confidential clients can be provided with realm policies allowing the use up to two secrets simultaneously.
+
+For more details, see link:{adminguide_link}#_secret_rotation[{adminguide_name}].
+
 == OpenID Connect Logout Improvements
 
 Some fixes and improvements were made to make sure that {project_name} is now fully compliant with all the OpenID Connect logout specifications:

server_admin/topics/clients/assembly-client-oidc.adoc

@@ -12,6 +12,10 @@ include::oidc/con-advanced-settings.adoc[leveloffset=+1]
 
 include::oidc/con-confidential-client-credentials.adoc[leveloffset=+1]
 
+include::oidc/con-secret-rotation.adoc[leveloffset=+1]
+
+include::oidc/proc-secret-rotation.adoc[leveloffset=+1]
+
 include::oidc/proc-using-a-service-account.adoc[leveloffset=+1]
 
 include::oidc/con-audience.adoc[leveloffset=+1]

server_admin/topics/clients/client-policies.adoc

@@ -122,6 +122,7 @@ One of several purposes for this executor is to realize the security requirement
 * Enforce more secure `state` and `nonce` parameters treatment for preventing CSRF
 * Enforce more secure signature algorithm when client registration
 * Enforce `binding_message` parameter is used for CIBA requests
+* Enforce <<_secret_rotation, Client Secret Rotation>>
 
 [[_client_policy_profile]]
 === Profile
@@ -155,3 +156,6 @@ client registration policies are applied.
 
 The current plans are for the Client Registration Policies feature to be removed and the existing client registration policies will be migrated into new client policies automatically.
 
+== Client Secret Rotation Example
+
+See an example configuration for <<_proc-secret-rotation,client secret rotation>>.

server_admin/topics/clients/oidc/con-secret-rotation.adoc

@@ -0,0 +1,45 @@
+[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::[]
+
+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>>.
+
+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.

server_admin/topics/clients/oidc/proc-secret-rotation.adoc

@@ -0,0 +1,104 @@
+[id="proc-secret-rotation_{context}"]
+
+[[_proc-secret-rotation]]
+
+= Creating an OIDC Client Secret Rotation Policy
+[role="_abstract"]
+
+The following is an example of defining a secret rotation policy:
+
+.Procedure
+. Click *Realm Settings* in the left menu.  
+
+. Click *Client Policies* tab.
+
+. On Profiles Page, Click *Create*
++
+.Create a profile
+image:images/create-oidc-client-profile.png[Create Client Profile]
+
+. Enter any name for *Name*.
+
+. Enter a description that helps you identify the purpose of the profile for *Description*.
+
+. Click *Save*.
++
+This action creates the profile and enables you to configure executors. 
+. Click *Create* to configure an executor for this profile.
++
+.Create a profile executors
+image:images/create-oidc-client-secret-rotation-executor.png[Client Profile Executor]
+
+. Select _secret-rotation_ for *Executor Type*.
+
+. Enter the maximum duration time of each secret, in seconds, for *Secret Expiration*.
+
+. Enter the maximum duration time of each rotated secret, in seconds, for *Rotated Secret Expiration*.
++
+WARNING: Remember that the *Rotated Secret Expiration* value must always be less than *Secret Expiration*.
+. Enter the amount of time, in seconds, after which any update action will update the client for *Remain Expiration Time*.
+
+. Click *Save*.
++
+[NOTE]
+====
+In the example above:
+
+* Each secret is valid for one week.
+* The rotated secret expires after two days.
+* The window for updating dynamic clients starts one day before the secret expires.
+====
++
+. Return to the *Client Policies* tab.
+
+. Click *Policies*.
+
+. Click *Create*.
++
+.Create the Client Secret Rotation Policy
+image:images/create-oidc-client-secret-rotation-policy.png[Client Rotation Policy]
+
+. Enter any name for *Name*.
+
+. Enter a description that helps you identify the purpose of the policy for *Description*.
+
+. Click *Save*.
++
+This action creates the policy and enables you to associate policies with profiles. It also allows you to configure the conditions for policy execution.
++
+. Under Conditions, click *Create*.
++
+.Create the Client Secret Rotation Policy Condition
+image:images/create-oidc-client-secret-rotation-condition.png[Client Rotation Policy Condition]
+
+. To apply the behavior to all confidential clients select _client-access-type_ in the *Condition Type* field
++
+[NOTE]
+====
+To apply to a specific group of clients, another approach would be to select the _client-roles_ type in the *Condition Type* field. In this way, you could create specific roles and assign a custom rotation configuration to each role.
+====
++
+. Add _confidential_ to the field *Client Access Type*.
+
+. Click *Save*.
+
+. Back in the policy setting, under _Client Profiles_, in the *Add client profile* selection menu, select the profile *Weekly Client Secret Rotation Profile* created earlier.
+
+.Client Secret Rotation Policy
+image:images/oidc-client-secret-rotation-policy.png[Client Rotation Policy]
+
+[NOTE]
+====
+To apply the secret rotation behavior to an existing client, follow the following steps: 
+
+.Using the Admin Console
+. Go to some client.
+. Go to tab *_Credentials_*.
+. Click *_Re-generate secret_*.
+====
+
+---
+
+.Using client REST services it can be executed in two ways:
+* Through an update operation on a client
+* Through the regenerate client secret endpoint

server_installation/topics/profiles.adoc

@@ -39,6 +39,11 @@ The features that can be enabled and disabled are:
 |Yes
 |Supported
 
+|client_secret_rotation
+|Enables client secret rotation for confidential clients
+|Yes
+|Preview
+
 |par
 |OAuth 2.0 Pushed Authorization Requests (PAR)
 |Yes