Skip to content

Sessions and Timeouts

Jump to bottom Edit New page
Hans Zandbelt edited this page Jul 25, 2024 · 10 revisions

When deploying mod_auth_openidc there are different sessions and timeouts at play simultaneously. This page aims to describe those parameters and their relation.

Sessions

Upon return to the Apache server after successful authentication at the Provider there are 2 (or 3) sessions created.

1. mod_auth_openidc session

mod_auth_openidc creates a session for the user that is tracked by a cookie. This session holds information about the user, the OpenID Connect tokens that have been created, session timeouts etc. This information can be stored client side or server side. The session will expire after:

For more information on how to configure parameters for the mod_auth_openidc session, see: https://github.com/OpenIDC/mod_auth_openidc/wiki/Session-Management-Settings

2. Provider Session

Authentication of the user is performed by the OpenID Connect Provider. The Provider typically creates a Single Sign On session for the user, also tracked by a (Provider/SSO) cookie. This session (and its cookie) is independent from the session that mod_auth_openidc creates, and it has its own timeouts. This leads to a number of observations:

  • when the mod_auth_openidc session expires, the user will be redirected to the Provider for authentication; at that point the Provider SSO session may stil be active, the Provider does not prompt the user for authentication again (it is SSO after all), and the user will just return to the Apache server where a new mod_auth_openidc session is created i.e. without explicit authentication
  • when the Provider session expires, the module's session may still be valid and the user will be able to continue to use the application until mod_auth_openidc's session itself expires; then the user is redirected to the Provider for authentication and explicit authentication is required because there's no active SSO session at the Provider anymore
  • a logout of mod_auth_openidc, a logout at the Provider, or a logout from one of the other applications connected to the Provider, will only result in the termination of all sessions when OpenID Connect Single Logout has been configured for all those applications

3. (optional) Application Session

When protecting a legacy application (e.g. running in a Tomcat container), that application may create its own session (e.g. tracked by a JSESSIONID cookie) once an authenticated request comes in. That session is independent from the (2) sessions mentioned above and may have its own timeouts. This leads to the following observations:

  • expiry of this application session may result in a new application session created for the same user without re-authentication, assuming the module's session is still active
  • expiry of the module's session will result in re-authentication at the Provider, even if the application session is still alive.

Timeouts

Each of the sessions above typically has its own (a) session inactivity timeout and (b) session maximum duration. Apart from those timeouts, the following timeouts are also at play.

1. State Cookie Timeout

When the user is redirected to the Provider for authentication, a state cookie is created that is used to correlate the request to the eventual authentication response; this cookie has its own timeout, representing the maximum time that the user can use to finish the authentication round trip, see: https://github.com/OpenIDC/mod_auth_openidc/wiki/Cookies#state-cookie

2. ID token Timeout

After successful authentication at the Provider, an ID Token is generated that is sent back to mod_auth_openidc. The ID Token contains a timeout that represents the maximum duration after which the token should no longer be accepted by mod_auth_openidc. Note that the ID Token merely represents a user authentication event and is not a session in itself, nor is related to any session. (see also here)

3. Access Token Timeout

After successful authentication at the Provider, an Access Token is generated that is sent back and stored by mod_auth_openidc. Note that the Access Token represents an access grant, it is not a session in itself, nor is related to any session. The access token is used for two purposes:

  • for calling the OpenID Connect UserInfo endpoint to obtain information about the authenticated user that is stored in the session; see here to (optionally) keep this information up to date during the time that the session lives
  • for passing it to a application that can use it to call (application specific) OAuth 2.0 protected APIs, see also here

The Access Token has an associated timeout after which API requests using it will fail. If a refresh token was also returned by the Provider, one can optionally configure the module to obtain a new access token in a just-in-time fashion, see https://github.com/OpenIDC/mod_auth_openidc/wiki/Single-Page-Applications#refresh-access-token-ahead-of-expiry

4. Refresh Token Timeout

If a refresh token was returned by the Provider, it is stored as part of the mod_auth_openidc session and may be used to obtain new access tokens until it expires, see previous bullet. Upon expiry of the refresh token, a new authentication roundtrip will be triggered, a new session will be created and a new refresh token is also obtained.

Session Timeout and Forms

The module's session timeout and behaviour can cause inconvenience for applications that present forms to the end user. Filling out a large form manually may take considerable time and during that time a potential session timeout will trigger an authentication redirect after which the form data is lost. The following options may be used as a workaround for that, at the cost of decreased security:

  1. increase OIDCSessionInactivityTimeout

    Set it to the maximum time that users have to complete the form; note that this is a global setting that applies to every pages and every request.

  2. set OIDCPreservePost On

    This will aim to store the form data temporarily in the browser's HTML 5 session storage, redirect the user for authentication and then restore that data, see here ; be aware that sensitive data may be stored and left in the browser in case the user never actually finishes the authentication roundtrip. This comes with limitations in size and data types and can only be used to store simple POST name/value pairs.

  3. keep the session alive on the Form page

    By sending HTTP GET (or XHR) requests to a protected endpoint (e.g. <OIDCRedirectURI>?info=json to also obtain the timeout settings) the inactivity time will be reset on each request, effectively extending the session, see e.g. here; note that this may lead to the session being kept alive forever (when the user stays on that page in a browser tab), or you'll have to implement a page timeout yourself, which would basically bring you back to the original problem (in this case with differentiated timeouts for different pages)

Single Page Applications

SPAs may call endpoints/APIs in two ways:

  • endpoints protected by mod_auth_openidc i.e. the same instance served the SPA itself, in which case the session cookie is automatically sent with the XHR request.

    a timeout occurs when the mod_auth_openidc session expires as described above

  • endpoints protected by OAuth 2.0 Resource Server functionality, typically in a different domain or protected by mod_auth_openidc in Resource Server or Mixed mode.

    a timeout occurs when the Access Token expires as described above, also for a description on now to refresh the Access Token before it expires

Note that an XHR request can never be used to reliably authenticate the user since there is no user interface that can be presented to the end-user. One should not rely on application/session/SSO cookies as a workaround, nor should one try to authenticate in iframes or in other non-interactive ways, which would defeat the point of trying to get the user to re-authenticate anyhow.

In case a timeout occurs, a 401 is returned to the SPA. This behaviour can be configured with OIDCUnAuthAction. Upon receiving the 401, the SPA should reload the application by refreshing the parent window, after which an authentication roundtrip will occur and a new session with new tokens is created.

See also: https://github.com/OpenIDC/mod_auth_openidc/wiki/Single-Page-Applications

Add a custom footer
Add a custom sidebar
Clone this wiki locally