Content of Session Context Cache in WSO2 IS : An Overview

If you ever used WSO2 Identity Server, then probably you must have encountered the word “Session Context”. Have you ever wondered what that is? Why are we using that? How are we using it in the authentication flow? Then you should read this. I hope it will give you some understanding of the Session Context of the WSO2 Identity Server.

First, let’s start with the WSO2 Identity Server. What is WSO2 Identity Server? WSO2 Identity Server is an open-source API-driven IAM product. It helps to build the best Customer Identity and Access Management (CIAM) solutions. WSO2 Identity Server is based on the SAML, OAuth and OIDC open standards and open source principles. WSO2 IS is capable of providing strong and adaptive authentication, identity federation, single sign-on, identity bridging, privacy compliance and identity provisioning. Authentication is a process of identifying user identity. Here the provided user credentials are checked with the available user information stored as a file within the database of the authentication server or local operating system. The use of Authentication mainly falls under three categories such as something the user is, something the user knows or something the user has. There are several types of authentication from single-factor authentication which checks for only one factor to multi-factor authentication (MFA) which checks two or more credentials.

We are using the caches to transfer the credentials and the necessary information during the authentication flow.

You can refer to this link to know about the caches and how the authentication happened.

They include the information on successful/ unsuccessful authentication and compare the requests with new incoming authentication requests. In WSO2 Identity Server, IDN_AUTH_SESSION_STORE and IDN_AUTH_TEMP_SESSION_STORE are used to store caches during the authentication flow. When the control of the process is handed over to the user, the server will store the current status of the process as a temporary placement. These data are stored in IDN_AUTH_TEMP_SESSION_STORE. Other data types that are related to the session are stored in IDN_AUTH_SESSION_STORE which will be used to have session data objects that store the authenticated user and the other authentication flow details. It is created by the WSO2 Identity Server when the user is authenticated. Session Context Cache is one of the caches which is stored in the IDN_AUTH_SESSION_STORE.

Session Context object is created when the Default Authentication Request Handler concludes the flow. The concludeFlow method of the default authentication request handler is used to send the response to the servlet that initiated the authentication flow. We are going to get the session context from the cache by using session context cache key which is obtained from the common auth cookie. If session context didn’t exist there then we are going to create the new session context object. If the session context existed in the cache then we will update it with the particular session data. If it is not then we will create a new session context and set the values for the session there.

Let’s refer to the content of the session context and its usage.

Here we are going to see the attributes of the Session context. Let’s start with authenticatedSequences. Authenticated Sequences has the collection of the sequence configs in a map which has the application name as a key and the respective sequence config as the value. We are using it in the findPreviousAuthenticatedSession method of the Default Request Coordinator. We are using it to get the previously authenticated sequence config using its app name. Then we will get the step map, request path authenticators, authenticated user, authenticated IdPs and authenticated Request Path Authenticators to build the effective sequence config.

Here we came across the class — “Sequence Config”. Let’s have a look around the Sequence config class.

The sequenceConfig class mentioned above has certain attributes. Those are name, isForceAuthn which is used to store whether force authentication is enabled or not, isCheckAuthn used to store whether check authentication is enabled or not, applicationId which is used as a reference for application, authenticationGraph attribute will be created and set based on the authentication script if it is enabled, reqPathAuthenticators are used to set the authenticator configs. completed is used to know whether the sequence is completed or not, authenticatedUser is used to set the user after the authentication of each step. Other than these there are other attributes in Sequence Config such as authenticatedIdPs, authenticatedReqPathAuthenticator and requestedAcr where their name itself holds the usage of attributes. There are attributes called stepMap which is a map consisting of step order as a key and StepConfig as value and applicationConfig which is used to have an application config object.

You can refer to this link to know more about the SequenceConfig class.

Now we came to know about some new class names Application Config and Step Config. ApplicationConfig has several attributes that are obtained from the service provider object. Those attributes are applicationID, applicationName, roleClaim, alwaysSendMappedLocalSubjectId, mappedSubjectIDSelected, subjectClaimUri, permissions, claimMappings, roleMappings, requestedClaims, mandatoryClaims, isSaaSApp, useTenantDomainInLocalSubjectIdentifier, useUserstoreDomainInLocalSubjectIdentifier, enableAuthorization, useUserstoreDomainInRole and useUserIdForDefaultSubject. With that, there is a serviceProvider attribute which is used to store the respective entire service provider object.

You can refer to this link to know more about the Application config class.

Let’s take an overview of the StepConfig class also.

The StepConfig class has the attribute order which is an int value to keep the track of the step configuration, multiOption which will be true if there is more than one authenticator for the step, loginPage, authenticatedUser, subjectIdentifierStep, subjectAttributeStep, authenticatedIdP, authenticatorMappings, completed, retrying and forced. Other than these we have authenticatedAutenticator and authenticatorList. We have authenticatorList which is used to store the list of authenticator configs that were configured for the particular step respectively and we have authenticatedAuthenticator which is used to have the authenticator config that is used to authenticate the particular step.

