# Keycloak inactivity timeout

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.

## Prerequisites

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


## Overview

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.

## Enabling the feature

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.

## How it works

The timeout follows three phases:

1. **Active** — The user interacts normally. Any activity (click, keypress, mouse movement) resets the timer.
2. **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).
3. **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

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.

## Cross-tab behavior

The system synchronizes the timer across all open browser tabs. Activity in any tab resets the timer for all tabs.