Document admin bootstrapping and recovery

Closes: keycloak#30011

Signed-off-by: Peter Zaoral <[email protected]>
Co-authored-by: Alexander Schwartz <[email protected]>
Co-authored-by: Václav Muzikář <[email protected]>

docs/documentation/release_notes/topics/26_0_0.adoc

@@ -74,3 +74,11 @@ The new `footer.ftl` template provides a `content` macro that is rendered at the
 The `keycloak` login theme has been deprecated in favour of the new `keycloak.v2` and will be removed in a future version.
 While it remains the default for the new realms for compatibility reasons, it is strongly recommended to switch all the
 realm themes to `keycloak.v2`.
+
+= Admin Bootstrapping and Recovery
+
+In the past, regaining access to a {project_name} instance when all admin users were locked out was a challenging and complex process. Recognizing these challenges and aiming to significantly enhance the user experience, {project_name} now offers several straightforward methods to bootstrap a temporary admin account and recover lost admin access.
+
+It is now possible to run the `start` or `start-dev` commands with specific options to create a temporary admin account. Additionally, a new dedicated command has been introduced, which allows users to regain admin access without hassle.
+
+For detailed instructions and more information on this topic, refer to the link:{bootstrapadminrecovery_link}[{bootstrapadminrecovery_name}] guide.

docs/documentation/tests/src/test/resources/ignored-links

@@ -35,4 +35,6 @@ https://developer.paypal.com/developer/applications
 https://account.live.com/developers/applications/create
 https://developer.twitter.com/apps/
 https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#rolling-update
-https://stackapps.com/apps/oauth/register
+https://stackapps.com/apps/oauth/register
+# Remove the following line once KC26 is released
+https://www.keycloak.org/server/bootstrap-admin-recovery

docs/documentation/topics/templates/document-attributes.adoc

@@ -61,6 +61,8 @@
 :adminguide_clearcache_link: {adminguide_link}#_clear-cache
 :apidocs_name: API Documentation
 :apidocs_link: https://www.keycloak.org/docs/{project_version}/api_documentation/
+:bootstrapadminrecovery_name: Admin Bootstrap and Recovery
+:bootstrapadminrecovery_link: https://www.keycloak.org/server/bootstrap-admin-recovery
 :developerguide_name: Server Developer Guide
 :developerguide_name_short: Server Developer
 :developerguide_link: {project_doc_base_url}/server_development/

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

@@ -92,6 +92,8 @@ To disable this behavior, use the SPI option `spi-single-use-object-infinispan-p
 The SPI behavior of `SingleUseObjectProvider` has changed that for revoked tokens only the methods `put` and `contains` must be used.
 This is enforced by default, and can be disabled using the SPI option `spi-single-use-object-infinispan-persist-revoked-tokens`.
 
-= 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/server/bootstrap-admin-recovery[Bootstrap admin and recovery] guide.

docs/guides/operator/advanced-configuration.adoc

@@ -206,7 +206,7 @@ For more details, see <@links.server id="containers" />.
 
 === Scheduling
 
-You may control several aspects of the server Pod scheduling via the Keycloak CR. The scheduling stanza exposes optional standard Kubernetes affinity, tolerations, topology spread constraints, and the priority class name to fine tune the scheduling and placement of your server Pods. 
+You may control several aspects of the server Pod scheduling via the Keycloak CR. The scheduling stanza exposes optional standard Kubernetes affinity, tolerations, topology spread constraints, and the priority class name to fine tune the scheduling and placement of your server Pods.
 
 An example utilizing all scheduling fields:
 
@@ -314,4 +314,6 @@ When you create a new instance the Keycloak CR spec.bootstrapAdmin stanza may be
 
 If a master realm has already been created for you cluster, then the spec.boostrapAdmin is effectively ignored. If you need to create a recovery admin account, then you'll need to run the CLI command against a Pod directly.
 
+For more information on how to bootstrap a temporary admin user or service account and recover lost admin access, refer to the <@links.server id="bootstrap-admin-recovery"/> guide.
+
 </@tmpl.guide>

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

@@ -0,0 +1,103 @@
+<#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.">
+
+== A temporary admin account
+
+A user or service admin 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. After that, the account needs to be removed manually. 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 a temporary admin account at {project_name} startup
+
+{project_name} `start` and `start-dev` commands support options for bootstrapping both temporary admin users and admin service accounts. These options are standard configuration options, so they can be specified in any of the https://www.keycloak.org/server/configuration#_configuring_sources_for_keycloak[configuration sources] such as environment variables or CLI parameters. For instance, the following examples demonstrate how to use the `start` and `start-dev` commands with CLI parameters to bootstrap a temporary admin user and an admin service account, respectively:
+
+<@kc.start parameters="--bootstrap-admin-username tmpadm --bootstrap-admin-password pass"/>
+
+<@kc.startdev parameters="--bootstrap-admin-client-id tmpadm --bootstrap-admin-client-secret secret"/>
+
+The username or client ID values can be omitted; see the <<Default values>> section below for more information.
+
+The purpose of these options is solely for bootstrapping temporary admin accounts. These accounts will be created only during the initial start of the {project_name} server when the master realm doesn't exist yet. The accounts are always created in the master realm. For recovering lost admin access, use the dedicated command described in the sections below.
+
+== Bootstrapping an admin user or service account using the dedicated command
+
+The `bootstrap-admin` command can be executed even before the first-ever start of {project_name}. Bear in mind that all the {project_name} nodes need to be stopped prior to using this command. Its execution will trigger the creation of the initial master realm, and as a result, the startup options to bootstrap the admin user and service account will be ignored later when the server is started for the first time.
+
+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).
+
+=== Create an admin user
+
+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, the user is prompted to enter the required information. The username value can be omitted to use the default values. For more information, see the <<Default values>> and <<Environment variables>> sections below.
+
+Alternatively, the parameters can be directly specified in the command:
+
+<@kc.bootstrapadmin parameters="user --username tmpadm --password:env PASS_VAR"/>
+
+This command creates a temporary admin user with the username `tmpadm` and the password retrieved from the environment variable.
+
+=== Create a service account
+
+In automated scenarios, a temporary 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, if no corresponding environment variables or additional parameters are set, the user will be prompted to enter the required information. The client ID value can be omitted to use the default values. For more information, see the <<Default values>> and <<Environment variables>> sections 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}"/>
+
+== Default values
+
+For both the startup and dedicated command scenarios, the username and client ID are optional and default to `temp-admin` for both the user and service account, respectively.
+
+== 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.
+
+The `--no-prompt` parameter can be useful if the username or client ID should be omitted. For example:
+
+<@kc.bootstrapadmin parameters="user --password:env PASS_VAR --no-prompt"/>
+
+This creates a temporary admin user with the default username without prompting for confirmation. For more information, see the <<Default values>> section above.
+
+== 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`, 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/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>