Document admin bootstrapping and recovery

Closes: keycloak#30011

Signed-off-by: Peter Zaoral <[email protected]>

docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc

@@ -37,3 +37,7 @@ The following items have been deprecated for removal in upcoming {project_name}
 = Consistent usage of UTF-8 charset for URL encoding
 
 `org.keycloak.common.util.Encode` now always uses the `UTF-8` charset for URL encoding instead relying implicitly on the `file.encoding` system property.
+
+= Admin bootstrap and recovery
+
+It used to be difficult to regain access to a {project_name} instance, where all admin users have been locked out. The process required multiple user-advanced steps, including direct database access and manual changes. In the continuous effort to improve the user experience, {project_name} now provides multiple ways to bootstrap a new admin account, which can be later used to recover from such a situation. For more information, see a new https://www.keycloak.org/high-availability/bootstap-admin-recovery[Bootstrap admin and recovery] guide.

docs/guides/server/bootstrap-admin-recovery.adoc

@@ -4,25 +4,27 @@
 
 <@tmpl.guide
 title="Admin bootstrap and recovery"
-summary="Learn how to bootstrap and recover admin account." >
+summary="Learn how to bootstrap and recover admin account.">
 
-== A solution for a disaster scenario
+== Creating a temporary admin account
 
-It used to be difficult to regain access to a {project_name} instance, where all admin users have been locked out. The process required multiple user-advanced steps, including direct database access and manual changes. In the continuous effort to improve the user experience, {project_name} now provides multiple ways to bootstrap a new admin account, which can be later used to recover from such a situation.
+A user account created by one of the methods described below is *temporary*. This means that such an account should exist only for the period necessary to perform operations needed to gain permanent and more secure admin access. Various UI/UX elements such as the Administration Console warning banner, labels or log messages will indicate to a {project_name} administrator that the account is temporary.
 
 == Bootstrapping an admin user using a dedicated command
 
 To create a temporary admin user, execute the following command:
 
 <@kc.bootstrapadmin parameters="user"/>
 
-This command can be executed even before the {project_name} first ever start. In other words, it does not matter, whether the `master` realm already exists or not. If no other parameters are specified and/or no corresponding environment variables are set, a user is prompted to enter required information. For more information, see the <<Environment variables>> section bellow.
+If no other parameters are specified and/or no corresponding environment variables are set, a user is prompted to enter required information. For more information, see the <<Environment variables>> section bellow.
 
 Alternatively, the parameters can be directly specified in the command:
 
 <@kc.bootstrapadmin parameters="user --username tmpadm --password tmpadmpass"/>
 
-This command creates a temporary admin user with the username `tmpadm` and the password `tmpadmpass`. The user is valid for 60 minutes.
+This command creates a temporary admin user with the username `tmpadm` and the password `tmpadmpass`.
+
+NOTE: The command can be executed even before the {project_name} first ever start. However, it leaves the {project_name} server in a state, where the temporary admin account will be the only account that exists in the master realm - the default admin will not be created. If the intention is to recover a lost admin access, the default admin should exist within the master realm. Also, it is strongly recommended to use the dedicated command with the very sane options that the {project_name} server is started with (e.g. `db` options).
 
 == Bootstrapping an admin service account
 
@@ -32,7 +34,7 @@ Again, to create a temporary admin service account, execute the following comman
 
 <@kc.bootstrapadmin parameters="service"/>
 
-The same rule applies here - the command can be executed regardless of the `master` realm existence. If no corresponding environment variables nor the additional parameter are set, a user will be prompted to enter the required information. For more information, see the <<Environment variables>> section bellow.
+Similarly, the command can be executed regardless of the `master` realm existence. Also, given the client nature of the admin service account, the default admin can be created even after the command execution. If no corresponding environment variables nor the additional parameter are set, a user will be prompted to enter the required information. For more information, see the <<Environment variables>> section bellow.
 
 Alternatively, you can specify the parameters directly in the command:
 
@@ -42,32 +44,17 @@ This command creates a temporary admin service account with the client ID `tmpcl
 
 == Regaining access to the realm with an increased security
 
-Passwordless, OTP or other advanced authentication methods can be enforced for the realm with lost admin access. In such case, the admin service account needs to be created. After the service account is created, authentication against the {project_name} instance is required to perform all the necessary operations:
+Passwordless, OTP or other advanced authentication methods can be enforced for the realm with lost admin access. In such case, the admin service account needs to be created to recover lost admin access to such realm. After the service account is created, authentication against the {project_name} instance is required to perform all the necessary operations:
 
-[source]
-----
-POST realms/{realm}/protocol/openid-connect/token \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "client_id=<service_account_id>" \
-  -d "client_secret=<service_account_secret>" \
-  -d "grant_type=client_credentials"
-----
+<@kc.admin parameters="config credentials --server http://localhost:8080 --realm master --client <service_account_client_name> --secret <service_account_secret>"/>
 
 Then you need to retrieve `credentialId`. In our case it is OTP credential. Following command will return an array of `CredentialRepresentation` objects and the one with the `type` set to `otp` is the one you are looking for:
 
-[source]
-----
-GET admin/realms/{realm}/users/{userId}/credentials
-----
+<@kc.admin parameters="get users/{userId}/credentials -r {realm}"/>
 
 Finally, the retrieved ID can be used to remove the advanced authentication method (in our case OTP):
 
-[source]
-----
-DELETE admin/realms/{realm}/users/{userId}/credentials/{credentialId}
-----
-
-To perform the above operations, `kcadm.sh` utility can be used as well as any HTTP client, like `curl`.
+<@kc.admin parameters="delete users/{userId}/credentials/{credentialId} -r {realm}"/>
 
 == Disable the parameters prompt
 
@@ -83,7 +70,7 @@ For the `bootstrap-admin user` command, both username and password can be option
 
 <@kc.bootstrapadmin parameters="user --username:env=<YourUsernameEnv> --password:env=<YourPassEnv>"/>
 
-Regarding the `bootstrap-admin service` command, for the client ID it is optional, while for the client secret it is required to be set as an environment variable:
+For the `bootstrap-admin service` command, the client ID is optional and defaults to temp-admin-service, while the client secret is required to be set as an environment variable:
 
 <@kc.bootstrapadmin parameters="service --client-id:env=<YourClientIdEnv> --client-secret:env=<YourSecretEnv>"/>
 

docs/guides/templates/kc.adoc

@@ -19,6 +19,13 @@ bin/kc.[sh|bat] start-dev ${parameters}
 ----
 </#macro>
 
+<#macro admin parameters>
+[source,bash]
+----
+bin/kcadm.[sh|bat] ${parameters}
+----
+</#macro>
+
 <#macro export parameters>
 [source,bash]
 ----