Configure Keycloak authentication methods

What you’ll accomplish

You’ll enable or disable the authentication methods available on the UDS Core login page (including username/password, X.509/CAC certificates, WebAuthn, OTP, and social login) using bundle overrides. No image rebuild is required.

Prerequisites

• UDS Core deployed
• UDS CLI installed
• UDS Registry account created and authenticated locally with a read token

Before you begin

UDS Core ships with all major authentication flows enabled by default. Use realmAuthFlows bundle overrides to selectively enable or disable them for your environment.

Setting	Default	Description
USERNAME_PASSWORD_AUTH_ENABLED	true	Username/password login, password reset, and registration
X509_AUTH_ENABLED	true	X.509 certificate (CAC/PIV) authentication
SOCIAL_AUTH_ENABLED	true	Social/SSO login (Google, Azure AD, etc.); requires an IdP to also be configured
OTP_ENABLED	true	One-time password (TOTP) as a required MFA step for username/password login
WEBAUTHN_ENABLED	false	WebAuthn/passkey as a required MFA step for username/password login
X509_MFA_ENABLED	false	Require additional MFA (OTP or WebAuthn) after X.509 authentication

Danger

Disabling USERNAME_PASSWORD_AUTH_ENABLED, X509_AUTH_ENABLED, and SOCIAL_AUTH_ENABLED all at once will result in no authentication options on the login page. Users will not be able to log in or register. Also, disabling both USERNAME_PASSWORD_AUTH_ENABLED and X509_AUTH_ENABLED disables user self-registration.

Note

realmAuthFlows controls the login experience and Keycloak realm flows. Keycloak applies theme-related changes after a pod restart, but imports realm-flow changes only during the initial realm import. To change realm flows on an existing deployment, follow Step 4. Keycloak also applies truststore certificates and custom plugin JARs after a pod restart without a realm redeploy.

Steps

1. Determine which flows to enable

   Identify which authentication methods your environment requires. Common configurations:

   Environment	Recommended configuration
   CAC-only (no username/password)	Disable USERNAME_PASSWORD_AUTH_ENABLED, keep X509_AUTH_ENABLED
   Username/password + OTP only	Keep defaults, disable X509_AUTH_ENABLED and SOCIAL_AUTH_ENABLED
   Username/password + WebAuthn	Enable WEBAUTHN_ENABLED, disable OTP_ENABLED if desired
   CAC + MFA	Enable X509_MFA_ENABLED (also requires OTP_ENABLED or WEBAUTHN_ENABLED)

   Note

   UDS Core ships with DoD UNCLASSIFIED CA certificates by default, so X.509/CAC authentication works out of the box in DoD environments. If your environment uses a different CA chain, see Configure the CA truststore.

2. Add realmAuthFlows to your bundle override

   In your uds-bundle.yaml, set the desired authentication flow values:

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       overrides:
         keycloak:
           keycloak:
             values:
               - path: realmAuthFlows
                 value:
                   USERNAME_PASSWORD_AUTH_ENABLED: true
                   X509_AUTH_ENABLED: false
                   SOCIAL_AUTH_ENABLED: false
                   OTP_ENABLED: true
                   WEBAUTHN_ENABLED: false
                   X509_MFA_ENABLED: false

   For clarity and auditability, specifying all settings explicitly is recommended, even settings you are leaving at their defaults.

   Note

   If you are disabling X509_AUTH_ENABLED, also update your Istio gateway configuration to stop requesting client certificates from browsers. With X.509 auth disabled, the gateway should not present mutual TLS to users. Set the tls.cacert override on istio-tenant-gateway (and istio-admin-gateway if applicable) to an empty string or remove it. See Configure the CA truststore for the gateway override structure.

3. Create and deploy your bundle

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

