Repository navigation
Enhanced Bootstrapping and Recovering Admin Access #9829
Description
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
--usernameis not specified, the env variableKEYCLOAK_BOOTSTRAP_ADMIN_USERwill be checked, if it is not defined, the user will be prompted to enter a username with a default preset totemp-admin. - If
--passwordis not specified, the environment variableKEYCLOAK_BOOTSTRAP_ADMIN_PASSWORDwill be checked, if it is not defined, the user will be prompted for a password. - If
--no-promptis 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.
--expirationspecifies the number of minutes after which the account expires. If--expirationis not specified, the environment variableKEYCLOAK_BOOTSTRAP_ADMIN_EXPIRATIONwill be checked. Otherwise, the default120(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 theKEYCLOAK_BOOTSTRAP_ADMIN_USER,KEYCLOAK_BOOTSTRAP_ADMIN_PASSWORDandKEYCLOAK_BOOTSTRAP_ADMIN_EXPIRATIONenv vars. Their meaning and functionality is identical to as when used as the dedicated command. --no-promptis implicit, i.e. ifKEYCLOAK_BOOTSTRAP_ADMIN_USERis set butKEYCLOAK_BOOTSTRAP_ADMIN_PASSWORDis 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_IDandKEYCLOAK_BOOTSTRAP_ADMIN_CLIENT_SECRETenv 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
nameSecretandpasswordSecretcan be provided by the user, or the Operator will populate them with defaults. - If the Secret or the Key referenced by
nameSecretdon’t exist, the default as described above is used and is written back to the Secret. - If the Secret or the Key referenced by
passwordSecretdon’t exist, a password is generated and is written back to the Secret. - The content of Secrets referenced by
clientIdSecretandclientSecretmust 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 #8549
### 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
### Follow-up tasks
- [ ] https://github.com/keycloak/keycloak/issues/30008
- [ ] https://github.com/keycloak/keycloak/issues/30010
Activity
21 remaining items
vmuzikar commentedon Aug 21, 2024
Resolving this as all tasks are done now and only follow-ups remain.
Barathwaja commentedon Apr 25, 2025
Hi @vmuzikar , While testing this scenario, I noticed that the
KC_BOOTSTRAP_ADMIN_USERNAMEis being created in the default master realm instead of my custom realm. I don't see anyKEYCLOAK_BOOTSTRAP_ADMIN_REALMorKC_BOOTSTRAP_ADMIN_REALMoptions currently implemented—please correct me if I'm mistaken.shawkins commentedon Apr 27, 2025
@Barathwaja the bootstrap admin will be created in whatever is designated as the master realm, you may then use that account to create other realm level admins.
Barathwaja commentedon Apr 27, 2025
@shawkins - Correct — but in my scenario, I already have a custom realm with non-admin users and only one main admin user. If I accidentally delete that main admin, I should still be able to create a temporary user and recover/recreate admin user with privileges to it under my custom realm.
atul-agg commentedon Apr 29, 2025
@pedroigor @vmuzikar @stianst is **KEYCLOAK_BOOTSTRAP_ADMIN_EXPIRATION ** still available? I don't see it here https://www.keycloak.org/server/all-config
How to delete temporary admin automatically after bootstrapping.
I am creating a permanent user at bootstrap. I don't want temporary user at all. Is there any way to avoid adding it or delete it later if adding it is compulsory.
vmuzikar commentedon Apr 29, 2025
No, it was never really implemented.
This is not possible at the moment. There's a tracker for it though it's unsure when or whether at all will get this implemented at this point.
atul-agg commentedon May 2, 2025
@vmuzikar is it possible to bootstrap without temporary admin? I am including a permanent admin in master realm during startup using config.json file in /keycloak/data/import/ folder.
Keycloak fails to start if I do not include KC_BOOTSTRAP_ADMIN_USERNAME and KC_BOOTSTRAP_ADMIN_PASSWORD in my docker-compose.yml file. Is there any solution for it?
shawkins commentedon May 2, 2025
@atul-agg the bootstrap properties are not required. Feel free to create a new issue or disscussion if you are having a problem.
Barathwaja commentedon May 2, 2025
@shawkins - Just following up—I'd appreciate it if you could review and let me know if there's a way to create temporary users under my custom realm, which is already set as the default.
shawkins commentedon May 2, 2025
No, the original response reflects how the bootstrap admin feature functions. If there are additional questions, please start a new discussion.