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 required.

Prerequisites

UDS Core deployed
UDS CLI installed
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.

Steps

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:

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

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.
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"
```
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
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.
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"
```
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.
Create and deploy your bundle
Terminal window
```
uds create <path-to-bundle-dir>
uds deploy uds-bundle-<name>-<arch>-<version>.tar.zst
```
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:

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

Check logout confirmation:

Log out from an application where you set logout.confirmation.enabled: "false"
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

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

Next steps

These guides and concepts may be useful to explore next:

Enforce group-based access controls Restrict application access to users in specific Keycloak groups using the Package CR.

Connect Azure AD as an identity provider Federate Keycloak with Azure Entra ID for enterprise SSO.

Cookie Settings Privacy Policy