4. (Optional) Update realm flows on an existing deployment

   If the Keycloak realm was already imported, a new realmAuthFlows value does not update its realm flows. Manually update the uds realm in the Keycloak Admin Console at keycloak.<admin_domain>. Apply the tab for each primary method or optional MFA method you need to update. For example, to keep only Social/SSO after deploying X.509/CAC and Social/SSO, apply the X.509/CAC tab.

   Username/password

   For USERNAME_PASSWORD_AUTH_ENABLED: false:

   1. Open Authentication → Flows → UDS Authentication.
   2. Expand Username Password Form.
   3. Set Deny Access to Required.
   4. Open Authentication → Flows → UDS Reset Credentials and disable Reset Password.
   5. Open Authentication → Flows → UDS Registration. Leave UDS Registration form enabled if X.509/CAC remains enabled. If X.509/CAC is also disabled, disable UDS Registration form.

   Caution

   Do not disable UDS Registration form while X.509/CAC remains enabled. CAC users need this flow to register.

   X.509/CAC

   For X509_AUTH_ENABLED: false:

   1. Open Authentication → Flows → UDS Authentication.
   2. Set X509 Authentication to Disabled.
   3. Open Authentication → Flows → UDS Registration. Leave UDS Registration form enabled if username/password remains enabled. If username/password is also disabled, disable UDS Registration form.
   4. Stop the gateway from requesting client certificates as described in Configure the CA truststore.

   Caution

   Do not disable UDS Registration form while username/password remains enabled. Username/password users need this flow to register.

   Social/SSO

   For SOCIAL_AUTH_ENABLED: false:

   1. Open Authentication → Flows → UDS Authentication.
   2. Set IDP Redirector to Disabled.
   OTP

   For OTP_ENABLED: true:

   1. Open Authentication → Flows → UDS Authentication. In Username/Password Authentication, set the Conditional OTP sub-flow to Required.
   2. Inside the Conditional OTP sub-flow, set OTP to Required.
   3. Open Authentication → Required Actions and enable Configure OTP.

   For OTP_ENABLED: false:

   1. Open Authentication → Flows → UDS Authentication.
   2. Inside the Conditional OTP sub-flow, set OTP to Disabled.
   3. If WebAuthn is also disabled, set the Conditional OTP sub-flow to Disabled.
   WebAuthn

   For WEBAUTHN_ENABLED: true:

   1. Open Authentication → Required Actions and enable Webauthn Register.
   2. Open Authentication → Flows → UDS Authentication. In Username/Password Authentication, set the Conditional OTP sub-flow to Required.
   3. Inside the Conditional OTP sub-flow, set WebAuthn Authenticator to Required.

   For WEBAUTHN_ENABLED: false:

   1. Open Authentication → Required Actions and disable Webauthn Register.
   2. Open Authentication → Flows → UDS Authentication.
   3. Inside the Conditional OTP sub-flow, set WebAuthn Authenticator to Disabled.
   4. If OTP is also disabled, set the Conditional OTP sub-flow to Disabled.

Verification

Confirm authentication flow changes are applied:

1. Navigate to sso.<domain>
2. Confirm only the expected login options appear on the login page
3. For X.509/CAC: confirm the browser prompts for a client certificate (requires truststore to be configured and a valid certificate installed)

Check Keycloak authentication flow configuration:

In the Keycloak admin UI, navigate to keycloak.<admin_domain> → uds realm → Authentication → Flows and confirm the expected flow steps are enabled or disabled.

Troubleshooting

Problem: X.509/CAC login fails with OCSP error in airgapped environment

Symptoms: Certificate authentication fails with an OCSP revocation check error. Logs show the OCSP responder is unreachable.

Solution: Configure OCSP fail-open behavior or disable OCSP checking via realmInitEnv.

To allow authentication when the OCSP responder is unreachable (fail-open):

- path: realmInitEnv
  value:
    X509_OCSP_FAIL_OPEN: "true"

To disable OCSP checking entirely:

- path: realmInitEnv
  value:
    X509_OCSP_CHECKING_ENABLED: "false"

Danger

Disabling OCSP checking means revoked certificates will not be rejected. Understand your organization’s compliance requirements before using this setting.

If your environment uses CRL-based revocation instead of OCSP, configure the CRL path:

- path: realmInitEnv
  value:
    X509_CRL_CHECKING_ENABLED: "true"
    X509_CRL_RELATIVE_PATH: "crls/DODROOTCA3.crl##crls/DODIDCA_81.crl"  # Relative to /opt/keycloak/conf; use ## between multiple paths
    X509_CRL_ABORT_IF_NON_UPDATED: "false"  # Set true to fail authentication if CRL is expired

Note

CRL files must be present on the Keycloak pod at the path specified in X509_CRL_RELATIVE_PATH, relative to /opt/keycloak/conf. To include CRL files in a custom image, see the uds-identity-config repository.

Problem: MFA is not required after enabling WebAuthn or OTP

Symptoms: Users can log in without completing an MFA step.

Solution: Confirm that both the flow toggle and at least one MFA method are enabled. For WebAuthn to work as a required step, WEBAUTHN_ENABLED: true must be set; for OTP, OTP_ENABLED: true. Verify the realm was redeployed after the override was applied.

If redeploying is not possible, use the corresponding OTP or WebAuthn tab in Step 4.

Reference: X.509/CAC with additional MFA

Note

CAC authentication (X.509 certificate + PIN) already satisfies multi-factor requirements in most security frameworks: the certificate is “something you have” and the PIN is “something you know.” X509_MFA_ENABLED adds a second software factor on top of CAC, which is rarely needed and can be impractical in classified environments where personal devices aren’t permitted. Confirm this is an explicit requirement before enabling it.

If you do need to require an additional factor after CAC authentication, use this configuration in the realmAuthFlows block from step 2 in place of the values shown there, then recreate and deploy the bundle:

- path: realmAuthFlows
  value:
    X509_AUTH_ENABLED: true
    X509_MFA_ENABLED: true
    OTP_ENABLED: true       # At least one MFA method must also be enabled
    WEBAUTHN_ENABLED: false

X509_MFA_ENABLED: true has no effect unless at least one of OTP_ENABLED or WEBAUTHN_ENABLED is also enabled.

Related documentation

• Keycloak: Authentication - upstream reference for Keycloak authentication flow configuration
• Configure the CA truststore - Configure the CA certificate bundle required for X.509/CAC authentication.
• Configure user accounts and security policies - Set password complexity and email verification alongside auth flow configuration.