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

@@ -76,6 +76,8 @@ If you are migrating from previous versions where any of the following settings
 
 For more details, see link:{adminguide_link}#_ldap_connection_pool[Configuring the connection pool].
 
-= Admin Bootstrapping
+= Admin Bootstrapping and Recovery
 
-The environment variables `KEYCLOAK_ADMIN` and `KEYCLOAK_ADMIN_PASSWORD` have been deprecated. You should use `KC_BOOTSTRAP_ADMIN_USERNAME` and `KC_BOOTSTRAP_ADMIN_PASSWORD` instead. These are also general options, so they may be specified via the cli or other config sources, for example `--bootstrap-admin-username=admin`.
+It used to be difficult to regain access to a {project_name} instance when all admin users were locked out. The process required multiple advanced steps, including direct database access and manual changes. In an effort to improve the user experience, {project_name} now provides multiple ways to bootstrap a new admin account, which can be used to recover from such situations.
+
+Consequently, the environment variables `KEYCLOAK_ADMIN` and `KEYCLOAK_ADMIN_PASSWORD` have been deprecated. You should use `KC_BOOTSTRAP_ADMIN_USERNAME` and `KC_BOOTSTRAP_ADMIN_PASSWORD` instead. These are also general options, so they may be specified via the cli or other config sources, for example `--bootstrap-admin-username=admin`. For more information, see the new https://www.keycloak.org/high-availability/bootstap-admin-recovery[Bootstrap admin and recovery] guide.

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

@@ -0,0 +1,77 @@
+<#import "/templates/guide.adoc" as tmpl>
+<#import "/templates/kc.adoc" as kc>
+<#import "/templates/links.adoc" as links>
+
+<@tmpl.guide
+title="Admin bootstrap and recovery"
+summary="Learn how to bootstrap and recover admin account.">
+
+== Creating a temporary admin account
+
+A user account created using one of the methods described below is *temporary*. This means the account should exist only for the duration 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, and 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"/>
+
+If no other parameters are specified and/or no corresponding environment variables are set, a user is prompted to enter the required information. For more information, see the <<Environment variables>> section below.
+
+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`.
+
+NOTE: The command can be executed even before the first-ever start of {project_name}. However, this will leave the {project_name} server in a state where the temporary admin account is the only account that exists in the master realm and the default admin will not be created. The initial admin creation happens only when the master realm is created. If the intention is to recover lost admin access, the default admin must exist in the master realm prior to executing the command (see <@links.server id="configuration#create-initial-admin"/>). Additionally, it is strongly recommended to use the dedicated command with the same options that the {project_name} server is started with (e.g., `db` options).
+
+== Bootstrapping an admin service account
+
+In automated scenarios, an admin service account can be a more suitable alternative to a temporary admin user.
+
+To create a temporary admin service account, execute the following command:
+
+<@kc.bootstrapadmin parameters="service"/>
+
+Similarly, the command can be executed regardless of the `master` realm’s existence. 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 or additional parameters are set, the user will be prompted to enter the required information. For more information, see the <<Environment variables>> section below.
+
+Alternatively, the parameters can be directly specified in the command:
+
+<@kc.bootstrapadmin parameters="service --client-id tmpclient --client-secret:env=SECRET_VAR"/>
+
+This command creates a temporary admin service account with the client ID `tmpclient` and the secret retrieved from the environment variable.
+
+== Regaining access to the realm with an increased security
+
+Passwordless, OTP, or other advanced authentication methods can be enforced for a realm with lost admin access. In such a case, the admin service account needs to be created to recover lost admin access to the realm. After the service account is created, authentication against the {project_name} instance is required to perform all necessary operations:
+
+<@kc.admin parameters="config credentials --server http://localhost:8080 --realm master --client <service_account_client_name> --secret <service_account_secret>"/>
+
+Next, retrieve the `credentialId`. For this example, the OTP credential is the relevant one. Use the following command to get an array of `CredentialRepresentation` objects and find the one with `type` set to `otp`:
+
+<@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):
+
+<@kc.admin parameters="delete users/{userId}/credentials/{credentialId} -r {realm}"/>
+
+== Disable the parameters prompt
+
+To disable the prompt for the parameters, the `--no-prompt` parameter can be used. For example:
+
+<@kc.bootstrapadmin parameters="user --username tmpadm --no-prompt"/>
+
+If no corresponding environment variable is set, the command will fail with an error message indicating that the required password parameter is missing.
+
+== Environment variables
+
+For the `bootstrap-admin user` command, both username and password can be optionally set as environment variables:
+
+<@kc.bootstrapadmin parameters="user --username:env=<YourUsernameEnv> --password:env=<YourPassEnv>"/>
+
+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>"/>
+
+</@tmpl.guide>

docs/guides/server/configuration.adoc

@@ -193,6 +193,7 @@ Before deploying {project_name} in a production environment, make sure to follow
 
 By default, example configuration options for the production mode are commented out in the default `conf/keycloak.conf` file. These options give you an idea about the main configuration to consider when running {project_name} in production.
 
+[#create-initial-admin]
 == Creating the initial admin user
 You can create the initial admin user by using the web frontend, which you access using a local connection (localhost). You can instead create this user by using environment variables. Set `KC_BOOTSTRAP_ADMIN_USERNAME=_<username>_` for the initial admin username and `KC_BOOTSTRAP_ADMIN_PASSWORD=_<password>_` for the initial admin password.
 

docs/guides/server/pinned-guides

@@ -1,5 +1,6 @@
 configuration
 configuration-production
+bootstrap-admin-recovery
 containers
 enabletls
 hostname

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]
 ----
@@ -31,4 +38,11 @@ bin/kc.[sh|bat] export ${parameters}
 ----
 bin/kc.[sh|bat] import ${parameters}
 ----
-</#macro>
+</#macro>
+
+<#macro bootstrapadmin parameters>
+[source,bash]
+----
+bin/kc.[sh|bat] bootstrap-admin ${parameters}
+----
+</#macro>