Authentication and group cache

A new cache for both User ID and Password based authentication, and group plug-ins has been introduced to relieve pressure on backend authentication mechanisms.

Attention: This feature is available in Db2® Version 11.5 Mod Pack 3 and later versions.
The authentication portion of the cache will store information about successful authentications and compare the information from new, incoming authentication requests against the cached entries to see if a valid match is found. If the match is found, the new authentication request is considered successful and subsequent Db2 post-authentication processing begins.

This cache will only be applied to authentication requests associated with CONNECT requests that provide passwords for authentication. The cache exists at each database member that receives CONNECT requests, and the cache contents are independent of the contents of the cache at any other database member.

The group portion of the cache will store a list of any external groups associated with a given User ID. This list is normally returned as part of the authentication process. If a match for a User ID is found in the group cache, the cached list of groups is returned and external group lookup is skipped.

Cache benefits

Enabling the cache is most beneficial when the authentication service for a Db2 instance is on a remote host and there is no caching locally on the server. Overhead of the network communication and overloading the authentication service can lead to significant delays when authenticating with the Db2 server, which results in slower connects. Using the ldap security plugin falls into this category.


Both database configuration parameters for the authentication cache can be configured online and do not require the database to be deactivated and reactivated.

The number of entries to be cached is determined by the user and indicated by a new database configuration parameter. When the number of cached entries reaches the configured maximum value, any new entry to be cached will force the eviction of an existing cache entry.

See the parameter AUTHN_CACHE_USERS for more information.

The duration of time when a cached entry is considered valid for comparison is determined by the user and indicated by a new database configuration parameter. This duration begins when the cached entry is first entered into the cache; once the duration is exceeded, the entry is no longer considered valid for comparison against new requests and can be evicted.

See the parameter AUTHN_CACHE_DURATION for more information.

Cache monitoring and performance

The MON_GET_CONNECTION table function contains several metrics associated with the active connections for a given database. One of these metrics, total_connect_authentication_time, measures how long authentication took for a given connection. If the value for total_connect_authentication_time goes down once the cache is enabled, then the cache is working.

The MON_GET_DATABASE table function contains several metrics associated with the authentication cache itself.

AUTHN_CACHE_LOOKUPS measures how many times the cache is searched for an entry. AUTHN_CACHE_HITS, alternatively, measures how many times the Db2 server was able to find a valid entry corresponding to a given user. The efficiency of the cache can be defined by how often the server finds valid authentication information in the cache every time the server accesses it during authentication. The cache efficiency or hit ratio can be calculated by (AUTHN_CACHE_HITS / AUTHN_CACHE_LOOKUPS).

If the hit ratio of the cache is low, there could be two reasons:

  1. If the cache size is too small, this leads to constant eviction of valid entries. This lowers the probability of finding cached authentication information for a given user.
  2. The period for which an entry is valid in the cache before that user must be reauthenticated is too short. This means entries are expiring too fast. In this case, if matching authentication information is found for a connecting user, it cannot be used because it is expired.

The AUTHN_CACHE_EXPIRED_EVICTIONS monitoring metric counts how many times the system evicted an expired entry from the cache. The AUTHN_CACHE_VALID_EVICTIONS metric counts the number of evictions of entries that were still valid at the time of eviction. If the value of AUTHN_CACHE_EXPIRED_EVICTIONS is growing faster than that of AUTHN_CACHE_VALID_EVICTIONS, it implies that the maximum duration an entry is valid in the cache is too short and should be increased. If it is the opposite, then the cache is too small and increasing its size could improve the cache efficiency.

Password and group membership changes

Db2 is unaware when the password or group membership of a given user changes, therefore, any entries in the cache containing stale information are still considered valid until they expire. In such a situation, a stale group list may be returned, or authentication with an old password may be returned.

If a user’s password is changed and authentication is attempted with the new password, a stale entry present in the cache will be updated and any future authentications with that new password will be handled by the cache.

If a user’s group membership changes, the entry must expire, be evicted, or be flushed before the cache can store updated group information.

To immediately invalidate all entries and flush the cache, the FLUSH AUTHENTICATION CACHE statement can be run. See FLUSH AUTHENTICATION CACHE for more information.