Bootstrapping a temporary admin account

Bootstrapping supports both an admin user account and admin service account. This proposal is describing bootstrapping that is meant as a replacement for the current KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD env vars. It does not replace the admin creation using Welcome Page.

Temporary admin user and admin service account specifications

• Meant to be only a temporary account that is used for creating permanent and more secure admin access.
• By default expires (is deleted) after 2 hours.

  * This is configurable by the user.
  

• In case of the user account, clear warning is visible in the Admin Console when logged in as this user.

  * A bar at the top of all Admin Console pages.
  

• The user/client is cleary marked as temporary in the lists in Admin Console.
• A warning is emitted in the log any time such a user logs in.
• The warnings include a note when the account will be deleted.

In automated scenarios, an admin service account is a more suitable alternative to an admin user.

Bootstrapping an admin user account

Bootstrapping an admin user using a dedicated command

Add a new command: kc.sh|bat bootstrap-admin user [--username=value] [--password=value] [--no-prompt] [--expiration=value].

• The command works regardless if Keycloak was ever started (and master realm exists), or not.
• If --username is not specified, the env variable KEYCLOAK_BOOTSTRAP_ADMIN_USER will be checked, if it is not defined, the user will be prompted to enter a username with a default preset to temp-admin.
• If --password is not specified, the environment variable KEYCLOAK_BOOTSTRAP_ADMIN_PASSWORD will be checked, if it is not defined, the user will be prompted for a password.
• If --no-prompt is specified, then prompting will not be used. If a value would have required prompting, an error will be shown.
• If the account with the specified username exists an error will be shown.
• -expiration specifies the number of minutes after which the account expires. If -expiration is not specified, the environment variable KEYCLOAK_BOOTSTRAP_ADMIN_EXPIRATION will be checked. Otherwise, the default 120 (2 hours) will be used.

Bootstrapping an admin user at server startup

• Usable only if Keycloak was not started before, i.e. the master realm doesn't not exist.
• When the server is starting (kc.sh|bat start|start-dev) and the condition specified above is met, it will check the KEYCLOAK_BOOTSTRAP_ADMIN_USER, KEYCLOAK_BOOTSTRAP_ADMIN_PASSWORD and KEYCLOAK_BOOTSTRAP_ADMIN_EXPIRATION env vars. Their meaning and functionality is identical to as when used as the dedicated command.
• --no-prompt is implicit, i.e. if KEYCLOAK_BOOTSTRAP_ADMIN_USER is set but KEYCLOAK_BOOTSTRAP_ADMIN_PASSWORD is not, an error will be shown.

Bootstrapping an admin service account

• Identical to bootstraping the admin user as described above with the following exceptions:

  * Instead of "user", "client-id" is used in param and env var names.
  * Instead of "password", "secret" is used in param and env var names.
  

• Dedicated command: kc.sh|bat bootstrap-admin service [--client-id=value] [--secret=value] [--no-prompt] [--expiration].
• Bootstrapping at server startup is supported too using the KEYCLOAK_BOOTSTRAP_ADMIN_CLIENT_ID and KEYCLOAK_BOOTSTRAP_ADMIN_CLIENT_SECRET env vars.

Based on the provided arguments, a Client is created in the master Realm with the following specificationss:

• It has all flows disabled.
• The Client requires authentication.
• Service account is enabled.
• The service account has the admin Realm Role assigned.

Bootstrapping using the Operator

There will be a dedicated field in the Keycloak CR for bootstrapping the admin user account and admin service account. The implementation will leverage the startup env vars, so it will be effective only for the initial bootstrapping of Keycloak.

```
kind: Keycloak
spec:
bootstrap-admin:

expiration: 260
user:
  nameSecret: 
    name: keycloak-admin-secret
    key: username
  passwordSecret:
    name: keycloak-admin-secret
    key: password
service:
  clientIdSecret: 
    name: keycloak-admin-secret
    key: client-id
  clientSecret:
    name: keycloak-admin-secret
    key: secret

```

• The content of Secrets referenced by nameSecret and passwordSecret can be provided by the user, or the Operator will populate them with defaults.
• If the Secret or the Key referenced by nameSecret don’t exist, the default as described above is used and is written back to the Secret.
• If the Secret or the Key referenced by passwordSecret don’t exist, a password is generated and is written back to the Secret.
• The content of Secrets referenced by clientIdSecret and clientSecret must be provided by the user.

Recovering the admin access

It is not possible to recover an admin account without already having admin access. It is possible though to create a new admin account using the dedicated command. In case of Operator/container deployments, we will document ssh-ing to the container is necessary.

Realms with increased security (OTP requirement, passwordles, ...) will have to use the admin service account to recover access to the master realm.

—

Originally discussed in https://github.com/keycloak/keycloak/discussions/8549

```[tasklist]

1. 1. 1. Tasks

• [ ] https://github.com/keycloak/keycloak/issues/30003
• [ ] https://github.com/keycloak/keycloak/issues/29324
• [ ] https://github.com/keycloak/keycloak/issues/30002
• [ ] https://github.com/keycloak/keycloak/issues/30004
• [ ] https://github.com/keycloak/keycloak/issues/30009
• [ ] https://github.com/keycloak/keycloak/issues/30011
• [ ] https://github.com/keycloak/keycloak/issues/29325
• [ ] https://github.com/keycloak/keycloak/issues/29355
• [ ] https://github.com/keycloak/keycloak/issues/30540
• [ ] https://github.com/keycloak/keycloak/issues/30658
• [ ] https://github.com/keycloak/keycloak/issues/31160
• [ ] https://github.com/keycloak/keycloak/issues/31491
  ```

```[tasklist]

1. 1. 1. Follow-up tasks

• [ ] https://github.com/keycloak/keycloak/issues/30008
• [ ] https://github.com/keycloak/keycloak/issues/30010
  ```