Enabling Authentication Session Persistence

This can be done only once you have installed the WSO2 Identity Server (IS) 5.0.0 along with the Service Pack. This topic is regarding sessions in the IS and the process of enabling session persistence for these sessions. This is particularly useful when the remember me option is selected when logging into either the service provider or the WSO2 Identity Server.

Understanding sessions in the WSO2 Identity Server

When you log in to the Web application using WSO2 Identity Server, a single sign-on (SSO) session is created by the Identity Server for the user of the application. Also, as the user logs in to the Web application, there is session created in the Web application itself for the user. These are two separate sessions and they are not synchronized with each other.

For an example, if the Web application has a session timeout of 20 minutes and the WSO2 IS SSO session timeout is 5 minutes, the application users will not see the login page up to 20 minutes. That is because WSO2 IS is not invalidating the session by force on the Web application.

If the Web application session timeout is 5 minutes and the WSO2 IS SSO session timeout is 20 minutes, the users will not see the login page up to 20 minutes. This is because even when the Web application container session timeout after 5 minutes, the session was kept alive since WSO2 IS SSO session is still alive. The user will not be redirected to the login screen of the SP until the WSO2 IS SSO session is invalidated.

WSO2 Identity Server creates separate SSO session for SSO login and it is different from the session that is created when you log in to the Identity Server management console.

When end user logs in through the WSO2 Identity Server for the service provider application (using SAML2 SSO, OpenID Connect, Passive STS, etc.), the Identity Server creates a SSO session for end users and a cookie that is related to the created SSO session is set to the user’s browser.

This cookie can be seen as commonauthId. It is set to the user’s browser with the hostname of WSO2 Identity Server instance and the value of the commonauthId cookie is the SSO session identifier. When SSO session is created in the WSO2 Identity Server, the session is put into the session cache and persisted to the database. To persist it in to the database, you must enable the session persistence.

Click here to read about the importance of persisting the session.

SSO sessions have been stored in a in-memory cache. It is recommended to persist the SSO session due to following reasons.

If you are running a single WSO2 Identity Server instance and the server is restarted, all SSO session would be removed. If you have multiple nodes of WSO2 instances, It is not guaranteed that you can recover all the sessions. Although the cache is distributed, it is not 100% split to each node.
Cache has a limit. If there are large number of SSO sessions, memory can be high and server performance may reduce. So usually the cache is evicted after a given number of entries (by default 10000 entries). Therefore, some SSO session can be evicted from caches when there are large number of user logins.
When there is a clustered development, if you have no persistence, you need to rely completely on the distributed cache. However, if you have persistence, you can rely on it as well. This increases the reliability of the overall system.

To enable authentication session persistence, uncomment the following configuration in the <IS_HOME>/repository/conf/identity.xml file, under the Server and JDBCPersistenceManager elements.

<SessionDataPersist>
	<Enable>true</Enable>
	<RememberMePeriod>20160</RememberMePeriod>
	<CleanUp>
        <Enable>true</Enable>
        <Period>1440</Period>
        <TimeOut>20160</TimeOut>
    </CleanUp>
	<Temporary>false</Temporary>
</SessionDataPersist>

See the following for more information on the configurations mentioned above.

Configuration element	Description
`Enable`	This enables the persistence of session data. Therefore, this must be configured to `true` if you wish to enable session persistence.
`RememberMePeriod`	If you check the commonauthid cookie, you will notice that the cookie time expires at end of session. This means that if you close the browser or restart your machine, the cookie is removed. So; when you close your browser after SSO login, your SSO session in the WSO2 Identity Server would be invalidated. Therefore, if you need to remember the SSO session, you need to select the Remember Me option in the WSO2 Identity Server login page. The commonauthid cookie is set with some defined expiry value. Then cookie will contain in the browser till it expired. Expiry time of the “commonauthid” cookie, can be configured from following property. This is the time period (in minutes) that the remember me option should be valid. After this time period, the users are logged out even if they enable the remember me option. The default value for this configuration element is 2 weeks.
`CleanUp`	This section of the configuration is related to the cleaning up of session data. The cleanup task runs on a daily basis (once a day) by default unless otherwise configured in the `Period` tag. When this cleanup task is executed, it removes session data that is older than 2 weeks, unless otherwise specified in the `TimeOut` tag.
`Enable`	Selecting true here enables the cleanup task and ensures that it starts running.
`Period`	This is the time period (in minutes) that the cleanup task would run. The default value is 1 day.
`TimeOut`	This is the timeout value (in minutes) of the session data that is removed by the cleanup task. The default value is 2 weeks.
`Temporary`	Setting this to `true` enables persistence of temporary caches that are created within an authentication request.

Note: If you are not using default values for the above configuration, the value of the TimeOut element must always be greater than the value of the RememberMePeriod element. This is necessary to ensure that the session data must not be cleared before the session ends.

Additionally, you must uncomment the following configuration under the Server element (which is the root element in the identity.xml configuration file). This is a step related to authentication session persistence. The previous configuration indicates whether to persist the cache or not, while this is about enabling caching and indicating its capacity.

<SessionContextCache> 
	<Enable>true</Enable> 
	<Capacity>100000</Capacity>	
</SessionContextCache>

See the following for more information on the configurations mentioned above.

Configuration element	Description
Enable	When this is set to `true`, caching is enabled for sessions.
Capacity	This is the size of the cache.

Note: If Single Sign-On is to work, you must enable at least one of the two configurations mentioned in this topic.