Configure session handling

Session handling comprises the internal censhare Server session, Keycloak and Cloud Gateway configuration.

Prerequisites

Requires censhare WP

Introduction

When logging in to censhare, the user is authenticated at Keycloak. With successful authentication, the censhare Server creates an active session with the respective user permissions. All request from the user client to the censhare Server are routed through the Cloud Gateway. For a secure session handling, all involved components must be accordingly configured.

You can configure timeouts that determine when a web session is closed due to inactivity via the client connection, lost client connection, or closing the web client. The session termination upon these events ensures that the session is properly disconnected. Active users are required to periodically reconnect and authenticate. This prevents session hijacking attempts. It also helps to reduce the amount of memory that is used when a large number of idle sessions are open simultaneously.

An active user session requires a valid JWT Token. This token can be shared across all services (Keycloak, Cloud Gateway, censhare Server, and optionally Google AI). When a session terminates after the user logs out, when a connection is lost, or after the session times out, the JWT token is invalidated. The user is redirected to the login page and must authenticate again.

Configuration

Cloud Gateway

To change the configuration of the Cloud Gateway, edit the core-cloud-gateway/application.yml file on your host:

If you want to use a custom-branded censhare Web, see also the necessary configuration of the application.yml file in (2021.2) Custom branding (censhare WP).

Parameter	Default value	Remarks
cg.censhareLogoutUrl	http://CENSHARE-SERVER-HOST:PORT/forward/rest/service/webserver/rest/csLogout	Adjust the CENSHARE_SERVER_HOST:PORT accordingly. The default port for non-SSL access is 9000. If Keycloak, Cloud Gateway and censhare Server are installed on the same host, the entry localhost:9000 works. However, we do not recommend to use localhost entries. Instead, use an alias for the censhare Server.
cg.censhareStartPageUrl	http://WEB-CLIENT-HOST:PORT/censhare5/client	Adjust the CENSHARE_CLIENT_HOST:PORT accordingly. The default port for non-SSL access is 9000. For the standard branding, leave the /censhare5/client part as is. If you use a custom branding, change according to the URL to access the custom branding.
cg.expiredSessionFullLogout	true	Ensures that the session is terminated from censhare Server and Keycloak. If set to false, Keycloak keeps the session alive.
cg.sessionTimeoutSec	1800 (equals 30 mins)	To avoid waiting 30 minutes for each attempt, adjust this value according to the live span of the access token and the refresh token. Ensure that: The session timeout value in Keycloak is higher than the cg.sessionTimeoutSec value The token live cycle value is lower than the cg.sessionTimeoutSec value For more information, see the Keycloak documentation.
cg.sessionCheckIntervalMs	60000 (equals 1 minute)	The interval, in which censhare checks for expired sessions. Decreasing this value below the threshold of 10000 can affect the performance of the application!
cg.maxSessions	10000	The maximum number of parallel sessions allowed in the Cloud Gateway. Normally, one session per user can be calculated, but it is possible that one user has multiple active sessions simultaneously. Increasing this value can affect the performance of the application!

Keycloak

In Keycloak, you must configure the correct redirect URLs to ensure that the users are redirected back to the login page when their session has expired, before they can resume their work in censhare. For more information, see Configure Keycloak for external authentication.

censhare Server

On the censhare Server, you can configure the web session limits for internal API connections.

We strongly recommend not to change the default settings for web session timeouts! If you do so, test your configuration thoroughly to ensure that they work in combination with the Cloud Gateway settings!

The following default setting can changed in the censhare Admin Client, under Configuration/Services/API:

Field	Default value	Remarks
Keep session alive	3 minutes	The maximum time to keep a web session alive after users have closed all browser windows without any user logout or the browser connection has been lost.
Session duration limit	1440 minutes (equals 1 day)	The maximum idle time of a web session without any user activity. After this period, the session is closed by a session cleaner. For security and performance reasons, we recommend to select an idle time that is not too long. The appropriate minimum value possible depends on the context of the application or tasks.

Timeout behavior with different connection protocols

For details on different connection protocols and their behavior regarding timeouts, see this FAQ.

Monitor web session timeouts

You can monitor session behavior in the censhare system asset and censhare log files. Check session creation/cleaning to analyse creation trends and detect irregular numbers of session creation. For more information, see Monitoring.

Monitor Keep sessions alive timeouts:

See a sample log with Keep alive timeout set to 2 minutes. After closing the browser window, the session is closed after 2 minutes:

Monitor Session inactivity limit timeouts:

See a sample log with session inactivity limit set to 5 minutes. A session cleaner closes the session after 5 minutes of session inactivity.