Recovering lost Keycloak credentials

This procedure describes how to recover lost Keycloak credentials for UDS Core. It leverages the Admin bootstrap and recovery feature of Keycloak and works only when an external database (like PostgreSQL) is used.

Caution

This procedure requires at least 1.5G of memory allocated to the Keycloak container. You may need to temporarily increase the memory limit before starting the recovery process. If the JAVA_OPTS_KC_HEAP environment variable is used, ensure the -XX:MaxRAM setting corresponds to the container memory limits. More information might be found at Keycloak’s part of the UDS Prerequisites manual.

Caution

If your account has been locked out after the FIPS migration, you may want to move back to non-FIPS mode and follow the Upgrading Identity Config Versions guide. This way you won’t need to recover your administrator credentials.

The procedure involves creating a new user with administrator privileges, logging into that user, recovering the lost credentials and deleting it. First, create a new temporary admin user called temp-admin with a strong password:

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, enter the temp-admin password:

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

The command will exit with no errors. Ensure this line is present in the output:

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

Navigate to https://keycloak.admin.uds.dev/ and log in with the temp-admin user. Once logged in, reset the admin user password by navigating to the Users tab, selecting admin, going to the Credentials tab, and clicking on Reset Password. Once the admin password has been updated, delete the temp-admin user.