diff --git a/docs/reference/configuration/Single Sign-On/overview.md b/docs/reference/configuration/Single Sign-On/overview.md index 9aee6c12a8..ae864c9524 100644 --- a/docs/reference/configuration/Single Sign-On/overview.md +++ b/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/) \ No newline at end of file +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/) diff --git a/docs/reference/configuration/Single Sign-On/recoving-lost-credentials.md b/docs/reference/configuration/Single Sign-On/recoving-lost-credentials.md new file mode 100644 index 0000000000..86887a8fb1 --- /dev/null +++ b/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 password: +Enter password again: +``` + +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 + 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.