FAQ: Caching in AM

Frequently asked questions

• Q. How can I control caching for configuration and user data using ssoadm?
• Q. How does LDAP persistent search affect caching?
• Q. Is there a recommended Maximum Session Cache Size?
• Q. How long is the Certificate Revocation List (CRL) held in the cache?

Q. How can I control caching for configuration and user data using ssoadm?

A. There are three properties available for enabling or disabling caching for configuration and user data stores:

• com.iplanet.am.sdk.caching.enabled - enables caching for both the configuration and user data stores. The following properties are ignored when this is set to true.
• com.sun.identity.idm.cache.enabled - enables caching for the user data store (IdRepo cache).
• com.sun.identity.sm.cache.enabled - enables caching for the configuration data store (service configuration caching).

See Cache settings for further information about these properties and other cache-related properties, including time-based expiration. This guide also provides steps for setting these advanced properties in the AM admin UI.

You can set these properties to true or false using the update-server-cfg command. For example, the following command enables caching for the user data store only:

• AM 7 and later: $ ./ssoadm update-server-cfg -s default -u uid=amAdmin,ou=People,dc=am,dc=forgerock,dc=org -f pwd.txt -a com.iplanet.am.sdk.caching.enabled=false com.sun.identity.idm.cache.enabled=true com.sun.identity.sm.cache.enabled=false
• AM 6.x: $ ./ssoadm update-server-cfg -s default -u amadmin -f pwd.txt -a com.iplanet.am.sdk.caching.enabled=false com.sun.identity.idm.cache.enabled=true com.sun.identity.sm.cache.enabled=false

Time-to-Live

If caching is enabled for either of these stores, you can also set the following properties using the above ssoadm command:

• com.sun.identity.sm.cache.ttl.enable - determines if entries in the configuration store cache are expired based on time-to-live (TTL). This is set to false by default.
• com.sun.identity.sm.cache.ttl - specifies the time to live in minutes when the above property is set to true. This is set to 30 by default; when TTL is enabled, entries will remain in the cache for 30 minutes after their last modification. After 30 minutes, the data in these entries will expire and further requests for the data will be retrieved from the configuration store.
• com.sun.identity.idm.cache.entry.expire.enabled - determines if entries in the user data store cache are expired based on time-to-live (TTL). This is set to false by default.
• com.sun.identity.idm.cache.entry.default.expire.time - specifies the time to live in minutes when the above property is set to true. This is set to 30 by default; when TTL is enabled, entries will remain in the cache for 30 minutes after their last modification. After 30 minutes, the data in these entries will expire and further requests for the data will be retrieved from the user data store.

These properties can also be set using the update-server-cfg command.

Q. How does LDAP persistent search affect caching?

A. AM uses LDAP persistent search to receive notifications of changes to cached data. However, operational attributes such as the isMemberOf attribute (DS data store) or the memberOf attribute (Active Directory data store) are not updated by the persistent search mechanism as they are computed dynamically. For use cases where you need to be notified of user membership changes, configuring your user data store to expire caches based on TTL is a valid option. See the Solution in isMemberOf attribute does not return current group membership details for a user in AM (All versions) for other options.

Unless all your user data stores support LDAP persistent search, you should disable the global cache for user data stores. When caching is enabled for user data stores that do not support LDAP persistent search, user data caches do not stay in sync with changes to user data. See Turn off global user data caching for further information on disabling the global cache.

Additionally, you should also set Persistent Search Base DN (sun-idrepo-ldapv3-config-psearchbase) to blank in the user data stores that do not support persistent search to disable persistent search.

See Identity stores​ for further information on making changes to individual data stores.

Q. Is there a recommended Maximum Session Cache Size?

A. No, this will depend on your setup. This setting specifies the maximum number of sessions to cache in each AM server’s internal session cache. The cache is an LRU (Least Recently Used) cache, which evicts the least used session (usually the first session to be added to the cache) when this maximum session cache size value is reached. For example, with the default size value of 5000: if there are 5000 active sessions within a single AM, when session 5001 arrives, session 1 is evicted. Until then, all sessions remain in the cache until modified and/or deleted.

This setting applies to each server, and assuming sticky load balancing has been applied, a guide to setting this appropriately is to take the maximum number of active sessions at any one time divided by the number of available AM instances.

Q. How long is the Certificate Revocation List (CRL) held in the cache?

A. Once the CRL is read by AM, it is held in the cache until AM is restarted or until it is updated in the LDAP directory.

It can only be updated in the LDAP directory if the Update CA CRLs from CRLDistributionPoint option (openam-am-auth-cert-update-crl) is enabled. When this option is enabled, AM checks the nextUpdate date field in the CRL each time it uses it. Once this date has passed, AM fetches new CA CRLs from the CRLDistributionPoint and updates the CRL held in the LDAP directory.

See How do I configure certificate-based authentication in AM (All versions)? and Certificate authentication module properties for further information on these settings.

See Also

FAQ: AM performance and tuning

Performance tuning and monitoring ForgeRock products

Tune caching