Upgrade to FIPS 140-2 mode

What you’ll accomplish

You’ll prepare an existing Keycloak deployment for upgrade to a UDS Core version with FIPS 140-2 Strict Mode enabled — migrating password hashing algorithms and resetting credentials that are incompatible with FIPS before the upgrade runs.

Note

FIPS 140-2 Strict Mode is always enabled in UDS Core. If you are deploying UDS Core for the first time, no action is required — FIPS is active by default. This guide applies only when upgrading an existing non-FIPS deployment.

Prerequisites

• Access to the Keycloak admin console on the pre-upgrade deployment
• UDS CLI installed

Before you begin

FIPS mode changes how Keycloak handles cryptography and passwords:

Constraint	Detail
Password hashing	argon2 (upstream Keycloak default) is not FIPS-approved — UDS Core uses pbkdf2-sha256
Minimum password length	14 characters
Algorithms	Only FIPS-approved algorithms are available for signing, encryption, and hashing

Existing accounts hashed with argon2 or with passwords shorter than 14 characters will fail to authenticate after FIPS is enabled. Complete the steps below before upgrading to the FIPS-enabled version.

Steps

1. Connect to the Keycloak admin console on your pre-upgrade deployment

   uds zarf connect keycloak

   Alternatively, navigate directly to keycloak.<admin_domain> if your admin domain is accessible.

2. Add pbkdf2-sha512 as the password hashing policy

   In the master realm:

   1. Go to Authentication → Policies → Password Policy
   2. Add a new policy: select Hashing Algorithm and set the value to pbkdf2-sha512
   3. Save

3. Reset all local user passwords to FIPS-compliant values

   For the admin user and any other local accounts:

   1. Go to Users → select the user
   2. Go to the Credentials tab → Reset Password
   3. Set a new password of at least 14 characters
   4. Set Temporary to Off
   5. Save

   Danger

   Do not upgrade UDS Core until all local users have new FIPS-compliant passwords. If the admin password is not migrated, you will be locked out of the admin console after the upgrade.

4. Upgrade UDS Core

   With all passwords migrated, proceed with the upgrade:

   uds create <path-to-bundle-dir>
   uds deploy uds-bundle-<name>-<arch>-<version>.tar.zst

Verification

Confirm FIPS is active after the upgrade by temporarily enabling debug mode in your bundle:

uds-bundle.yaml

- path: debugMode
  value: true

Deploy the bundle, then check the Keycloak startup logs:

uds zarf tools kubectl logs -n keycloak -l app.kubernetes.io/name=keycloak --tail=100 | grep BCFIPS

Look for:

KC(BCFIPS version 2.0 Approved Mode, FIPS-JVM: disabled)

BCFIPS version 2.0 Approved Mode confirms Keycloak is running in FIPS Strict Mode. FIPS-JVM: disabled is expected unless the underlying host OS is also running a FIPS-enabled kernel. Disable debugMode once confirmed.

Troubleshooting

Problem: Keycloak admin console is inaccessible after upgrade

Symptoms: Cannot log in to the Keycloak admin console after upgrading. Login fails with a password error.

Solution: The admin password was hashed with argon2 or is shorter than 14 characters — FIPS rejects both. To recover:

1. Access the Keycloak pod directly:

   uds zarf tools kubectl exec -n keycloak statefulset/keycloak -- /opt/keycloak/bin/kcadm.sh \
     set-password --username admin --new-password <new-14+-char-password> \
     --server http://localhost:8080 --realm master --user admin --password <old-password>

2. Once logged in, follow step 3 above to reset all remaining accounts.

Related Documentation

• Keycloak FIPS 140-2 support — upstream details on FIPS constraints and limitations

Next steps

These guides and concepts may be useful to explore next:

Configure Keycloak login policies Set session timeouts, concurrent session limits, and logout confirmation behavior.

Configure user accounts and security policies Set password complexity and hashing algorithm alongside FIPS requirements.