ESF supports caching (remembering) the results of some security requests. This can improve performance, sometimes dramatically, by eliminating some calls to the configured Security Managers.
There are two types of ESF caching. The ESF manager itself can cache results. When a request matches one in the ESF cache, the ESM modules are not called, and the cached result is returned. ESF also has a mechanism for ESM modules to cache information that may be expensive to retrieve, but currently no ESM modules make use of that feature. That means caching is only active if it is enabled in the ESF configuration, not in the security manager configuration.
By default, ESF caching is disabled. If you enable caching, then by default the results of Auth and XAuth requests (resource access requests) are cached, when the result is either "explicitly allowed" or "explicitly denied". Auth/XAuth requests that result in an "unknown" status, because no ESM has a rule that governs that access request, are not cached, regardless of whether the access is ultimately granted. (The setting of the "Allow unknown resources" option in the ESF configuration determines how those requests are handled.)
Also, Verify (user sign-on) requests are not cached by default, even when caching is enabled.
There are advanced configuration settings you can use to enable or disable the caching of particular types of requests. Some requests can never be cached, including Verify requests that involve passtokens.
When a request is processed by retrieving an entry from the cache, it is not passed to the ESM modules, which means it is not seen by the ESM. Sometimes ESMs do more than simply allow or deny security requests. These are called "side effects". For example, some ESMs keep track of the last time a user logged in; that's a side effect. If a Verify request is answered from the cache, the ESM will not be told to update the last-login time.
Side effects are commonly used with Verify requests, which is why they are not cached by default. If you enable Verify caching, be aware of any side effects that would normally occur in your ESM(s).
Similarly, if your ESM has side effects for resource access control that are useful to you, such as usage counts, be aware you'll lose these if you enable caching.
One configuration setting, flush on change, may be useful for organizations that only care about user-account locking. Many ESMs will lock a user account after a certain number of failed attempts to sign on. If a user does sign on successfully after a failed attempt (but not so many attempts that the account is locked), then the count of failed attempts is reset to zero. For this to work with caching, the ESM must see the successful Verify request, which means it must not be retrieved from the cache.
The "flush on change" setting tells ESF to discard a cached Verify request if it sees a Verify request with a different result for the same user. For example, assuming Verify caching and flush-on-change are enabled:
# Bob signs on to his account. The request is sent to the ESM, and the result is cached. # Bob signs off, then signs on again. The cache is used to validate this attempt. # Bob signs off, then tries to sign on again, but mistypes his password. This doesn't match the cached request, so it's sent to the ESM. The ESM returns a "denied" result, and sets Bob's failed sign-on attempt count to 1. # The flush-on-change setting sees this is a Verify request for Bob, but with a different result, so it removes the old successful Verify entry from the cache. # Bob tries again, and types his password correctly this time. Since his previous attempt flushed his successful Verify from the cache, this request also goes to the ESM. The ESM returns an "allow" result and sets his failed count back to 0.
If flush-on-change had not been enabled, the final successful Verify would have been processed using the cache, and Bob's failed-attempt count would still be 1. If Bob repeated this pattern a few times, he'd be locked out, even though he'd signed on successfully between each failed attempt.
There are two main parameters for enabling caching. They can be found on the ESF configuration pages in the Micro Focus Enterprise Server Administration user interface: the Default ES Security and MFDS Security tabs in the Security section, and the Security tab for each individual server (which overrides the Default ES Security settings). The two parameters are:
The best values for these parameters depend on your particular application mix. If your applications use many different MSS resources, they may benefit more from a larger cache, but larger caches also take longer to search.
A 16 KB cache limit and 60-second TTL are generally a good starting point.
Some additional caching parameters can be controlled with settings in the "Configuration Text" area of the security configuration tab. All of these are entered in the optional [Cache] section.
The requests setting specifies what types of ESF requests can be cached. It is set to a list of tokens, separated by commas or spaces. The possible tokens are:
auth-allow auth-deny auth-unknown auth verify-allow verify-deny verify xauth-allow xauth-deny xauth-unknown xauth The default is requests=auth xauth.
Set flush on change to yes or 1 to tell the cache that it should discard any cached Verify result if it sees another request for the same user with a different result. See Using Flush on Change for more information. This is only useful when Verify caching is enabled.
Periodically, processes that use ESF will report some statistics about the cache, such as how many entries are in use and what percentage of requests are fulfilled using the cache (the cache "utilization" or "hit rate"). The information is reported as an ESF message, so it will appear in the console log (for CAS processes) or the MFDS journal. By default, this happens about every hour, though processes will only report it when an ESF request is made, so idle processes (e.g. SEPs that are never used) won't report.
You can configure how often this reporting happens by setting the report interval option. Its value is an integer, representing the approximate time between reports in seconds. Setting this to 0 disables reporting.
[Cache]
# Enable Verify caching, as well as Auth and XAuth, including the result of
# requests for unknown resources
requests=verify, auth, xauth, auth-unknown, xauth-unknown
# Discard Verify result when a different request for the same user is processed
flush on change=yes
# Report cache statistics about every half-hour (1800 seconds)
report interval=1800