feat: recovering lost Keycloak credentials

docs/reference/configuration/Single Sign-On/overview.md

@@ -51,7 +51,9 @@ All groups are under the Uds Core parent group. Frequently a group will be refer
 1. [Authservice Protection](/reference/configuration/single-sign-on/auth-service/)
 2. [Device Flow Clients](/reference/configuration/single-sign-on/device-flow/)
 3. [Group Based Authorization](/reference/configuration/single-sign-on/group-based-auth/)
-4. [Service Account Roles Clients](/reference/configuration/single-sign-on/service-account/)
-5. [Client Attribute Validation](/reference/configuration/single-sign-on/sso-client-validation/)
-6. [Secret Templating](/reference/configuration/single-sign-on/sso-templating/)
-7. [Trusted Certificate Authority](/reference/configuration/single-sign-on/trusted-ca/)
+4. [Keycloak Session Timeout](/reference/configuration/single-sign-on/keycloak-session-timeouts/)
+5. [Recovering lost Keycloak credentials](/reference/configuration/single-sign-on/recoving-lost-credentials/)
+6. [Service Account Roles Clients](/reference/configuration/single-sign-on/service-account/)
+7. [Client Attribute Validation](/reference/configuration/single-sign-on/sso-client-validation/)
+8. [Secret Templating](/reference/configuration/single-sign-on/sso-templating/)
+9. [Trusted Certificate Authority](/reference/configuration/single-sign-on/trusted-ca/)

docs/reference/configuration/Single Sign-On/recoving-lost-credentials.md

@@ -0,0 +1,31 @@
+---
+title: Recovering lost Keycloak credentials
+---
+
+This procedure describes how to recover lost Keycloak credentials for UDS Core. It leverages the [Admin bootstrap and recovery](https://www.keycloak.org/server/bootstrap-admin-recovery) feature of Keycloak.
+
+:::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](/reference/uds-core/prerequisites/).
+:::
+
+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:
+
+```bash
+uds zarf tools kubectl exec -it keycloak-0 -n keycloak -- /opt/keycloak/bin/kc.sh bootstrap-admin user
+```
+
+When prompted, enter the `temp-admin` password:
+
+```bash
+Enter username [temp-admin]: <enter>
+Enter password: <temp-admin password>
+Enter password again: <temp-admin password>
+```
+
+The command will exit with an error indicating that it can't bootstrap the Keycloak server (this is normal as there's already a Keycloak server running in this container). Ensure this line is present in the output:
+
+```bash
+<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.