Configure Keycloak login policies

What you’ll accomplish

You’ll configure Keycloak login behavior for your UDS Core deployment: setting concurrent session limits, session idle timeouts, and logout confirmation behavior. All configuration in this guide is applied via 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
• Familiarity with UDS bundle overrides

Before you begin

This guide configures Keycloak via Helm chart values, the fastest path to operational changes with no image rebuild required. If you’re unsure which approach fits your need, see Keycloak configuration layers. For custom themes or plugins, see Build a custom Keycloak configuration image.

Note

Settings applied via realmInitEnv or realmAuthFlows bundle overrides (covered in this guide and related guides) are only imported during the initial Keycloak realm setup. On a running instance, these require a full Keycloak teardown and redeploy to take effect, or you can apply them manually in the admin UI. Each relevant step below notes which settings are affected.

Steps

1. Limit concurrent sessions per user

   By default, Keycloak allows unlimited concurrent sessions per user. To restrict this (for example, to enforce single-session policies or limit login storms), set these values in your bundle:

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       overrides:
         keycloak:
           keycloak:
             values:
               - path: realmInitEnv
                 value:
                   # Maximum concurrent active sessions per user (0 = unlimited)
                   SSO_SESSION_MAX_PER_USER: "3"
               - path: realmConfig
                 value:
                   # Maximum in-flight (ongoing) login attempts per user
                   maxInFlightLoginsPerUser: 1

   Setting	Default	Description
   SSO_SESSION_MAX_PER_USER	0 (unlimited)	Max concurrent active sessions per user
   maxInFlightLoginsPerUser	300	Max concurrent login attempts in progress

2. Configure session idle timeouts

   Keycloak has two session idle timeout layers that interact with each other:

   • Realm session idle timeout: Controls the overall user session. When it expires, the user is logged out from all applications.
   • Client session idle timeout: Controls the refresh token expiration for a specific application. Must be set equal to or shorter than the realm timeout.

   Danger

   The client session timeout must not exceed the realm session timeout. Keycloak 26.5.0+ (UDS Core 0.59.0+) will reject this configuration. Earlier versions accepted it silently but the realm timeout took precedence anyway, so users would still be logged out at the realm timeout interval regardless of the client setting.

   Configure realm session timeouts via bundle override:

   The realm-level SSO session idle timeout and max lifespan are set during initial realm import and can be configured in your uds-bundle.yaml:

   uds-bundle.yaml

   packages:
     - name: core
       repository: registry.defenseunicorns.com/public/core
       ref: x.x.x-upstream
       overrides:
         keycloak:
           keycloak:
             values:
               - path: realmInitEnv
                 value:
                   # Session idle timeout in seconds (default: 600 = 10 minutes)
                   SSO_SESSION_IDLE_TIMEOUT: "1800"
                   # Session max lifespan in seconds (default: 36000 = 10 hours)
                   SSO_SESSION_MAX_LIFESPAN: "28800"

   Note

   realmInitEnv values are applied only during initial realm import. If Keycloak is already running, a full Keycloak teardown and redeploy is required for these settings to take effect. To change timeouts on a live instance without redeploying, use the admin UI instead (see below).

   Configure realm session timeouts in the Keycloak admin UI (for live instances):

   1. Log in to the Keycloak admin UI at keycloak.<admin_domain>
   2. Switch to the uds realm using the top-left dropdown
   3. Go to Realm Settings → Sessions tab
   4. Adjust SSO Session Idle and SSO Session Max as needed

   Configure per-client session timeouts (admin UI only, not available as a bundle override):

   1. Go to Clients → select the client → Advanced tab → Advanced Settings
   2. Set Client Session Idle to a value ≤ the realm’s SSO Session Idle

   Note

   When a client session expires, users are not necessarily forced to log in again immediately. If the realm session is still active, browser-based applications can silently obtain new tokens. However, applications using only bearer tokens (without browser session cookies) will require the user to reauthenticate once the refresh token expires. The realm session timeout is the outer bound: once it expires, all clients are logged out regardless of client session settings.

3. Disable logout confirmation

   By default, UDS Core shows a confirmation page when a user logs out. To skip this for specific applications, set the logout.confirmation.enabled attribute in the Package CR:

   package.yaml

   apiVersion: uds.dev/v1alpha1
   kind: Package
   metadata:
     name: my-package
     namespace: my-namespace
   spec:
     sso:
       - name: My SSO Client
         clientId: my-client-id
         redirectUris:
           - "https://my-app.uds.dev/login"
         attributes:
           logout.confirmation.enabled: "false"

   Note

   This is a per-client setting in the Package CR, not a global Keycloak setting. To disable it globally, configure the default in Keycloak’s realm settings instead.

4. Create and deploy your bundle

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

   Note

   To learn about FIPS 140-2 mode (always enabled), see Manage FIPS 140-2 mode.

Verification

Confirm your session policy changes are applied:

Check concurrent session limits:

1. Log in to the same application from two different browser sessions
2. If SSO_SESSION_MAX_PER_USER is set to 1, the second login should invalidate the first session

Check logout confirmation:

1. Log out from an application where you set logout.confirmation.enabled: "false"
2. The user should be logged out immediately without a confirmation page

Check session timeout configuration:

In the Keycloak admin UI, navigate to Realm Settings → Sessions and confirm the SSO Session Idle and SSO Session Max values match your intended configuration.

Troubleshooting

Problem: Session expires unexpectedly early

Symptoms: Users are logged out before the configured timeout elapses, or sessions expire after only 10 minutes on a fresh deployment.

Solution: The default SSO_SESSION_IDLE_TIMEOUT is 600 seconds (10 minutes). If this is too short for your environment, set a longer value in realmInitEnv before the first deploy, or update it in the Keycloak admin UI (Realm Settings → Sessions) on a live instance.

Also verify that the client session idle timeout is ≤ the realm session idle timeout. In Keycloak 26.5+ this is enforced; in earlier versions, a misconfigured client setting would be silently overridden by the realm setting.

Problem: Bundle deploy fails with a realmConfig error

Symptoms: uds deploy fails with a validation error referencing realmConfig fields.

Solution: Verify the path and value types match the chart values schema. Common mistakes:

• Values expected as strings must be quoted: "3" not 3 for SSO_SESSION_MAX_PER_USER
• Check the Keycloak chart values for the correct path syntax

Problem: Logout confirmation change has no effect

Symptoms: Users still see a logout confirmation page after setting logout.confirmation.enabled: "false".

Solution: Confirm the Package CR is applied and the UDS Operator has reconciled it. Check the operator logs:

uds zarf tools kubectl logs -n pepr-system -l app=pepr-uds-core-watcher --tail=50 | grep logout

Related documentation

• Build a custom Keycloak configuration image - for theme and plugin customization beyond Helm values
• Manage FIPS 140-2 mode - verify FIPS status and understand constraints
• Keycloak: Session and Token Timeouts - upstream reference for session configuration options
• Package CR reference - full spec for SSO client configuration
• Enforce group-based access controls - Restrict application access to users in specific Keycloak groups using the Package CR.