{"templateId":"markdown","versions":[{"version":"v1.40","label":"v1.40 STS","link":"/products/custody/identity-and-access/sso/keycloak-inactivity-timeout","default":true,"active":false,"folderId":"c15a2701"},{"version":"v1.39","label":"v1.39 STS","link":"/products/custody/v1.39/identity-and-access/sso/keycloak-inactivity-timeout","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.38","label":"v1.38 STS","link":"/products/custody/v1.38/identity-and-access/sso/keycloak-inactivity-timeout","default":false,"active":true,"folderId":"c15a2701"},{"version":"v1.34","label":"v1.34 LTS","link":"/products/custody/v1.34/identity-and-access/sso/keycloak-inactivity-timeout","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.26","label":"v1.26 LTS","link":"/products/custody/v1.26/identity-and-access/sso/keycloak-inactivity-timeout","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.19","label":"v1.19 LTS","link":"/products/custody/v1.19/identity-and-access/sso/keycloak-inactivity-timeout","default":false,"active":false,"folderId":"c15a2701"},{"version":"v1.15","label":"v1.15 LTS","link":"/products/custody/v1.15/identity-and-access/sso/keycloak-inactivity-timeout","default":false,"active":false,"folderId":"c15a2701"}],"sharedDataIds":{"sidebar":"sidebar-products/custody/@v1.15/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Keycloak inactivity timeout","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"keycloak-inactivity-timeout","__idx":0},"children":["Keycloak inactivity timeout"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial describes how to configure the session inactivity timeout in Keycloak using the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Keycloak Admin Console"]},". This lets you control the warning modal that the system displays to the user when their session is about to expire."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keycloak ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["26.x"]}," or later."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Custody LTS Version ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["1.34"]}," or later."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Admin access to the Keycloak Admin Console."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You are working in the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Metaco"]}," realm."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"overview","__idx":2},"children":["Overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"enabling-the-feature","__idx":3},"children":["Enabling the feature"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two environment variables for the frontend v2 component control the inactivity timeout feature:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"HMZ_FEATURE_SESSION_INACTIVITY_TIMEOUT=\"true\"\nSESSION_INACTIVITY_TIMEOUT_MINUTES=20\n"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Variable"},"children":["Variable"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HMZ_FEATURE_SESSION_INACTIVITY_TIMEOUT"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["false"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Enables the inactivity timeout feature."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SESSION_INACTIVITY_TIMEOUT_MINUTES"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["number"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["20"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Duration of inactivity (in minutes) before logout."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When disabled (default), the feature has no effect on the application."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":4},"children":["How it works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The timeout follows three phases:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Active"]}," — The user interacts normally. Any activity (click, keypress, mouse movement) resets the timer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following is an example with a 20-minute timeout:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Time elapsed"},"children":["Time elapsed"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["0–16 minutes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["User is idle. No UI change."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["16 minutes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Warning modal appears with a 4-minute countdown."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["20 minutes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["System logs the user out; \"session expired\" modal displays."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-warning-modal","__idx":5},"children":["The warning modal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The warning modal displays:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A countdown of the remaining time (e.g. \"3 min 45 sec\")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Continue working"]}," button to reset the timer"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Log out"]}," button to end the session immediately"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The browser tab title changes to \"Timeout warning - Ripple Custody\" to alert users who may have switched tabs."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cross-tab-behavior","__idx":6},"children":["Cross-tab behavior"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The system synchronizes the timer across all open browser tabs. Activity in any tab resets the timer for all tabs."]}]},"headings":[{"value":"Keycloak inactivity timeout","id":"keycloak-inactivity-timeout","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Overview","id":"overview","depth":2},{"value":"Enabling the feature","id":"enabling-the-feature","depth":2},{"value":"How it works","id":"how-it-works","depth":2},{"value":"The warning modal","id":"the-warning-modal","depth":2},{"value":"Cross-tab behavior","id":"cross-tab-behavior","depth":2}],"frontmatter":{"seo":{"title":"Keycloak inactivity timeout"}},"lastModified":"2026-07-27T10:10:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/custody/v1.38/identity-and-access/sso/keycloak-inactivity-timeout","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}