Tune caching

AM caches data to avoid having to query user and configuration data stores each time it needs the information. By default, AM makes use of LDAP persistent search to receive notification of changes to cached data. For this reason, caching works best when data are stored in a directory server that supports LDAP persistent search.

AM has two kinds of configurable cache on the server side; one for configuration data and one for user data. You can generally use the default settings for configuration data cache. This section covers the configuration choices available for caching user data.

AM implements the global user data cache for its user data stores.

The user data store also supports a DN cache, used to cache DN lookups that tend to occur in bursts during authentication. The DN cache can become out of date when a user is moved or renamed in the underlying LDAP store, events that are not always reflected in a persistent search result. You can enable the DN cache when the underlying LDAP store supports persistent search and mod DN operations (that is, move or rename DN).

The following diagram depicts the two kinds of cache, and also the two types of caching available for user data:

Servers cache user data and configuration data separately.

Figure 1. Caches

The rest of this page concerns mainly settings for global user data cache and for SDK clients. For a look at data store cache settings, refer to Tune LDAP connectivity.

Overall server cache settings

By default, AM has caching enabled for both configuration data and user data. This setting is governed by the server property com.iplanet.am.sdk.caching.enabled, which is true by default. If you set this advanced property to false, you can enable caching independently for configuration data and for user data.

Turn off global user data caching

Disabling caching can have a severe negative impact on performance. This is because when caching is disabled, AM must query a data store each time it needs data.

If, however, you have at least one identity store that does not support LDAP persistent search, then you must disable the global cache for user data. Otherwise, user data caches cannot stay in sync with changes to user data entries:

In the AM admin UI, go to Deployment > Servers > Server Name > Advanced.
Set the value of the com.iplanet.am.sdk.caching.enabled property to false to disable caching overall.

Set the value of the com.sun.identity.sm.cache.enabled property to true to enable configuration data caching.

All supported configuration data stores support LDAP persistent search, so it is safe to enable configuration data caching.

You must explicitly set this property to true, because setting the value of the property com.iplanet.am.sdk.caching.enabled to false in the previous step disables both user and configuration data caching.

Save your work.
AM starts persistent searches on user data stores when possible⁽¹⁾ in order to monitor changes.

With user data store caching disabled, AM still starts the persistent searches, even though it no longer uses the results.

Therefore, if you disable user data store caching, you should also disable persistent searches on identity stores in your deployment to improve performance.

To disable persistent search on an identity store, go to Realms > Realm Name > Identity Stores > Identity Store Name > Persistent Search Controls and remove the value of the Persistent Search Base DN configuration property (leave it blank).

⁽¹⁾ AM starts persistent searches on user data stores on directory servers that support the psearch control.

Change the maximum size of the global user data cache

With a large user data store and active user base, the number of user entries in cache can grow large.

In the AM admin UI, go to Configure > Server Defaults > SDK.
Change the value of SDK Caching Maximum Size.

There is no corresponding setting for configuration data, because the number of configuration entries in a large deployment is not likely to grow nearly as large as the number of user entries.

Clear the configuration cache

When you change configuration property values, the old value remains in effect until the affected service is restarted. To avoid having to restart AM when you change a property value, you can clear the configuration cache and force the new property value to take effect.

To clear the configuration cache, send an empty POST request to the /json/cache endpoint with the clear action, for example:

$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "iplanetDirectoryPro: kYQVVJ2YFCuAe-b1xjm7evGBDkw.AAJTSQACMDEAAlNLABxQS0ZIYzBPeFVWUzBQOTNLaHV0elVQemdqVU09AAR0eXBlAANDVFMAAlMxAAA.	" \
--header  "Accept-API-Version: resource=1.0" \
--data '{}' \
https://openam.example.com:8443/openam/json/cache?_action=clear
{}

Only members of a group with the Realm Admin or Cache Admin privilege can run this operation to clear the cache. All attempts to access the endpoint are audited, including information about the user that attempted to clear the cache.

Cache settings

The table below provides a quick reference, primarily for user data cache settings.

Notice that many properties for configuration data cache have sm (for Service Management) in their names, whereas those for user data have idm (for Identity Management) in their names:

Cache properties
Property	Description	Default	Applies to
`com.iplanet.am.sdk.cache.maxSize`	Maximum number of user entries cached.	10000	Server and SDK
`com.iplanet.am.sdk.caching.enabled`	Whether to enable caching for both configuration data and also for user data. If `true`, this setting overrides `com.sun.identity.idm.cache.enabled` and `com.sun.identity.sm.cache.enabled`. If `false`, you can enable caching independently for configuration data and for user data using the aforementioned properties.	`true`	Server and SDK
`com.iplanet.am.sdk.remote.pollingTime`	How often in minutes the SDK client, such as a web or a Java agent, should poll AM for modified user data entries. The SDK also uses this value to determine the age of the oldest changes requested. The oldest changes requested are 2 minutes older than this setting. In other words, by default the SDK polls for entries changed in the last 3 minutes. Set this to 0 or a negative integer to disable polling.	1 (minute)	SDK
`com.sun.am.event.notification.expire.time`	How long AM stores a given change to a cached entry, so that clients polling for changes do not miss the change.	30 (minutes)	Server only
`com.sun.identity.idm.cache.enabled`	If `com.iplanet.am.sdk.caching.enabled` is `true`, this property is ignored. Otherwise, set this to `true` to enable caching of user data.	`false`	Server and SDK
`com.sun.identity.idm.cache.entry.default.expire.time`	How many minutes to store a user data entry in the global user data cache.	30 (minutes)	Server and SDK
`com.sun.identity.idm.cache.entry.expire.enabled`	Whether user data entries in the global user data cache should expire over time.	`false`	Server and SDK
`com.sun.identity.idm.remote.notification.enabled`	Whether the SDK client, such as a web or a Java agent, should register a notification listener for user data changes with the AM server. The SDK client uses the URL specified by `com.sun.identity.client.notification.url` to register the listener so that AM knows where to send notifications. If notifications cannot be enabled for some reason, then the SDK client falls back to polling for changes.	`true`	SDK
`com.sun.identity.sm.cache.enabled`	If `com.iplanet.am.sdk.caching.enabled` is `true`, this property is ignored. Otherwise, set this to `true` to enable caching of configuration data. It is recommended that you always set this to `true`.	`false`	Server and SDK
`sun-idrepo-ldapv3-dncache-enabled`	Set this to `true` to enable DN caching of user data.	`false`	Server and SDK
`sun-idrepo-ldapv3-dncache-size`	Sets the cache size.	`1500`	Server and SDK

AM 7.3.1