Keycloak credential recovery

When to use this runbook

Use this runbook when:

• You cannot log into the Keycloak admin console at https://keycloak.<admin_domain>/
• Admin credentials are unknown, lost, or were changed without updating records
• Your account is locked out after a FIPS migration or upgrade
• No admin user exists because the previous break-glass admin was deleted after completing an administrative task
• uds zarf connect keycloak no longer shows the first-run “Create administrative user” form

Overview

This is typically caused by one of the following:

1. Admin password lost or forgotten: the original admin password was not recorded or has been misplaced
2. Credentials rotated without updating records: a scheduled or manual rotation changed the password but the new value was not stored
3. Account locked after FIPS migration or upgrade: FIPS mode can invalidate existing credential hashes, locking out the admin account
4. Break-glass admin deleted: the prior admin was intentionally removed after completing an administrative task (see Manage Keycloak admin access) and a new one must be bootstrapped

This runbook uses the Keycloak Admin bootstrap and recovery feature to create a temporary admin user, then reset the original admin credentials.

Pre-checks

1. Try logging into the Keycloak admin console

   Navigate to https://keycloak.<admin_domain>/ and attempt to log in with the expected admin credentials. If authentication fails, proceed with the recovery steps below.

2. Verify Keycloak pods are healthy

   uds zarf tools kubectl get pods -n keycloak

   What to look for: All Keycloak pods should be in Running state with all containers ready. If pods are in CrashLoopBackOff or OOMKilled, address pod health before attempting credential recovery.

3. Confirm the Keycloak container has at least 1.5G of memory allocated

   Danger

   The bootstrap-admin recovery command requires at least 1.5G of memory. You may need to temporarily increase the memory limit before starting. If you use the JAVA_OPTS_KC_HEAP environment variable, ensure the -XX:MaxRAM setting corresponds to the container memory limits.

Procedure

1. Create a temporary admin user

   Exec into the Keycloak pod and run the bootstrap-admin command:

   uds zarf tools kubectl exec -it keycloak-0 -n keycloak -- /opt/keycloak/bin/kc.sh bootstrap-admin user --verbose --optimized --http-management-port=9001

   When prompted, accept the default username and enter a strong password:

   Enter username [temp-admin]: <enter>
   Enter password: <temp-admin password>
   Enter password again: <temp-admin password>

   The command exits with no errors. Confirm this line is present in the output:

   <timestamp> INFO  [org.keycloak.services] (main) KC-SERVICES0077: Created temporary admin user with username temp-admin

2. Log in with the temporary admin user

   Navigate to https://keycloak.<admin_domain>/ and log in with the temp-admin user and the password you set in the previous step.

3. Restore admin access

   Use whichever case applies:

   • Reset the password on an existing admin user: Navigate to the Users tab, select the admin user, go to the Credentials tab, and click Reset Password. Set a new password for the account.
   • Create a new admin user (for example, the previous break-glass admin was deleted): Navigate to the Users tab, click Add user, and create an account. Open the Role mapping tab, click Assign role, Realm roles, and check the box for the admin role then Assign.

4. Delete the temporary admin user

   After confirming the admin password has been updated, navigate back to the Users tab and delete the temp-admin user.

Verification

After applying a fix, confirm the issue is resolved:

1. Navigate to https://keycloak.<admin_domain>/
2. Log in with the recovered admin credentials

Success indicators:

• Admin console loads successfully after authentication
• The temp-admin user no longer appears in the Users tab

Additional help

If this runbook doesn’t resolve your issue:

1. Collect relevant details from the steps above
2. Check UDS Core GitHub Issues for known issues
3. Open a new issue with your relevant details attached

Related documentation

• Identity & Authorization - how Keycloak fits into UDS Core’s identity architecture
• Keycloak High Availability - HA configuration for Keycloak