Web Policy Agents 5.9.1

Features

Multiple Sites and Virtual Hosts

Web Agent instances can be configured to operate with multiple websites in IIS, and with multiple virtual hosts in Apache.

Each configuration instance is independent and has its own configuration file, debug logs, and audit logs. Each instance can connect to a different AM realm, or even different AM servers.

For more information, see Installing Apache Web Agents on a Virtual Host and Installing the IIS Web Agent.

SSO-Only Mode

Web Agent intercepts all inbound client requests to access a protected resource and processes the request based on the Enable SSO Only Mode property.

The configuration setting determines the mode of operation that should be carried out on the intercepted inbound request, as follows:

  • When true, the agent manages user authentication only. The filter invokes the AM Authentication Service to verify the identity of the user. If the identity is verified, the user is issued a session token through AM’s Session Service.

  • When false, which is the default, the agent also manages user authorization, by using the policy engine in AM.

Not-Enforced Rules

Not-enforced rules are configured in the Application tab of the AM console. Rules that apply an HTTP method filter are configured as Custom Properties, in the Advanced tab.

When a not-enforced rule applies to a request, the request is processed without authentication. Configure lists of the following not-enforced rules:

Not-enforced URL rules

Allow access to resources, such as images, stylesheets, or the HTML pages that provide the public front end of your site. See Not-Enforced URL List.

Not-enforced IP rules

Allow access to your site from an administrative IP address, an internal network range, or a search engine. See Not-Enforced IP List.

Compound not-enforced rules

Allow access to listed IP addresses when requesting the listed URLs. See Not-Enforced URL from IP Processing List.

When there are multiple lists of rules, the Web Agent evaluates them in this order:

  1. Compound not-enforced rules

  2. Rules in not-enforced IP lists

  3. Rules in not-enforced URL lists

The following image shows the data flow when Web Agent evaluates not-enforced rules for a request:

not-enforced-flow

1. A client requests a resource.

2. The Web Agent checks whether the request matches a rule in a not-enforced list.

The Web Agent evaluates every rule in the lists in order, until it finds the first match. When it finds a match, it stops evaluating, and does not consider other rules further down the list even if they provide a better match. Take care to place your most specific rules at or near the beginning of the list.

3-4. The Web Agent passes the request without requiring the client to authenticate.

5-9. If the request doesn’t match a rule in a not-enforced list, the Web Agent checks whether it matches a not-enforced URL rule that is inverted. If so, the Web Agent passes the request without requiring the client to authenticate.

Conventions for Not-Enforced Rules

Use the conventions in this section to define not-enforced rules:

Invert All Rules

Invert all rules in a not-enforced URL list by setting Invert Not-Enforced URLs to true.

Consider the following points when you invert all rules:

  • If Not-Enforced URL List is empty, all URLs are enforced.

  • At least one URL must be enforced. To allow access to any URL without authentication, consider disabling the agent.

Wildcard for not-enforced IP rules

Add * to match all characters in a rule, except the question mark ? character. The wildcard cannot be escaped.

The following example does not require authentication for any request method to 192.168.10.*:

com.sun.identity.agents.config.notenforced.ip[1]=192.168.10.*

For more information about using wildcards, see Specifying Resource Patterns with Wildcards.

Wildcards for not-enforced URL rules

  • Add * to match all characters in a rule, except the question mark ? character. The wildcard cannot be escaped.

    The wildcard spans multiple levels. For example:

    com.sun.identity.agents.config.notenforced.url[1]=http://www.example.com:8080/images/*
