From 1a16bac6fa551d5c240b75d2c0a40c7be87aa0e4 Mon Sep 17 00:00:00 2001 From: Peter Zaoral Date: Wed, 3 Jul 2024 15:44:47 +0200 Subject: [PATCH] Document admin bootstrapping and recovery Closes: #30011 Signed-off-by: Peter Zaoral --- .../topics/changes/changes-26_0_0.adoc | 6 +- .../server/bootstrap-admin-recovery.adoc | 77 +++++++++++++++++++ docs/guides/server/configuration.adoc | 1 + docs/guides/server/pinned-guides | 1 + docs/guides/templates/kc.adoc | 16 +++- 5 files changed, 98 insertions(+), 3 deletions(-) create mode 100644 docs/guides/server/bootstrap-admin-recovery.adoc diff --git a/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc b/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc index 3684e6b6c480..64ce09fa7023 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc +++ b/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`. \ No newline at end of file +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. diff --git a/docs/guides/server/bootstrap-admin-recovery.adoc b/docs/guides/server/bootstrap-admin-recovery.adoc new file mode 100644 index 000000000000..3600551f1596 --- /dev/null +++ b/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 <> 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 <> 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 --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= --password:env="/> + +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= --client-secret:env="/> + + diff --git a/docs/guides/server/configuration.adoc b/docs/guides/server/configuration.adoc index 7b59f5122af2..e4cf3c451733 100644 --- a/docs/guides/server/configuration.adoc +++ b/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=__` for the initial admin username and `KC_BOOTSTRAP_ADMIN_PASSWORD=__` for the initial admin password. diff --git a/docs/guides/server/pinned-guides b/docs/guides/server/pinned-guides index cd63457ab483..b5885fa707c9 100644 --- a/docs/guides/server/pinned-guides +++ b/docs/guides/server/pinned-guides @@ -1,5 +1,6 @@ configuration configuration-production +bootstrap-admin-recovery containers enabletls hostname diff --git a/docs/guides/templates/kc.adoc b/docs/guides/templates/kc.adoc index 7cb41aa62cce..826dcd1571cd 100644 --- a/docs/guides/templates/kc.adoc +++ b/docs/guides/templates/kc.adoc @@ -19,6 +19,13 @@ bin/kc.[sh|bat] start-dev ${parameters} ---- +<#macro admin parameters> +[source,bash] +---- +bin/kcadm.[sh|bat] ${parameters} +---- + + <#macro export parameters> [source,bash] ---- @@ -31,4 +38,11 @@ bin/kc.[sh|bat] export ${parameters} ---- bin/kc.[sh|bat] import ${parameters} ---- - \ No newline at end of file + + +<#macro bootstrapadmin parameters> +[source,bash] +---- +bin/kc.[sh|bat] bootstrap-admin ${parameters} +---- +