You can refer to this link to know more about the StepConfig class.

Let’s continue with the Session context class. We have authenticatedIdPs next to authenticated sequences. We have a collection of Authenticated IdP Data as the map which has the name of the authenticated idp data as the key and authenticated idp data as the value. We are using it to setPreviousAuthenticatedIdPs of the Authentication context in the findPreviousAuthenticatedSession method of the Default Request Coordinator. And We have authenticatedIdPsOfApp which has the collection of authenticated IdPs in the map which has the application name as the key and AuthenticatedIdPs that is a map of authenticated IdP data as the value. There we have a collection of authenticated IdP data as the map which has the name of the authenticated IdP data as the key and particular authenticated IdP data as the value. We are using this authenticatedIdPsOfApp to setAuthenticatedIdPsOfApp of Authentication context in the findPreviousAuthenticatedSession method of the Default Request Coordinator. So here both authenticatedIdPs and authenticatedIdPsOfApp are having the collection of the authenticated IdP data. So let’s take a look at the AuthenticatedIdPData class.

The authenticated Idp Data contains the attributes idpname, authenticators, and authenticatedUser. Their usage can be expressed by the name itself. We have an attribute — authenticators which is used to store the List of authenticator configs for the particular step. and we have lastAuthenticatedUser stores the user/subject known at the latest authentication step.

You can refer to this link to know more about the AuthenticatedIdPData class.

And we already got to see the class name “Authenticator Config” in the step config class also. We have a list of authenticator configs as the authenticatorList and authenticator config object which is used to authenticate in the respective step in the authenticatedAuthenticator. So let’s have a look at the AuthenticatorConfig class.

AuthenticatorConfig has the attributes name, enabled, authenticatorStateInfo and parameterMap for which the name itself will clearly explain the use of them. Other than them we have applicationAuthenticator which is an API for the application authenticator, idps which is used to store the identity providers which are configured for the respective authenticator config. It is a map that has the identity provider’s name as the key and the entire identity provider object as the value and idpNames which is used to store the names of the identity providers.

You can refer to this Link to know more about the authenticator config class.

Other than the mentioned attributes of the session context, we have isRememberMe attribute to keep track if the remember me option is enabled or not, properties where we have the collection of particular properties for the session. For example, CreatedTimestamp, opbs, AuthenticatedUser and tenantDomain are the properties that are in the properties. Then we have the Session Auth History attribute which helps to keep the track of the session history in the session context.

You can refer to this Link to know more about the SessionAuthHistory class.

We are using the Session Context Cache class to store and get the session context cache object. It is a singleton class.

You can refer to this Link to know about the Session Context Cache.

We are using addToCache(SessionContextCacheKey key, SessionContextCacheEntry entry, String loginTenantDomain) method to add a cache entry by using storeSessionData() method of the Session Data Store class.

Session Context Cache Key is a class that is used as a key to session context cache and Session Context Cache Entry is the class which is used as a wrapper object to session context cache.

We are having a session context object as context, loggedInUser and accessedTime in the Session Context Cache Entry. We created the entry before we passed it to the session context cache to add to the cache. And there, we will pass it to the storeSessionData method of the Session Data Store class.

And there we will check if the cache is a temporary cache or not, as we already saw the session context cache is not the temporary cache. And It will check if the maximum session data pool size is greater than 0, by default we will have 100, then we have to push the object in the queue and then persisting will be handled by another thread. In WSO2 IS ‘persistence_pool_size’ equals 0 means that it is disabled and then the authentication flow is blocked until this particular data persistence task is complete. To execute the persistence task asynchronously, set the value to greater than zero. Based on the pool size, the system creates the task parallel, to execute the persistence task that was in the queue. Any value greater than zero does not provide expected results, and sometimes causes unwanted side effects. This can be configured in the deployment.toml file.

We are using getValueFromCache(SessionContextCacheKey key, String loginTenantDomain) method to get the session context cache entry. Here we will try to get the entry from the cache and if we failed to get the entry from the cache then we will try to get it from the database.

Here we are using the getSessionFromDB method to get the entry from the database. We are using context id that can be obtained from the key and type of the cache to get the object from the database.

We are using this SessionContextDO to pass the data to and from the SessionDataStore. We will load the session context cache entry from it and return it to the getValueFromCache method. After the timeout value of the session context object, it will clean up from the database. We are having this cleanup time period to remove session data by the cleanup task. The default value is 14 days. Otherwise, the database will grow with that data very frequently. Since the above data is collected over the authentication flow.

This will sum up on what you need to know about the Session context. I hope that it would have helped you to go through the attributes of the session context and their usage in a detailed manner and the creation of the session context from how we are using it to store the session info and how we are cleaning it. If you want to know more about the session context or about the authentication in the WSO2 IS, you can download WSO2 IS here and You can clone the carbon-identity-Framework from here and Let’s debug it.