This tutorial describes how to configure the session inactivity timeout in Keycloak using the Keycloak Admin Console. This lets you control the warning modal that the system displays to the user when their session is about to expire.
- Keycloak 26.x or later.
- Custody LTS Version 1.34 or later.
- Admin access to the Keycloak Admin Console.
- You are working in the Metaco realm.
The session inactivity timeout automatically logs out users after a configurable period of inactivity. The system displays a warning modal dialog before logout, giving users the opportunity to extend their session.
Two environment variables for the frontend v2 component control the inactivity timeout feature:
HMZ_FEATURE_SESSION_INACTIVITY_TIMEOUT="true"
SESSION_INACTIVITY_TIMEOUT_MINUTES=20| Variable | Type | Default | Description |
|---|---|---|---|
HMZ_FEATURE_SESSION_INACTIVITY_TIMEOUT | boolean | false | Enables the inactivity timeout feature. |
SESSION_INACTIVITY_TIMEOUT_MINUTES | number | 20 | Duration of inactivity (in minutes) before logout. |
When disabled (default), the feature has no effect on the application.
The timeout follows three phases:
- Active — The user interacts normally. Any activity (click, keypress, mouse movement) resets the timer.
- Warning — After the inactivity timer reaches the threshold, a modal appears with a countdown asking the user to confirm they are still working. The warning appears during the last 20% of the total timeout (minimum 10 seconds).
- Logged Out — If the user does not respond, the system silently signs them out and displays a "Session expired" modal prompting them to log back in.
The following is an example with a 20-minute timeout:
| Time elapsed | Event |
|---|---|
| 0–16 minutes | User is idle. No UI change. |
| 16 minutes | Warning modal appears with a 4-minute countdown. |
| 20 minutes | System logs the user out; "session expired" modal displays. |
The warning modal displays:
- A countdown of the remaining time (e.g. "3 min 45 sec")
- A Continue working button to reset the timer
- A Log out button to end the session immediately
The browser tab title changes to "Timeout warning - Ripple Custody" to alert users who may have switched tabs.
The system synchronizes the timer across all open browser tabs. Activity in any tab resets the timer for all tabs.