From 4f47c6e66396f099aa240643de797a26ddb16b6d Mon Sep 17 00:00:00 2001 From: Peter Zaoral Date: Tue, 9 Jul 2024 14:05:57 +0200 Subject: [PATCH] Document admin bootstrapping and recovery Closes: #30011 Signed-off-by: Peter Zaoral --- .../topics/changes/changes-26_0_0.adoc | 4 ++ .../server/bootstrap-admin-recovery.adoc | 39 +++++++------------ docs/guides/templates/kc.adoc | 7 ++++ 3 files changed, 24 insertions(+), 26 deletions(-) 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 ebe3d28e32a3..d047d3bc0e9a 100644 --- a/docs/documentation/upgrading/topics/changes/changes-26_0_0.adoc +++ b/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. diff --git a/docs/guides/server/bootstrap-admin-recovery.adoc b/docs/guides/server/bootstrap-admin-recovery.adoc index 7a1483e9cc57..21642277d6a1 100644 --- a/docs/guides/server/bootstrap-admin-recovery.adoc +++ b/docs/guides/server/bootstrap-admin-recovery.adoc @@ -4,11 +4,11 @@ <@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 @@ -16,13 +16,15 @@ 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 <> 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 <> 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 has to exist in the master realm prior to the command execution. Also, it is strongly recommended to use the dedicated command with the very same 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 <> section bellow. +Similarly, the command can be executed regardless of the `master` realm 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 nor the additional parameter are set, a user will be prompted to enter the required information. For more information, see the <> 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=" \ - -d "client_secret=" \ - -d "grant_type=client_credentials" ----- +<@kc.admin parameters="config credentials --server http://localhost:8080 --realm master --client --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= --password:env="/> -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= --client-secret:env="/> diff --git a/docs/guides/templates/kc.adoc b/docs/guides/templates/kc.adoc index 9429f3112384..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] ----