Chapter 13. User Session Management
When a user logs into a realm, Red Hat Single Sign-On maintains a user session for them and remembers each and every client they have visited within the session. There are a lot of administrative functions that realm admins can perform on these user sessions. They can view login stats for the entire realm and dive down into each client to see who is logged in and where. Admins can logout a user or a set of users from the Admin Console. They can revoke tokens and set up all the token and session timeouts there too.
13.1. Administering Sessions
If you go to the Sessions left menu item you can see a top level view of the number of sessions that are currently active in the realm.
Sessions
A list of clients is given and how many active sessions there currently are for that client. You can also log out all users in the realm by clicking the Logout all button on the right side of this list.
13.1.1. Limitations of the Logout all Operation
Any SSO cookies set will now be invalid and clients that request authentication in active browser sessions will now have to re-login. Only certain clients are notified of this logout event, specifically clients that are using the Red Hat Single Sign-On OIDC client adapter. Other client types, such as SAML, will not receive a backchannel logout request.
It is important to note that any outstanding access tokens are not revoked by clicking Logout all. They have to expire naturally. You have to push a revocation policy out to clients, but that also only works with clients using the Red Hat Single Sign-On OIDC client adapter.
13.1.2. Application Drilldown
On the Sessions page, you can also drill down to each client. This will bring you to the Sessions tab of that client. Clicking on the Show Sessions button there allows you to see which users are logged into that application.
Application Sessions
13.1.3. User Drilldown
If you go to the Sessions tab of an individual user, you can also view the session information.
User Sessions
13.2. Revocation Policies
If your system is compromised you will want a way to revoke all sessions and access tokens that have been handed out. You can do this by going to the Revocation tab of the Sessions screen.
Revocation
You can only set a time-based revocation policy. The console allows you to specify a time and date where any session or token issued before that time and date is invalid. The Set to now will set the policy to the current time and date. The Push button will push this revocation policy to any registered OIDC client that has the Red Hat Single Sign-On OIDC client adapter installed.
13.3. Session and Token Timeouts
Red Hat Single Sign-On gives you fine grain control of session, cookie, and token timeouts. This is all done on the Tokens tab in the Realm Settings left menu item.
Tokens Tab
Let’s walk through each of the items on this page.
| Configuration | Description |
|---|---|
| Default Signature Algorithm | The default algorithm that is used to assign tokens for this realm. |
| Revoke Refresh Token | For OIDC clients that are doing the refresh token flow, this flag, if on, will revoke that refresh token and issue another token with the request that the client has to use. The result is that each refresh token is used only once. |
| SSO Session Idle | Also pertains to OIDC clients. If the user is not active for longer than this timeout, the user session will be invalidated. The idle timeout is reset by a client requesting authentication or by a refresh token request. There is a small window of time that is always added to the idle timeout before the session invalidation takes effect. See the note below. |
| SSO Session Max | Maximum time before a user session is expired and invalidated. This option controls the maximum time that a user session can remain active, regardless of user activity. |
| SSO Session Idle Remember Me | Same as the standard SSO Session Idle configuration but specific to logins with Remember Me enabled. It allows for the specification of longer session idle timeouts when Remember Me is selected during the login process. It is an optional configuration and if not set to a value greater than 0 it uses the same idle timeout as set in the SSO Session Idle configuration. |
| SSO Session Max Remember Me | Same as the standard SSO Session Max but specific to logins with Remember Me enabled. It allows for the specification of longer lived sessions when Remember Me is selected during the login process. It is an optional configuration and if not set to a value greater than 0 it uses the same session lifespan as set in the SSO Session Max configuration. |
| Offline Session Idle | For offline access, this is the time the session is allowed to remain idle before the offline token is revoked. There is a small window of time that is always added to the idle timeout before the session invalidation takes effect. See the note below. |
| Offline Session Max Limited | For offline access, if this flag is on, Offline Session Max is enabled to control the maximum time the offline token can remain active, regardless of user activity. |
| Offline Session Max | For offline access, this is the maximum time before the corresponding offline token is revoked. This option controls the maximum time the offline token can remain active, regardless of user activity. |
| Access Token Lifespan | When an OIDC access token is created, this value affects the expiration. |
| Access Token Lifespan For Implicit Flow | With the Implicit Flow no refresh token is provided. For this reason there’s a separate timeout for access tokens created with the Implicit Flow. |
| Client login timeout | This is the maximum time that a client has to finish the Authorization Code Flow in OIDC. |
| Login timeout | Total time a login must take. If authentication takes longer than this time then the user will have to start the authentication process over. |
| Login action timeout | Maximum time a user can spend on any one page in the authentication process. |
| User-Initiated Action Lifespan | Maximum time before an action permit sent by a user (e.g. forgot password e-mail) is expired. This value is recommended to be short because it is expected that the user would react to self-created action quickly. |
| Default Admin-Initiated Action Lifespan | Maximum time before an action permit sent to a user by an admin is expired. This value is recommended to be long to allow admins send e-mails for users that are currently offline. The default timeout can be overridden right before issuing the token. |
| Override User-Initiated Action Lifespan | Permits the possibility of having independent timeouts per operation (for example, e-mail verification, forgot password, user actions and Identity Provider E-mail Verification). This field is optional. If nothing is specified, it defaults to the value configured at User-Initiated Action Lifespan. |
For idle timeouts, there is a small window of time (2 minutes) during which the session is kept unexpired. For example, when you have timeout set to 30 minutes, it will be actually 32 minutes before the session is expired. This is needed for some corner-case scenarios in cluster and cross-datacenter environments, in cases where the token was refreshed on one cluster node for a very short time before the expiration and the other cluster nodes would in the meantime incorrectly consider the session as expired, because they had not yet received the message about successful refresh from the node which did the refresh.
13.4. Offline Access
Offline access is a feature described in OpenID Connect specification . The idea is that during login, your client application will request an Offline token instead of a classic Refresh token. The application can save this offline token in a database or on disk and can use it later even if user is logged out. This is useful if your application needs to do some "offline" actions on behalf of user even when the user is not online. An example is a periodic backup of some data every night.
Your application is responsible for persisting the offline token in some storage (usually a database) and then using it to retrieve new access token from Red Hat Single Sign-On server.
The difference between a classic Refresh token and an Offline token is, that an offline token will never expire by default and is not subject of the SSO Session Idle timeout and SSO Session Max lifespan. The offline token is valid even after a user logout or server restart. However by default you do need to use the offline token for a refresh token action at least once per 30 days (this value, Offline Session Idle timeout, can be changed in the administration console in the Tokens tab under Realm Settings). Moreover, if you enable the option Offline Session Max Limited, then the offline token expires after 60 days regardless of using the offline token for a refresh token action (this value, Offline Session Max, can also be changed in the administration console in the Tokens tab under Realm Settings). Also if you enable the option Revoke refresh tokens, then each offline token can be used just once. So after refresh, you always need to store the new offline token from refresh response into your DB instead of the previous one.
Users can view and revoke offline tokens that have been granted by them in the User Account Service. The admin user can revoke offline tokens for individual users in admin console in the Consents tab of a particular user. The admin can also view all the offline tokens issued in the Offline Access tab of each client. Offline tokens can also be revoked by setting a revocation policy.
To be able to issue an offline token, users need to have the role mapping for the realm-level role offline_access. Clients also need to have that role in their scope. Finally, the client needs to have an offline_access client scope added as an Optional client scope to it, which is done by default.
The client can request an offline token by adding the parameter scope=offline_access when sending authorization request to Red Hat Single Sign-On. The Red Hat Single Sign-On OIDC client adapter automatically adds this parameter when you use it to access secured URL of your application (i.e. http://localhost:8080/customer-portal/secured?scope=offline_access). The Direct Access Grant and Service Accounts also support offline tokens if you include scope=offline_access in the body of the authentication request.
13.5. Transient sessions
Red Hat Single Sign-On has the concept of transient sessions. When transient sessions are used, no real user session is created after successful authentication. Only a temporary transient session is created for the scope of the current request that successfully authenticated the user. This transient session allows Red Hat Single Sign-On to run protocol mappers after the authentication.
When transient sessions are used, the client application has no way to refresh or introspect the token or check if a specific session is valid. In some situations, these actions are not needed, so you can avoid the additional overhead for persistence of user sessions. This would improve performance and save memory and network communication (in case of cluster and cross-datacenter environments).
