diff --git a/docs/documentation/release_notes/topics/26_0_0.adoc b/docs/documentation/release_notes/topics/26_0_0.adoc index 205faef72c63..1c3180e63fc0 100644 --- a/docs/documentation/release_notes/topics/26_0_0.adoc +++ b/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. diff --git a/docs/documentation/topics/templates/document-attributes.adoc b/docs/documentation/topics/templates/document-attributes.adoc index 6bc252fbb001..b5ebff5c5e05 100644 --- a/docs/documentation/topics/templates/document-attributes.adoc +++ b/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/ diff --git a/docs/guides/operator/advanced-configuration.adoc b/docs/guides/operator/advanced-configuration.adoc index 46218a3b7789..a5bd69f37e5e 100644 --- a/docs/guides/operator/advanced-configuration.adoc +++ b/docs/guides/operator/advanced-configuration.adoc @@ -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. + diff --git a/docs/guides/server/bootstrap-admin-recovery.adoc b/docs/guides/server/bootstrap-admin-recovery.adoc index 62f3275cfc58..2ad99c677b53 100644 --- a/docs/guides/server/bootstrap-admin-recovery.adoc +++ b/docs/guides/server/bootstrap-admin-recovery.adoc @@ -8,7 +8,7 @@ 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. 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. +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 @@ -24,7 +24,7 @@ The purpose of these options is solely for bootstrapping temporary admin account == 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 the server needs 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. +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). @@ -34,7 +34,7 @@ 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 or client ID values can be omitted to use the default values. For more information, see the <> and <> sections below. +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 <> and <> sections below. Alternatively, the parameters can be directly specified in the command: @@ -50,7 +50,7 @@ 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 username or client ID values can be omitted to use the default values. For more information, see the <> and <> sections below. +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 <> and <> sections below. Alternatively, the parameters can be directly specified in the command: @@ -58,10 +58,6 @@ Alternatively, the parameters can be directly specified in the command: This command creates a temporary admin service account with the client ID `tmpclient` and the secret retrieved from the environment variable. -== Admin bootstrapping using the {project_name} operator - -For more information on how to bootstrap a temporary admin user or service account using the operator, see the <@links.operator id="advanced-configuration" anchor="operator-admin-bootstrap"/>. - == 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: @@ -78,7 +74,7 @@ Finally, the retrieved ID can be used to remove the advanced authentication meth == Default values -For both the startup and dedicated command scenarios, the username and client ID are optional and default to `temp-admin` and `temp-admin-service`, respectively. +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 @@ -100,8 +96,8 @@ For the `bootstrap-admin user` command, both username and password can be option <@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: +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= --client-secret:env="/> +<@kc.bootstrapadmin parameters="service --client-id:env --client-secret:env "/>