Review + adjustments

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

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

@@ -12,39 +12,45 @@ A user account created using one of the methods described below 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]. 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:
+{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 purpose of these options is solely for bootstrapping temporary admin accounts. The accounts are always created in the master realm. For recovering lost admin access, use the dedicated command described in the sections below.
+The username or client ID values can be omitted; see the <<Default values>> section below for more information.
 
-== Bootstrapping an admin user using a dedicated command
+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.
+
+== Dedicated command for bootstrapping an admin user or service account
+
+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.
+
+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, a user is prompted to enter the required information. For more information, see the <<Environment variables>> section 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 or client ID values 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 tmpadmpass"/>
-
-This command creates a temporary admin user with the username `tmpadm` and the password `tmpadmpass`.
+<@kc.bootstrapadmin parameters="user --username tmpadm --password:env PASS_VAR"/>
 
-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" anchor="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).
+This command creates a temporary admin user with the username `tmpadm` and the password retrieved from the environment variable.
 
-== Bootstrapping an admin service account
+=== Create a service account
 
-In automated scenarios, an admin service account can be a more suitable alternative to a temporary admin user.
+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, 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 <<Environment variables>> section below.
+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 <<Default values>> and <<Environment variables>> sections below.
 
 Alternatively, the parameters can be directly specified in the command:
 
@@ -66,6 +72,10 @@ Finally, the retrieved ID can be used to remove the advanced authentication meth
 
 <@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` and `temp-admin-service`, respectively.
+
 == Disable the parameters prompt
 
 To disable the prompt for the parameters, the `--no-prompt` parameter can be used. For example:
@@ -74,11 +84,17 @@ To disable the prompt for the parameters, the `--no-prompt` parameter can be use
 
 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>"/>
+<@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-service, while the client secret is required to be set as an environment variable: