Content of Authentication Context Cache in WSO2 IS : An overview
If you ever used WSO2 Identity Server, then probably you must have encountered the word “Authentication Context”. Have you ever wondered what that is? Why are we using that? How is it used in the authentication context? Then you should read this. I hope it will give you some understanding about the authentication context of WSO2 Identity Server.
First, let’s start with 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. They include the information of successful/ unsuccessful authentication information 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.
Let’s take the OIDC Code flow in WSO2 Identity Server as an example. Following session types are persisted in the OIDC code flow. In the IDN_AUTH_TEMP_SESSION_STORE table
- OAuthSessionDataCache
- AuthenticationContextCache
- AuthenticationResultCache session types are found.
In IDN_AUTH_SESSION_STORE table
- AppAuthFrameworkSessionContextCache
- OIDCSessionParticipantCache
- AuthorizationGrantCache are found.
Initially, when an OAuth2/Authorize requests to enter into the server, the OAuth component will validate the request which contains the client id and other parameters. The OAuth component is responsible for maintaining the flow protocol. After the validation, the OAuth component stores the data of the request in the database as OAuth Session Data Cache and Authentication context cache which is going to be used by the framework component. The framework component is responsible for the user authentication process. OAuth Session Data Cache contains OAuth2 Parameters, redirect URI, client id and a few other similar data. The Authentication Context Cache contains the fields necessary for the authentication process. Both belong to the temporary session data type which is stored in the temporary store. There will be a respective login page that is based on the configured authenticator after the storing process of these caches. When a user provides the credentials on the login page it will be sent through the commonauth. Commonauth will include credentials and Session Data Key which is used to obtain the Authentication Context Cache stored in the previous step. After obtaining the AuthenticationContextCache using the Session Data Key the session is validated and the values are set and stored in the Authentication Context Cache again. If there are uncompleted authentication steps or if there are any missing claims then there will be a prompt page for them, in that scenario authentication context cache will be used in the same manner.
You can refer to this link to know more about the caches and how the authentication happened.
Let’s refer to the content of the authentication context and its usages in the authentication flow.
Here we are going to see the attributes of the authentication context. Let’s start with contextIdentifier which is used to identify the authentication context object, sessionIdentifier is used to identify the session. callerPath is used to store the caller path and send the response, currentStep keeps track of steps in authentication flow. And we have callerSessionKey, relyingParty, queryParams, requestType and isLogoutRequest which is used to identify if it is for the log out request or not. The attribute sequenceConfig is used to store the credentials which are needed to keep the authentication sequence properly. It is stored as a SequenceConfig object which includes the stepMap that is used to have the step configurations which were configured for the authentication sequence. Now we just pause it here and let’s visit 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.
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 continue with the Authentication context class. We have an attribute called externalIdP which is used to store the external identity provider’s configuration. ExternalIdPConfig has the attributes claimConfiguration, roleConfiguration, justInTimeProConfig, parameterMap and roleMappings which are related with the identity provider. Other than these we have an entire identity provider object here.
You can refer to this link to know about the IdentityProvider class.
We have rememberMe which is used to identify whether the user enabled remember me option or not, tenantDomain stores tenant Domain which is needed in many aspects of the framework component, currentPostAuthHandlerIndex stores the current post authentication handler index which is in execution, retryCount, authenticatorProperties, serviceProviderName, contextIdIncludedQueryParams, currentAuthenticator and endpointParams.
forceAuthenticate stores whether force authentication or not. If it is a force authentication then it will need a new session. passiveAuthenticate is used to store whether the request is passive authentication or not, authenticationRequest is used to store the authentication request object which has its attributes/parameters of the authentication request, previousAuthenticatedIdPs stores the previously authenticated IdPs for the session, currentAuthenticatedIdPs stores the current authenticated IdPs. If there are no current authenticated IDPs, it means no authentication has taken place yet. Therefore we need to check whether there are previously authenticated IDPs for this session. CurrentAuthenticatedIdPs (if not null) always contain the previousAuthenticatedIdPs. activeInAThread is used as the authentication context’s thread status flag and here we have some more attributes called reAuthenticate and previousAuthTime.
requestAuthenticated, returning, retrying, previousSessionFound are used as authentication context’s flow control flags.
We have authenticationStepHistory which is used to store Adaptive Authentication control and status, requestedAcr, acrRule, selectedAcr, authenticatedIdPsOfApp which is a map with AuthenticatedIdPData’s name as the key and AuthenticatedIdpData as the value. The authenticated Idp Data contains the attributes idpname, authenticator, and authenticatedUser. Their usage can be expressed by the name itself. With that, it has 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, subject stores the subject which was set by each authenticator and stateInfo which holds any (state) information that would be required by the authenticator for later processing. Other than these userTenantDomainHint, loginTenantDomain, executedPostAuthHandlers, parameters are also there in the Authentication Context.
You can refer to this Link to know more about the Authentication Context class.
We learned about the StepConfig class from the SequenceConfig class. It is there in the stepMap. Let’s take an overview of the StepConfig class also.
The StepConfig class has the attributes 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.
We came across the Authenticator Config class several times in the above discussion. We have mentioned that Authenticator config is found in these two places, namely in AuthenticatedIdPData and in StepConfig. Let’s have a small look at that too.
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.
We are using the Authentication Context Cache class to cache the data about the authentication request sent from a servlet and we are using it to store and get the authentication context cache object. It is a singleton class.
You can refer this Link to know about the Authentication Context Cache.
We are using addToCache(AuthenticationContextCacheKey key, AuthenticationContextCacheEntry entry) method to add a cache entry by using storeSessionData() method of the Session Data Store class. Authentication Context Cache Key is a class that is used as a key to authentication context cache and Authentication Context Cache Entry is the class which is used as a wrapper object to authentication context cache. We added the entry in the cache before we passed it to store in the database. As we mentioned above Authentication context is the temporary session object. We checked if we disabled (it is enabled as default) the temporary session data persists, if it is not then we store the session data.
As authentication context is a temporary cache then we won’t add it to the queue. We passed it to persist by using the persistSessionData() method of Session Data Store class.
We used getValueFromCache(AuthenticationContextCacheKey key) method of authentication context cache class to retrieve the authentication context cache.
First, we try to get the cache from the cache if we didn’t find the entry there, then we will get it using the getSessionData() method Session Data Store class to get the entry from the database. After authentication steps are completed, we will remove the authentication context.
This will sum up the blog on what you need to know about the Authentication context. I hope that it would have helped you to go through the attributes of the authentication context and their usage in a detailed manner. If you want to know more about the authentication 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.
