WebSphere authentication cache works the same way in both traditional WebSphere and Liberty. From time to time, customers ask how the authentication cache works internally. This blog shares the top 5 frequently asked questions.
The authentication cache overview
The WebSphere authentication cache helps improve the performance by reducing the number of the user registry access. At the initial login, WebSphere authenticates the user by validating the credential with the user registry (LDAP, Database, etc) and creates a Subject. In the subsequent logins, WebSphere retrieves the Subject from the authentication cache. The cache entries expire after some time so WebSphere periodically make sure the user is valid in the registry.
The default values of the authentication cache are the same for
Traditional WebSphere,
WebSphere Liberty and
Open Liberty. For more details, follow the link to see the configuration page.
- Authentication Cache: Enabled
- Cache timeout: 10 minutes
- Initial cache size: 50 entries
- Maximum cache size: 25000 entries
- Use basic authentication cache keys (password one-way hashed) : Enabled
Q1: What are the lookup keys for the authentication cache?
At the time of the initial login, multiple keys are created for the authentication cache lookup. The type of the keys depends on the login type. For example, when a certificate login happens, the hash of the certificate and the LtpaToken are the lookup keys. The keys are associated with the same Subject object in the cache.
Optionally, the developers can specify a custom cache key of their choice in the custom Trust Association Interceptor code or custom Login Module code.
Following is the example of the keys. They are created depending on the type of login :
- Realm + user + hash(password)
- Realm + user
- Realm + loginUID
- Realm + unique security name
- SSL Certificate
- Credential Token
- SingleSignOn Token (LTPA, JWT, SAML..)
- TAI Cache Key
- CSIv2 Session Key
- z/OS Authentication Data
- Subject Unique ID
- Custom cache key (The developers optionally provides the key in the code)
Q2: Our LDAP administrator changed a user's password. After 10 minutes (or the cache timeout period), the user can still login to WebSphere with the old password. Why?
It is possible that the authentication cache entry stays a little longer than the cache timeout. Following is the reasons:
The authentication cache consists of three tables (Primary, Secondary, Tertiary) internally. There is an internal alarm set to go off at half of the timeout value to move the entries from one table to another until the entry gets purged. For the default timeout value 10 minutes, the alarm interval is 5 minutes.
As we see in the picture below, at the third alarm, the entry is purged from the cache. So the actual timeout for the entry varies between timeout ~ timeout x 1.5 (10 ~ 15 minutes) If the timeout value is set to a larger value, the range of timeout value expands. It is recommended that the timeout value is chosen carefully so the authentication cache helps improve the performance while the user validation is triggered at a reasonable interval.
The cache entry is not always moved from the Primary to Secondary to Tertiary. If the cache entry is frequently looked up, the entry gets moved to the Primary Table for the best user experience.
Q3: How do we make the password change effective immediately?
Yes. For Traditional WebSphere, the password change can be immediately reflected if
"Use basic authentication cache keys (password one-way hashed)" is disabled in the adminconsole (Security > Global security > Authentication cache settings). The same setting can be achieved by setting the security custom property "
com.ibm.websphere.security.util.authCacheEnabled" to "
BasicAuthDisabled" (
Security > Global security > Custom properties) In Liberty, the equivalent setting is to configure
allowBasicAuthLookup as false : <authCache allowBasicAuthLookup="false"/>
The setting keeps WebSphere from looking up with the userid and password hash. As a result, userid/password login is always evaluated with the user registry. There is performance trace off with this setting since the authentication cache is not used for the basicauth login.
Q4: What happens if the authentication cache becomes full?
When the authentication cache is full, WebSphere removes all the entries in the Tertiary Table in the cache since they have been around without being looked up.
In Traditional WebSphere, following warning is printed: "
SECJ0430W: The authentication cache currently has X entries which has exceeded the maximum size of Y. The cache cleanup algorithm will remove some entries. Consider increasing the maximum cache size. " In Liberty, following trace is printed: "
The cache size is X (a,b,c) which is greater than the cache limit of Y".
The number of the cache entries can be found in the trace. It is printed when the cache alarm goes off at the timeout interval periodically. For the Traditional WebSphere, the trace option is "com.ibm.ws.security.auth.Cache=*" and the trace output looks like "The current cache size is 100 (50, 25, 25)" . For Liberty, the trace option is "com.ibm.ws.security.authentication.internal.cache.Cache=*" with the same output.
The each table in the authentication cache (Primary, Secondary Tertiary) holds the maximum entries (25000 by default) so the total cache entries could be up to maximum size x 3.
Q5: Is there a way to calculate the memory usage for the authentication cache?
Unfortunately, it is not an easy to calculate the cache size with pen and paper. One reason is the size of the Subject varies depending on the user's information. For example, if a user belongs to thousands of groups, the user's Subject becomes large with the group information. Another reason is, the number of cache entries fluctuates depending on the business peak/off-peak time.
The best way to find the authentication cache size is to take the Java heapdump and analyze it using the memory analyzer tools.
The Eclipse Memory Analyzer Tool (MAT) is a free and opensource Java heapdump analysis tool.
IBM also provides free extensions to MAT called the IBM Extensions for Memory Analyzer that provide product-specific queries on top of MAT for products such as WebSphere Application Server and others. For more details, please refer to IBM WebSphere Server Performance Cookbook.