Caching
Web Agents Documentation supports the following caches to speed up agent operations:
Configuration cache
The configuration cache stores web agent configuration properties.
When a Web Agents Documentation starts up, it either makes a call to AM to retrieve a copy of the agent profile (centralized configuration mode) or reads the agent profile from the local configuration file (local configuration mode). Then, the agent stores the configuration in its cache. The cached information is valid until one of the following events occur:
-
AM notifies the agent of changes to hot-swappable agent configuration properties. This only applies to deployments that use centralized configuration mode.
-
The information in the cache reaches the expiration time specified by Configuration Reload Interval.
When a configuration property in the cache is invalid, the agent clears the cached property value and rereads it from the agent profile.
Session and policy decision cache
Stored in the shared memory pool defined by the AM_MAX_SESSION_CACHE_SIZE
environment variable, the session and policy decision cache stores session
information, and the results of previous policy decisions.
The default size of the cache is 16 MB, but you may need to increase its size if you plan to hold many active sessions in the cache at any given time. For more information about the environment variable, refer to Environment variables.
After authentication, AM presents the client with an ID token containing session information. The web agent stores part of that session information in the cache. When a client attempts to access a protected resource, the agent checks whether there is a policy decision cached for the resource:
-
If there is a cached policy decision, the agent reuses it without contacting AM.
-
If there is no cached policy decision, the validity of the client’s session determines the agent’s behavior:
-
If the client’s session is valid, the web agent requests a policy decision from AM, caches it, and then enforces it.
-
If the client’s session is not valid, the agent redirects the client to AM for authentication regardless of why the session is invalid. The agent does not specify the reason why the client needs to authenticate.
After the client authenticates, and the session is cached, the agent requests a policy decision from AM, caches it, and then enforces it.
Session and policy decisions are valid in the cache until one of the following events occur:
-
| Event | What is invalidated? |
|---|---|
Session contained in the ID token expires |
Session and policy decisions related to the session |
Client logs out from AM (and session notifications are enabled) |
Session and policy decisions related to the session |
Session reaches the expiration time specified by SSO Cache Polling Period. |
Session |
Policy decision reaches the expiration time specified by Policy Cache Polling Period. |
Policy decision |
Administrator makes a change to policy configuration (and policy notifications are enabled) |
All sessions and all policy decisions |
| A Web Agents Documentation that loses connectivity with AM cannot request policy decisions. Therefore, the agent denies access to inbound requests that do not have a policy decision cached until the connection is restored(*). |
Policy cache
The policy cache builds upon the session and policy decision cache. It downloads and stores details about policies from AM, and uses the downloaded policies to make authorization decisions, without contacting AM each time.
Web Agents Documentation uses the policy cache without contacting AM in the following situations:
-
A requested resource matches the resource pattern of a policy that has been cached due to a previous evaluation.
-
A requested resource does not match a pattern of policy rules downloaded locally. In this case, the agent denies access.
-
A requested resource matches the resource pattern of a simple policy that applies to the
All Authenticated Usersvirtual group.If the resource matches the policy used for a previous policy decision, the agent does not request policy evaluation from AM. Therefore, policy conditions based on scripts, LDAP filter conditions, or session properties, which rely on attributes that can vary during a session, may not be enforced.
To reduce this risk, you should:
-
Enable session property change notifications, as described in Notifications.
-
Reduce the amount of time that sessions can remain in the agent session cache.
Consider the following caveats when using the policy cache:
-
If you have a large number of policies, for example more than one million in an UMA deployment, the time to download the policies and the memory consumption of the agent may affect performance.
-
The agent downloads the policy rules, and uses them to evaluate policies locally. If a policy is customized in AM in a way that changes the way it is evaluated (for example, a wildcard or delimiter is changed), the policy decision made by the agent might not match the policy defined in AM.
-
Even though delimiters and wildcards are configurable in AM (Configure > Global Services > Policy Configuration > Global Attributes > Resource Comparator), the policy cache supports only the default configuration.
Do not enable the agent’s policy cache if your policies use custom delimiters and/or wildcards.
Enable the policy cache by creating an environment variable named
AM_POLICY_CACHE_MODE.
Change the location of the policy cache by creating an environment variable named
AM_POLICY_CACHE_DIR.
For more information about properties related to the policy cache, refer to Environment variables.