Server Identity Cache Performance

Microsoft Azure Active Directory is now Microsoft Entra ID

Use this topic to understand the various configuration settings associated with the server’s identity cache.

The Identity Service includes a caching mechanism designed to work with any user and group provider configured to work with the product, such as Active Directory users and groups, Azure Active Directory, LDAP, and SharePoint groups and system roles. Note that the Active Directory user manager cache is disabled automatically which allows the server identity cache to cache user and group information instead.

Backend Database Tables

The Identity framework uses the following tables which are located in the K2 database:

Identity.CacheConfiguration table

The [Identity].[CacheConfiguration] table sets the time parameters of the Identity Provider (K2, K2SQL, custom) cache settings and the Microsoft SQL command timeout setting. The default values of these settings are as follows:

You can define these settings in milliseconds (ms), seconds (s), minutes (m), hours (h) or days (d).
If you enter a value of 0s, you turn off that setting. Time values which are greater than the default will increase the time between reloading and reduce the load on the server, but will increase the chance that information is stale.
The three types of identities that get cached on the Server are User, Group, and Role.
The CacheTimeout is set to when the cached properties expire. After the configured time period has expired, the server resolves the identity with the provider.
A standard user, group or role gets resolved according to the CacheTimeout configuration. Dynamic Roles get excluded from this regular resolution and instead resolve on demand according to the dynamicCacheTimeout. When someone opens a worklist item, all dynamic Roles that are assigned the task are resolved before the server queries the current user membership (in case the user is included in the result).
The ContainersCacheTimeout setting is the time until expiration of the server cache that contains the external relational identity settings (i.e. all the groups that a user or group also belongs to).
The MembershipCacheTimeout setting is the time until expiration of the server cache that contains the internal relational identity settings (i.e. all the users within a role or group).
The resolvedExpiredIdentities setting is the period of time in which the server checks for expired identities and resolves them.
The sqlCommandTimeout setting is the maximum amount of time the calling application will wait for an identity to be cached before a timeout exception is raised.
The CacheThreadCount setting is not used at this time.
The ServerLockTimeout setting is the maximum amount of time a particular server thread should wait for a lock to be released before throwing an error that it could not acquire a lock on a particular identity for updating. If this time is exceeded, it retries once before the thread is aborted and an error is logged. The default ServerLockTimeout setting is five minutes which offers optimal server performance. It is not recommended that you set this timeout to less than 60 seconds. More than five minutes could negatively affect the server’s performance, depending on factors such as server workload and time taken for the server to update the cache from the provider. It is recommended that you contact a support representative for timeout period recommendations.

Identity.Identity table

This table stores the cache expiration information for users, groups, and roles. You can force a cache expiration by changing the datetime value.

For every item there are three different expiration timestamp fields (ExpireOn, MembersExpireOn and ContainersExpireOn). There are also three main methods on the Identity Service (GetIdentity, GetIdentityMembers, and GetIdentityContainers). These relate to the three expiry timestamp fields mentioned above:

ExpireOn is updated if the GetIdentity method is called (e.g. a Get User Details call on UMUser SmartObject).
MembersExpireOn is updated when GetIdentityMembers is called. (e.g. Get Group Users call on UMUser SmartObject).
ContainersExpireOn is updated when GetIdentityContainers is called (e.g. OpenWorklist call). This returns all the groups and roles for a user and recursively gets roles and groups for each of the direct containers.

For a group, notice that the MembersExpireOn and ExpireOn fields are refreshed when a group is requested to be resolved (for example, when a new task is assigned to the group (it refreshes the group membership and group properties respectively), or an Email event that sends an email to the group). Other possibilities include the UMUser SmartObject when executing the GetGroupUsers method. On the other hand, when accessing your worklist, the user’s ExpireOn and the ContainersExpireOn fields are refreshed. ExpireOn refreshes the identity Properties XML field and ContainersExpireOn refreshes the groups and roles that the user belongs to. The MembersExpireOn field does not change and its value originates from the first time the Identity Service is used for the user.

If you want to refresh the cache items, set all three expiry dates to some time in the past for the each identity.

There is a Dynamic flag for each identity but it only applies to system roles. If you set it to True, the CacheTimeout setting is ignored and instead uses the dynamicCacheTimeout settings (30s by default). Queries are queried every 30 seconds. This is useful for keeping worklist items current when users are removed from or added to a K2 role. However, there is a performance impact when identities are resolved because dynamic identities are refreshed before members or containers are selected.

Do not delete values from the Identity.Identity table. Other product components rely on the ID’s in this table. This is also where the system roles are saved. If you delete the records, the actual roles are deleted as well.

Identity.IdentityMember table

This table contains the relationship of groups and roles and their members (i.e. a many-to-many relationship). In the Identity.IdentityMember table, both the ContainerID and MemberID columns link back to the Identity.Identity table ID primary key column. The ID of the user is stored instead of the user name for performance reasons.

As of K2 Five (5.1), new memberships get stored in the Authorization.RoleMember table.

Authorization.Role table

The Authorization.Role table includes all roles you create or are created by the installer or the system. This table as shown below contains the information defined for every system role.

The table contains records that are also shown in Management.

Editing the K2 database can have serious, unexpected consequences that can cause system instability or break K2 components. You should not edit the K2 database unless you are familiar with the procedure and tools to do so, and K2 strongly recommends backing up your K2 database before making any changes. Making unauthorized changes to your K2 database may put your K2 environment into an unsupported state.