[RHIDP-11458]: Document session management in RHDH (#2035)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: themr0c

assemblies/shared/assembly-manage-session-expiration.adoc

@@ -0,0 +1,19 @@
+:_mod-docs-content-type: ASSEMBLY
+ifdef::context[:parent-context: {context}]
+
+[id="manage-session-expiration_{context}"]
+= Manage session expiration
+
+:context: manage-session-expiration
+
+[role="_abstract"]
+You can manage how long users stay authenticated in {product} by configuring session duration and auto-logout settings.
+
+include::../modules/shared/con-understand-session-management-in-rhdh.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-configure-session-management.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-enable-auto-logout-for-inactive-users.adoc[leveloffset=+1]
+
+ifdef::parent-context[:context: {parent-context}]
+ifndef::parent-context[:!context:]

assemblies/shared/assembly-troubleshoot-authentication-issues.adoc

@@ -11,9 +11,13 @@ Learn how to troubleshoot common authentication issues.
 
 include::../modules/shared/proc-reduce-the-size-of-issued-tokens.adoc[leveloffset=+1]
 
+include::../modules/shared/proc-troubleshoot-unexpected-session-expiration.adoc[leveloffset=+1]
 
-include::../modules/shared/ref-troubleshoot-login-failed-errors.adoc[leveloffset=+1]
+include::../modules/shared/proc-troubleshoot-missing-session-expiration-warning.adoc[leveloffset=+1]
+
+include::../modules/shared/proc-troubleshoot-missing-login-redirect-after-session-expiration.adoc[leveloffset=+1]
 
+include::../modules/shared/ref-troubleshoot-login-failed-errors.adoc[leveloffset=+1]
 
 include::../modules/shared/ref-troubleshoot-catalog-provider-errors.adoc[leveloffset=+1]
 

modules/shared/con-understand-session-management-in-rhdh.adoc

@@ -0,0 +1,68 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="understand-session-management-in-rhdh_{context}"]
+= Understand session management in {product-short}
+
+[role="_abstract"]
+Session management in {product} involves multiple mechanisms that control how long users stay authenticated and what happens when sessions expire.
+
+== What happens when a session expires
+
+When a session approaches expiration, {product-short} can display a pre-expiration warning dialog that includes a countdown timer.
+The timing of this warning depends on how you configure the auto-logout feature.
+
+After the session expires, {product-short} redirects the user to the login page.
+To continue working, the user must re-authenticate with the configured identity provider and is then returned to {product-short}.
+
+// TODO: Screenshot placeholder: warning dialog
+// TODO: Screenshot placeholder: login redirect
+
+== AutoLogout (frontend inactivity)
+
+The AutoLogout feature monitors user activity in the browser and logs out the user after a configurable idle period.
+AutoLogout revokes the refresh token for {product-short}, but does not end the Identity Provider (IdP) session.
+The logout mechanism is the same as if you manually logout from the user settings page.
+
+You configure AutoLogout under the `auth.autologout` section of your `{my-app-config-file}` file.
+
+== Session duration (provider-level)
+
+Session duration controls the absolute session lifetime regardless of user activity.
+This is a backend HTTP-only cookie configuration.
+When this duration elapses, no warning popup is displayed.
+Instead, the user is redirected to the sign-in page the next time they interact with {product-short}, such as navigating to a new page or refreshing the browser.
+
+You configure session duration per provider by using the `auth.providers.<name>.<env>.sessionDuration` parameter in your `{my-app-config-file}` file.
+This parameter accepts milliseconds, ISO duration, or human-readable duration values (for example, `24h`, `2 days`).
+
+== Identity Provider session settings
+
+Your Identity Provider (IdP), such as {rhbk-brand-name}, GitHub, {azure-brand-name}, or GitLab, maintains its own session timeout independently of {product-short}.
+
+Signing out of {product-short} does not end the IdP SSO session.
+This is expected behavior.
+If the IdP session is still active when a user signs back in to {product-short}, re-authentication might be seamless, with no password prompt.
+
+== How the mechanisms interact
+
+The three session management mechanisms operate at different layers:
+
+AutoLogout::
+Triggers on user inactivity in the browser.
+Frontend-only: does not revoke tokens or end server-side sessions.
+
+Session duration::
+Controls the absolute session lifetime on the server side.
+The session expires after the configured duration regardless of user activity.
+No warning popup is displayed; the user is redirected to the sign-in page on next interaction.
+
+Identity Provider session::
+Outlives {product-short} sign-out.
+A user might re-enter {product-short} without a password prompt if the IdP session is still active.
+
+The mechanism with the shortest timeout takes effect first.
+For example, if AutoLogout is set to 30 minutes of idle time but the session duration is set to 15 minutes, the session expires after 15 minutes regardless of user activity.
+
+[role="_additional-resources"]
+.Additional resources
+* xref:enable-auto-logout-for-inactive-users_{context}[Enable auto-logout for inactive users]