com.sun.identity.agents.config.notenforced.url[2]=http://www.example.com:8080/*.jsp?locale=*

    Multiple forward slashes do not match a single forward slash. Therefore, * matches mult/iple/dirs, but mult/*/dirs does not match mult/dirs.

  • Add -*- to match all characters in a rule, except the forward slash / and the question mark ? character. The wildcard cannot be escaped. Because this wildcard does not match the / character, it does not span multiple levels in a URL. For example:

    com.sun.identity.agents.config.notenforced.url[1]=http://www.example.com:8080/css/-*-

  • * and -*- wildcards cannot be used in the same rule, but can be used in different rules in the same list. For example:

    com.sun.identity.agents.config.notenforced.url[1]=http://www.example.com:8080/css/-*-
com.sun.identity.agents.config.notenforced.url[2]=http://www.example.com:8080/images/*

  • Multiple wildcards in the query parameter section of a not-enforced URL rule match the parameters in any order that they appear in a resource URL. For example, the following not-enforced URL rule applies to any resource URL that contains a member_level and location query parameter, in any order:

    com.sun.identity.agents.config.notenforced.url[1]=http://www.example.com:8080/customers/*?*member_level=*&location=*

    In following example, the requests would be not-enforced:

    https://www.example.com/customers/default.jsp?member_level=silver&location=fr
https://www.example.com/customers/default.jsp?location=es&member_level=silver
https://www.example.com/customers/default.jsp?location=uk&vip=true&member_level=gold

    If the parameters are not present in the request, the agent evaluates the resource URL against policies in AM, as usual.

  • Trailing forward slashes are not recognized as part of a resource name. Therefore, /images// and /images are equivalent. For more information about using wildcards, see Specifying Resource Patterns with Wildcards.

Regular expressions

Set Regular Expressions for Not-Enforced URLs to true, and consider the following points for using regular expressions in not-enforced rules:

  • Wildcards and regular expressions cannot be used in the same rule.

  • Using netmask CIDR notation or IP address ranges and regular expressions is not supported. However, you can create a regular expression that matches a range of IP addresses, such as:

    com.sun.identity.agents.config.notenforced.ip[1]=192\.168\.10\.(10|\d)

  • If an invalid regular expression is specified in a rule, the rule is dropped, and an error message is logged.

HTTP Methods

Rules that apply an HTTP method filter are configured as Custom Properties in AM.

Add one or more of the following keywords to the not-enforced rule to apply it when the incoming request uses a specific HTTP method: GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE.

By default, no HTTP method is specified for a rule, and all methods are not-enforced for that rule. When one or more HTTP methods are specified, only those methods are not-enforced; methods that are not specified are enforced.

The following example does not require authentication for OPTIONS requests to your scripts, but does require authentication for other HTTP methods:

com.sun.identity.agents.config.notenforced.url[OPTIONS,1]=http://www.example.com:8080/scripts/*

To specify a list of methods, add multiple rules:

com.sun.identity.agents.config.notenforced.url[OPTIONS,1]=http://www.example.com:8080/scripts/*
com.sun.identity.agents.config.notenforced.url[TRACE,2]=http://www.example.com:8080/scripts/*

To invert a method, precede it with an exclamation point ! character. The following examples require authentication for POST requests, but not for other HTTPS methods:

com.sun.identity.agents.config.notenforced.ip[!POST,1]=192.168.1.0/24

Unrecognized keywords in a rule are ignored and do not invalidate the rest of the rule.

Compound rules

Configure compound rules in Not-Enforced URL from IP Processing List.

In the following example, the agent does not enforce HTTP requests from the IP addresses 192.6.8.0/24 to any file in /public, or any files or directories that start with the string login in the directory /free_access URI:

org.forgerock.agents.config.notenforced.ipurl[1]=192.6.8.0/24|http://www.example.com:8080/public/* /free_access/login*

Encoding non-ASCII characters in rules

Percent-encode resources that use non-ASCII characters.

For example, to match resources to the URI http://www.example.com/forstå, specify the following percent-encoded rule:

/forst%C3%A5/*

Attribute Fetch Modes

Web Agent can fetch and inject user information into HTTP headers, request objects, and cookies and pass them on to the protected client applications. The client applications can then personalize content using these attributes in their web pages or responses.

You can configure the type of attributes to be fetched, and the associated mappings for the attributes names used in AM, to those values used in the containers. The agent securely fetches the user and session data from the authenticated user, as well as policy response attributes.

For example, you can have a web page that addresses the user by name retrieved from the user profile, for example "Welcome Your-Name!". AM populates part of the request (header, form data) with the CN from the user profile, and the website consumes and displays it.

FQDN Checking

Web Agent requires that clients use valid URLs with FQDNs to access protected resources. If invalid URLs are referenced, policy evaluation can fail because the FQDN does not match the requested URL, leading to blocked access to the resource. Misconfigured URLs can also result in incorrect policy evaluation for subsequent access requests.

There are cases where clients may specify resource URLs that differ from the FQDNs stored in AM policies, for example, in load balanced and virtual host environments. To handle these cases, the agent supports FQDN Checking properties: FQDN Default and FQDN Virtual Host Map properties.

The FQDN Default property specifies the default URL with valid hostname. The property ensures that the web agent can redirect to a URL with a valid hostname should it discover an invalid URL in the client request.

The FQDN Virtual Host Map property stores map keys and their corresponding values, allowing invalid URLs, load balanced URLs, and virtual host URLs to be correctly mapped to valid URLs. Each entry in the Map has precedence over the FQDN Default setting, so that if no valid URLs exist in the FQDN Virtual Host Map property, the agent redirects to the value specified in the FQDN Default property.

If you want the agent to redirect to a URL other than the one specified in the FQDN Default property, then it is good practice to include any anticipated invalid URLs in the FQDN Virtual Host Map property and map it to a valid URL.

Web Agent can reset cookies before redirecting the client to a login page, by issuing a Set-Cookie header to the client to reset the cookie values.

Cookie reset is typically used when multiple parallel authentication mechanisms are in play with the web agent and another authentication system. The agent can reset the cookies set by the other mechanism before redirecting the client to a login page.

To set and reset secure or HTTP Only cookies, in addition to the cookie reset properties, set the relevant cookie option, as follows:

  • To reset secure cookies, enable the com.sun.identity.agents.config.cookie.secure property.

  • To reset HTTP only cookies, enable the com.sun.identity.cookie.httponly property.

If you have enabled attribute fetching by using cookies to retrieve user data, it is good practice to use cookie reset, which will reset the cookies when accessing an enforced URL without a valid session.

Cross-Domain Single Sign-On

Cross-domain single sign-on (CDSSO) is an AM capability that lets users access multiple independent services from a single login session, using the agent to transfer a validated session ID on a single DNS domain or across domains.

Without AM’s CDSSO, SSO cannot be implemented across domains; the session cookie from one domain would not be accessible from another domain. For example, in a configuration where the AM server (openam.example.com) is in a different DNS domain than the web agent (myapp.website.com), single sign-on would not be possible.

Web Agent works in CDSSO mode by default, regardless of the DNS domain of the AM servers and the DNS domain of the web agents.

For more information, see Single Sign-On and Implementing CDSSO in AM’s Authentication and Single Sign-On Guide.

Continuous Security

When a user requests a resource through AM, excluding proxies and load balancers, the Web Agent is usually the first point of contact. Because Web Agent is closer to the user than AM, and outside the firewalls that separate the user and AM, the Web Agent can sometimes gather information about the request, which AM cannot access.

When Web Agent requests a policy decision from AM, it can include the additional information in an environment map, a set of name/value pairs that describe the request IP and DNS name, along with other, optional, information. The additional information can then be included in the policy, for example, to allow only incoming requests that contain the InternalNetwork.

In AM, use server-side authorization scripts to access the environment map, and write scripted conditions based on cookies and headers in the request. For information about server-side authorization scripts, see Scripting a Policy Condition in AM’s Authorization Guide.

Environment Maps With Customizable Keys

In Web Agent, use the continuous security properties Continuous Security Cookie Map and Continuous Security Header Map to configure an environment map with the following parts:

requestIp

The IP address of the inbound request, determined as follows:

  • If Client IP Address Header is configured, Web Agent extracts the IP address from the header.

  • Otherwise, Web Agent uses the container’s connection information to determine the client IP address.

This entry is always created in the map.

requestDNSName

The host name address of the inbound request, determined as follows:

  • If Client Hostname Header is configured, Web Agent extracts the host name from the header.

  • Otherwise, Web Agent uses the container’s connection information to determine the client’s host name.

This entry is always created in the map.

Other variable names

An array of cookie or header values. An entry is created for each value specified in the continuous security properties.

In the following example, the continuous security properties are configured to map values for the ssid cookie and User-Agent header to fields in an environment map:

org.forgerock.openam.agents.config.continuous.security.cookies[ssid]=mySsid
org.forgerock.openam.agents.config.continuous.security.headers[User-Agent]=myUser-Agent

If the incoming request contains an ssid cookie and a User-Agent header, the environment map takes the value of the cookie and header, as shown in this example:

requestIp=192.16.8.0.1
requestDnsName=client.example.com
mySsid=77xe99f4zqi1l99z
myUser-Agent=Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko

Login Redirect

When an unauthenticated user requests access to a protected resource, the agent redirects the user to log in. The login redirect can be to a specific AM instance, an AM site, or a website. For example, a user can be redirected from the france.example.com domain to log in to the am.france.example.com AM site.

Default login redirects use OpenID Connect ID tokens as session tokens, and the AM UI end user pages to log in users. Use default login redirect for all new deployments.

Custom login redirects support environments with custom login pages, that are upgrading from Web Agents 4.x. Custom login redirects let the agent use AM-specific SSO tokens as session tokens. Use conditional login redirects to use the request URL as a criteria for redirects to different AM instances or sites, or authentication realms.

Configure login redirect options as follows:

Login Redirect Configuration Options

Accept SSO Token

0

1

Enable Custom Login Mode

0

  • Default login redirect

  • Accepts SSO tokens and ID tokens as session tokens during and after the login flow.

  • SSO tokens are not converted to ID tokens.

1

  • Not supported

2

  • Not supported

  • Non-standard flow; this configuration has limitations, and is only for environments migrating from earlier versions of the agent.

  • For AM 6 or later.

  • Same domain custom login redirect

  • Redirection with a goto query parameter to the originally requested resource

  • Accept SSO tokens

Default Login Redirect

Unauthenticated users are redirected to, and must be able to access, the /oauth2/authorize endpoint. This endpoint invokes the AM console and other endpoints such as oauth2/authorize, json/authenticate, json/sessions, json/serverinfo, and XUI/*.

Set the following properties to configure default login redirects:

The following image shows the data flow for a default login redirect:

login-redirection-default

Same Domain Custom Login Redirect

The agent redirects unauthenticated users to a custom login page in the same domain, adding the original_request_url parameter to the redirect. The parameter records the requested URL, which can then be used by custom login application or page.

The custom login page posts an SSO token to agent/custom-login-response, with the realm as an optional parameter, and sets an SSO token in the same domain as the agent.

The agent attempts to validate the SSO token against the AM endpoints.

At the end of the login flow, the agent can do the final redirect to the protected resource, or to the originally requested resource, with a goto query parameter

Same Domain Custom Login Redirect With Final Redirect to the Protected Resource

Set the following properties:

If the custom login page is a part of the agent’s protected application, add the custom login pages to the not enforced lists.

The following image shows the data flow for a custom login redirect when the custom login pages are in the same domain as the agent, and the agent redirects the the request to the originally requested resource.

login-redirection-custom1-accepttoken0

Same Domain Custom Login Redirect With Final Redirect to the Originally Requested Resource (Migration Mode)

In this scenario, the agent redirects the client with a goto query parameter to the originally requested resource.

This mode only operates on HTTP GET requests. POST requests are not supported.

This is not a standard flow, and this feature is evolving. Use it only when migrating from earlier versions of the agents. Contact ForgeRock if you suspect your environment has a similar use case.

Part of this flow happens outside the agent’s control, and, therefore, the SSO token may expire or become invalid before the agent has a chance to validate it. In these cases, the user/client needs to authenticate again.

  • The custom login pages obtain the SSO token from AM

  • The agent does not track the user authentication using the pre-authentication cookie

Cross Domain Custom Login Redirect

The agent redirects unauthenticated users to a custom login page in a different domain, including the original-request-uri parameter in the redirect. The parameter records the requested URL, which can then be used by custom login application or page.

The custom login page provides a custom-login-response, and sets an SSO token, which can be accessed only in that domain. Because the agent cannot access the cookie, it redirects to AM for the Default Login Redirection Mode.

Depending on your environment, the agent can contact AM to validate the cookie even if it cannot see it. In other cases, you need to configure an additional property.

If AM can validate the SSO token, it returns an ID token as part of the default redirection login flow.

Consider the following points:

  • Ensure that the login pages do not set the SSO token cookie with the SameSite=Strict attribute.

  • If AM cannot validate the SSO token (for example, because it cannot recognize the domain set for the cookie), it redirects the end user to authenticate again using the Default Login Redirection Mode.

  • AM must be visible to the custom login pages, either because they both are in the same network/domain, or because you exposed the relevant AM endpoints using a proxy:

Cross Domain Custom Login Redirect on a Shared Network

On a shared network, the server where AM is running has two interfaces: one connected to the internal network, where the agent is, and another connected to the external network, where the custom login pages are.

Use the following properties to configure this scenario:

The following image illustrates the environment. The web server housing the protected resources can be connected to the external network in different ways; with two interfaces, or through a proxy. It is not important for the purposes of custom login, so it is not shown.

The agent and the custom login pages are on different domains. There is no proxy between AM and the custom login pages

The following image shows the data flow:

login-redirection-custom1-different-domain

Cross Domain Custom Login Redirect With AM Behind a Proxy

The server where AM is running has one interface to the internal network, where the agent is. A proxy hides AM from the external network, which forwards traffic to the /oauth2/authorize endpoint.

Use the following properties to configure this scenario:

The following image illustrates the environment. The web server where the protected resources are may be connected to the external network in different ways; with two interfaces, or through a proxy. It is not important for the purposes of custom login, so it is not shown in the following diagram:

The agent and the custom login pages are on different domains. There is a proxy between AM and the custom login pages.

The following image shows the data flow:

login-redirection-custom1-different-domain-publicAM

Conditional Login Redirect

Use conditional redirects with default or custom login redirects to redirect the end user to different AM instances or sites, or to different custom pages, depending on the incoming request URL.

When the incoming request URL matches a specified domain name, configure the following properties to redirect to a specified URL:

When the incoming request URL matches a regular expression, configure the following properties to redirect to a specified URL:

The following image shows the data flow for a default login redirect flow when conditional redirection is configured:

login-redirection-default-conditional

Logout Redirection

Web Agent can redirect users on logout to a specific AM page or to a custom logout page in your web server.

Configure logout redirect with the following properties:

Logout is triggered when the incoming URL matches one of the values configured in the Logout URL List or the Agent Logout URL Regular Expression properties.

These pages must exist in your web server and should be the logout pages for your application.

If the incoming URL matches a logout URL, the agent creates a URL and redirects the web client to it. The URL contains:

  • A logout page in your application or in AM. This page is configured in the OpenAM Logout URL property.

    If the Invalidate Logout Session property is enabled, the agent invalidates the session in AM. Configure this if the Logout URL List property is set to a page in your application, and your application does not handle the session invalidation process.

    If it is disabled, the logout page is responsible for invalidating the user session. Configure this if the Logout URL List property page is a SAML v2.0 logout page, the AM logout page, or a page in your application that can handle the session invalidation process.

  • A goto parameter. Its value is the URL configured in the Logout Redirect URL property.

    Configure this if you want the user to end on a specific page of your application after logout. For example, the landing page, or a login page. This page must exist in your web server.

    If the Enable Logout URL Redirect property is disabled, the agent does not add the goto parameter, and the web client will remain in the logout page.

You can also configure the agent to reset specific cookies during logout by configuring the Logout Cookies List for Reset property.

Examples:

Logout Flow with {am_abbr} as the Logout Page
Figure 1. Logout Flow with AM as the Logout Page
Logout Flow with the Application Serving the Logout Page
Figure 2. Logout Flow with the Application Serving the Logout Page

POST Data Preservation

Use POST data preservation in environments where clients submit form data, and have short-lived sessions.

When POST data preservation is enabled, and an unauthenticated client posts HTML form data to a protected resource, the agent stores the data in its cache, and redirects the client to the login screen. After successful authentication, the agent recovers the data stored in the cache, and automatically submits it to the protected resource.

The following image shows a simplified data flow, when an unauthenticated client POSTs data to a protected web application:

pdp-flow

Web Agent guarantees the integrity of the data, and the authenticity of the client as follows:

  1. An unauthenticated client requests a POST to a protected resource.

  2. The agent caches the POST data, and generates the following unique identifiers:

    • An identifier in the goto URL for the authentication response

    • An identifier in a cookie

    The use of two unique identifiers provides robust security, because a hacker must steal the goto URL and the cookie.

  3. The agent redirects the client to AM for authentication, and includes the cookie in the redirect.

  4. The client authenticates with AM.

  5. AM provides an authentication response to the goto URL with the unique identifier, and includes the cookie.

  6. The agent validates both identifiers, and recovers the POST data from the dummy internal endpoint given in the goto URL.

    If the goto URL contains the incorrect identifier, or cannot provide a cookie containing the correct second identifier (for example, because it has expired), the agent denies the request.

    The presence of the unique identifier in the goto URL ensures that requests at the URL can be individually identified. Additionally, the code makes it more difficult to hijack user data, because there is little chance of guessing the code within the login window.

  7. The agent sends a self-submitting form to the client browser, that includes the form data the user attempted to post in step 1. The self-submitting form POSTs to the protected resource.

For information about configuration properties, see POST Data Preservation.

Defend Against CSRF Attacks When Using POST Data Preservation

Cross-site request forgery attacks (CSRF or XSRF) can be a cause of serious vulnerabilities in web applications. It is the responsibility of the protected application to implement countermeasures against such attacks, because Web Agent cannot provide generic protection against CSRF. ForgeRock recommends following the latest guidance from the OWASP CSRF Prevention Cheat Sheet.

When POST data preservation is enabled, captured POST data that is replayed appears to come from the same origin as the protected application, not from the site that originated the request. Therefore, CSRF defenses that rely solely on checking the origin of requests, such as SameSite cookies or Origin headers, are not reliable. ForgeRock strongly recommend using token-based mitigations against CSRF, and relying on other measures only as a defense in depth, in accordance with OWASP guidance.

CSRF Attack When POST Data Preservation Is Disabled

The following image shows a simplified data flow during a CSRF attack on an authenticated client when POST data preservation is disabled. In this limited scenario, the agent SameSite setting is enough to defend the web application:

csrf-no-pdp-flow

CSRF Attack When POST Data Preservation Is Enabled

The following image shows a simplified data flow during a CSRF attack on an authenticated client when POST data preservation is enabled. In this scenario, the SameSite setting is not enough to defend the web application:

csrf-pdp-flow

Caches

Web Agent supports the following caches to speed up agent operations:

Configuration Cache

The configuration cache stores web agent configuration properties.

When a Web Agent 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, see 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:

Session and Policy Decision Validity in Cache
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 Agent 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 Agent 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 any cached policy patterns. In this case, the agent denies access immediately.

  • A requested resource matches the resource pattern of a simple policy that applies to the All Authenticated Users virtual 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.

The following caveats apply 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 only supports 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, see Environment Variables.

POST Data Preservation Cache

Stored in files saved in the agent installation directory, the POST data preservation cache stores short-lived POST data.

When Enable POST Data Preservation is enabled, the agent caches HTML form data submitted as an HTTP POST by unauthenticated clients. By default, this data is stored in the directory specified by POST Data Storage Directory.

POST data information is cached for the amount of time specified by POST Data Entries Cache Period.

Connection Pooling

By default, the Web Agent uses connection pooling to improve performance when AM is available over low bandwidth connections, or to throttle the maximum number of connections made by the Web Agent.

When AM is available over high bandwidth connections, connection pooling can reduce performance.

Enable and disable connection pooling with the bootstrap property Enable Connection Pooling.

Copyright © 2010-2023 ForgeRock, all rights reserved.