Document admin bootstrapping and recovery

Closes: #30011

Signed-off-by: Peter Zaoral <pzaoral@redhat.com>
Co-authored-by: Alexander Schwartz <aschwart@redhat.com>
Co-authored-by: Václav Muzikář <vaclav@muzikari.cz>
This commit is contained in:
Peter Zaoral 2024-07-30 15:45:56 +02:00 committed by GitHub
parent e62604b1ec
commit 07cfdac862
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 139 additions and 5 deletions

View file

@ -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.

View file

@ -36,3 +36,5 @@ 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
# Remove the following line once KC26 is released
https://www.keycloak.org/server/bootstrap-admin-recovery

View file

@ -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/

View file

@ -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.

View file

@ -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>

View file

@ -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>

View file

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

View file

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