modules/shared/proc-configure-session-management.adoc

@@ -0,0 +1,36 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="configure-session-management_{context}"]
+= Configure session management
+
+[role="_abstract"]
+You can configure the session duration for your authentication provider in {product}.
+
+.Prerequisites
+
+* You have administrative access to the {product} configuration files.
+
+.Procedure
+
+. To set the absolute session lifetime for an authentication provider, add the `sessionDuration` parameter to your `{my-app-config-file}` file:
++
+[source,yaml,subs="+attributes,+quotes"]
+----
+auth:
+  providers:
+    <name>:
+      <env>:
+        sessionDuration: 24h
+----
++
+`sessionDuration`::
+Enter the session lifetime in milliseconds, ISO duration, or human-readable format (for example, `24h`, `2 days`).
+When this duration elapses, the session expires regardless of user activity.
++
+This parameter is not set by default.
+
+. Restart the {product} application to apply the changes.
+
+[role="_additional-resources"]
+.Additional resources
+* xref:enable-auto-logout-for-inactive-users_{context}[Enable auto-logout for inactive users]

modules/shared/proc-troubleshoot-missing-login-redirect-after-session-expiration.adoc

@@ -0,0 +1,12 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="troubleshoot-missing-login-redirect-after-session-expiration_{context}"]
+= Troubleshoot missing login redirect after session expiration
+
+[role="_abstract"]
+If users are not redirected to the login page after their session expires, verify the following.
+
+.Procedure
+
+. Verify that your {product-short} version includes the upstream session expiration fix.
+. Verify that your authentication provider is correctly configured with valid `metadataUrl`, `clientId`, and `clientSecret` settings.

modules/shared/proc-troubleshoot-missing-session-expiration-warning.adoc

@@ -0,0 +1,16 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="troubleshoot-missing-session-expiration-warning_{context}"]
+= Troubleshoot missing session expiration warning
+
+[role="_abstract"]
+If users receive no warning before their session expires, auto-logout might not be enabled.
+Without auto-logout, sessions expire silently based on `sessionDuration` or IdP settings.
+
+.Procedure
+
+* To enable pre-expiration warnings, configure the `auth.autologout` settings in your `{my-app-config-file}` file.
+
+[role="_additional-resources"]
+.Additional resources
+* xref:enable-auto-logout-for-inactive-users_manage-session-expiration[Enable auto-logout for inactive users]

modules/shared/proc-troubleshoot-unexpected-session-expiration.adoc

@@ -0,0 +1,18 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="troubleshoot-unexpected-session-expiration_{context}"]
+= Troubleshoot unexpected session expiration
+
+[role="_abstract"]
+If sessions expire sooner than expected, check the following settings.
+The mechanism with the shortest timeout takes effect first.
+
+.Procedure
+
+. Check the Identity Provider (IdP) session timeout: the IdP might have a shorter session lifetime than {product-short}.
+. Check the `sessionDuration` parameter for your authentication provider.
+. Check the AutoLogout `idleTimeoutMinutes` setting, if auto-logout is enabled.
+
+[role="_additional-resources"]
+.Additional resources
+* xref:configure-session-management_manage-session-expiration[Configure session management]

titles/control-access_authentication-in-rhdh/master.adoc

@@ -28,6 +28,6 @@ include::assemblies/shared/assembly-enable-authentication-with-gitlab.adoc[level
 
 include::assemblies/shared/assembly-enable-service-to-service-authentication.adoc[leveloffset=+1]
 
-include::modules/shared/proc-enable-auto-logout-for-inactive-users.adoc[leveloffset=+1]
+include::assemblies/shared/assembly-manage-session-expiration.adoc[leveloffset=+1]
 
 include::assemblies/shared/assembly-troubleshoot-authentication-issues.adoc[leveloffset=+1]