Configure cookie-expiry and cookie-refresh for Logout and Standard compliances (e.g. HIPAA)

Idle Timeout (Inactivity) Configuration for Kloudfuse OAuth2-Proxy

This guide explains how to control automatic logout after a period of user inactivity (idle timeout) by tuning the cookie-expire and cookie-refresh settings in your custom YAML.

1. Key Concepts

cookie-expire: Total lifetime of the session cookie. After this duration without any user activity, the user will be logged out and must re-authenticate.
cookie-refresh: Interval at which OAuth2-Proxy will automatically use the IdP refresh token to renew the session cookie (resetting its TTL). Requires an active HTTP request (click, navigation, AJAX) to trigger.

Activity: Any HTTP request sent to the protected app (e.g., page navigation, AJAX call, link click). To be qualified for InActivity or Idle time, passive actions like hovering or just viewing the page would be considered.

Behavior: On each valid request, if the session cookie is older than cookie-refresh, OAuth2-Proxy will call the IdP to get a fresh access token and re-issue the cookie with a full cookie-expire TTL. If no requests occur within the cookie-expire window, the session expires.

2. Setting Idle Timeout

Choose your idle timeout (e.g. 30 minutes): this becomes your cookie-expire.
Set your refresh interval to a value shorter than cookie-expire (e.g. 5 minutes): this becomes your cookie-refresh.

Example: To log users out after 30 minutes of inactivity, but renew their session every 5 minutes when active:

kfuse-auth:
  oauth2-proxy:
    extraArgs:
      cookie-expire: "30m"
      cookie-refresh: "5m"

cookie-expire: "30m" → session lasts up to 30 minutes without activity.
cookie-refresh: "5m" → on each request older than 5 minutes, OAuth2-Proxy will renew the cookie.

Catches:

SSO/SAML flows: Refresh tokens must still be valid; if the IdP’s refresh token TTL is shorter than cookie-expiry, sessions will end early than the time limit set by cookie-expiry.
Basic Auth: No OAuth refresh flow. Once cookie-expiry or cookie-refresh value is reached (whichever is shorter time), the user will be logged out to the sign in page.