Web Agents 5.10.3

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

Some resources, such as the "public" directory of a web application, contain data that is not sensitive. It can be accessed by any, authenticated or unauthenticated, clients. The agent uses lists of not-enforced rules to identify these resources in the web application.

The agent matches incoming requests to the lists of not-enforced rules. When a request matches a not-enforced rule, the agent bypasses the call to AM:

  • If an unauthenticated user sent the request, the agent does not redirect the user to log in.

  • If an authenticated user sent the request, the agent does not request a policy evaluation from AM.

Use not-enforced rules to reduce the number of unnecessary calls to AM, and therefore improve the performance and speed of your application.

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

not-enforced-flow

1-2. A client requests a resource and the agent checks whether the request matches a rule in a not-enforced list.

3-5. If the request matches a rule, the agent passes the request without requiring authentication or policy decisions. Otherwise, the agent checks whether rules are inverted.

6-10. If the request matches an inverted rule, the agent passes the request without requiring authentication or policy decisions. Otherwise, the agent enforces authentication and policy decisions.

Conventions for not-enforced rules

Consider the following points about not-enforced rules:

  • Web servers normalize request URLs as described in RFC 3986: Normalization and comparison before passing them to the agent. The agent compares the normalized URL to the not-enforced rule.

  • Trailing forward-slashes / can represent a directory. Therefore, /images/ does not match /images, but does match /images/index.html

Invert not-enforced URL 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.

Wildcards

For more information about using wildcards, see Specifying resource patterns with wildcards.

Multi-level wildcard (*)

The following list summarizes the behavior of the multi-level wildcard (*):

  • Matches zero or more occurrences of any character except for the question mark (?).

  • Spans multiple levels in a URL.

  • Cannot be escaped. Therefore, the backslash (\) or other characters cannot be used to escape the asterisk, as such \*.

  • Cannot be used in the same rule as the one-level wildcard (-*-) or regular expression.

  • Explicit patterns are required to match URL parameters. For example:

    • URL patterns ending with /foo* do not match URLs with parameters

    • URL patterns ending with /foo*?* match any parameter

Multi-level wildcard for not-enforced IP rules
Rules in Not-Enforced IP List Matches request IP Does not match request IP

192.168.1.*

192.168.1.0

192.168.1.0/24

192.168.0.1
Multi-level wildcard for not-enforced URI rules
Rules in Not-Enforced URL List Matches request URL Does not match request URL

http://A-examp.com:8080/*

http://A-examp.com:8080/

http://A-examp.com:8080/index.html

http://A-examp.com:8080/x.gif

http://B-examp.com:8080/

http://A-examp.com:8090/index.html

http://A-examp.com:8080/a?b=1

http://A-examp.com:8080/*.html

http://A-examp.com:8080/index.html

http://A-examp.com:8080/pub/ab.html

http://A-examp.com:8080/pri/xy.html

http://A-examp.com/index.html

http://A-examp.com:8080/x.gif

http://B-examp.com/index.html

http://A-examp.com:8080/*/ab

http://A-examp.com:8080/pri/xy/ab/xy/ab

http://A-examp.com:8080/xy/ab

http://A-examp.com/ab

http://A-examp.com/ab.html

http://B-examp.com:8080/ab

http://A-examp.com:8080/ab/*/de

http://A-examp.com:8080/ab/123/de

http://A-examp.com:8080/ab/ab/de

http://A-examp.com:8080/ab/de/ab/de

http://A-examp.com:8080/ab/de

http://A-examp.com:8090/ab/de

http://B-examp.com:8080/ab/de/ab/de
One-level wildcard (-*-)

The following list summarizes the behavior of the one-level wildcard (-*-):

  • Matches zero or more occurrences of any character except for the forward-slash (/) and the question mark (?).

  • Does not span across multiple levels in a URL.

  • Cannot be escaped. Therefore, the backslash (\) or other characters cannot be used to escape the hyphen-asterisk-hyphen, like this \-*-.

  • Cannot be used in the same rule as the multi-level wildcard (*) or regular expression.

One-level wildcard for not-enforced URI rules
Rules in Not-Enforced URL List Matches request URL Does not match request URL

http://A-examp.com:8080/b/-*-

http://A-examp.com:8080/b/

http://A-examp.com:8080/b/cd

http://A-examp.com:8080/b

http://A-examp.com:8080/b/cd/ (This URL should match the rule, but does not because of the known issue AMAGENTS-4672.)

http://A-examp.com:8080/b/c?d=e

http://A-examp.com:8080/b/cd/e

http://A-examp.com:8090/b/

http://A-examp.com:8080/b/-*-/f

http://A-examp.com:8080/b/c/f

http://A-examp.com:8080/b/cde/f

http://A-examp.com:8080/b/c/e/f

http://A-examp.com:8080/f/

http://A-examp.com:8080/b/c-*-/f

http://A-examp.com:8080/b/cde/f

http://A-examp.com:8080/b/cd/f

http://A-examp.com:8080/b/c/f

http://A-examp.com:8080/b/c/e/f

http://A-examp.com:8080/b/c/

http://A-examp.com:8080/b/c/fg
Multiple wildcards

When multiple wildcards are included in the same rule of a Not-Enforced URL List, the agent matches the parameters in any order that they appear in a resource URI.

For example, the following rule applies to any resource URI 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

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 cannot be used. The asterisk * is not treated as a wildcard, but is treated as part of the expression, representing repetition of the last character 0-n times.

  • The following formats cannot be used:

    • Netmask CIDR notation

    • IP address ranges

    However, regular expressions can match 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 HTTP method keywords to the not-enforced rule to apply it when the incoming request uses the HTTP method. Keywords include but are not restricted to GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS.

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]=http://www.example.com:8080/scripts/*
com.sun.identity.agents.config.notenforced.url[PATCH]=http://www.other.com:8080/scripts/*
com.sun.identity.agents.config.notenforced.url[PATCH1,PATCH2]=http://www.example.com:8080/scripts/*

Unrecognized methods can invalidate a 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

For information about properties to configure attribute fetching, see Attribute processing.

Web Agent can fetch user information, and inject it into HTTP request headers 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.

When injecting information into HTTP headers, do not use underscores (_) in the header name. Underscores are incompatible with systems that run CGI scripts, and the header can be silently dropped.

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 web server. 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

When FQDN checking is enabled, the agent checks the FQDN of a request before it evaluates the authentication or authorization of the request. Use this feature to prevent the redirect of requests in the following scenarios:

  • Where resource URLs differ from the FQDNs in AM policies, for example, in load balanced and virtual host environments.

  • Where hostnames are virtual, allocated dynamically, or match a pattern, for example in a Kubernetes deployment.

  • Where hostnames are partial.

FQDN checking requires Enable FQDN Check to be true, FQDN Default to be set to a suitable value, and optionally, FQDN Virtual Host Map to map incoming URLs to valid outgoing domains.

The agent maps FQDNs as follows:

  1. If the request matches the domain in FQDN Default, the agent passes the request to the next step without changing the request domain.

  2. Otherwise, if the request matches a mapped domain (map value) in FQDN Virtual Host Map, the agent passes the request to the next step without changing the request domain.

  3. Otherwise, if the request matches a mapped host (map key) in FQDN Virtual Host Map, the agent redirects the request to the mapped domain before passing it to the next step.

  4. Otherwise, the agent redirects the request to the domain in FQDN Default before passing it to the next step.

Examples

The following example configuration and requests illustrate how the agent checks and remaps FQDNs:

Example configuration

  • Agent Root URL for CDSSO:

    sunIdentityServerDeviceKeyValue=agent.example.com

  • Not-Enforced URL List

    com.sun.identity.agents.config.notenforced.url[0]=http://www.agent1*.example.com

  • Enable FQDN Check:

    com.sun.identity.agents.config.fqdn.check.enable=true

  • FQDN Default:

    com.sun.identity.agents.config.fqdn.default=agent.default.com

  • FQDN Virtual Host Map:

    com.sun.identity.agents.config.fqdn.mapping[agent.example.com]=agent.example.com

    com.sun.identity.agents.config.fqdn.mapping[agent.example.com]=agent-*

    com.sun.identity.agents.config.fqdn.mapping[any.value.com]=ag*.example.com

    com.sun.identity.agents.config.fqdn.mapping[agent.othertest.me]=other.example.com

Example requests

  • http://agent.default.com/app: The request URL matches the domain of the default mapping, so the agent does not redirect the request.

  • https://agent.example.com/app: The request URL matches the value (domain) in the first mapping, so the agent does not redirect the request.

  • http://agent-4738294739287492/foo/bar/: The request URL matches the value (domain) in the second mapping, using the wildcard, so the agent does not redirect the request. Note that the value of the key is irrelevant in this match.

  • https://agent123.example.com/app: The request URL matches the value (domain) in the third mapping, so the agent does not redirect the request.

  • https://agent.othertest.me/app: The request URL matches the key (host) in the fourth mapping, so the agent redirects the request to https://other.example.com/app.

  • https://agent.othertest2.me/app: The request URL doesn’t match any mapping, so the agent redirects the request to the default domain, https://agent.example.com/app.

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 (am.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 web server 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 web server 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.

This section describes the default login redirect, and options to configure the redirect.

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:

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.

  • Same domain custom login redirect

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

  • Accept SSO tokens

Default login redirect

The following image shows the flow of data during a default login redirect, when an unauthenticated user requests access to a protected resource. The agent wraps the SSO session token inside an OIDC JWT. Authentication requires access to the /oauth2/authorize endpoint, which invokes the AM console and other endpoints such as oauth2/authorize, json/authenticate, json/sessions, json/serverinfo, and XUI/*.

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 isn’t 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

Redirect login to a custom URL configured in AM

AM’s OAuth2 Provider service can be configured to use a custom URL to handle login, to override the default AM login page. When a custom login page is configured in AM, configure the agent to ensure that it redirects the login to that page.

  1. In the AM console, go to Services > OAuth2 Provider > Advanced > Custom Login URL Template, and note the custom URL.

  2. Go to Applications > Agents > Web, and select your Web Agent.

  3. On the AM Services tab set the following properties:

Logout redirect

On logout, Web Agent can redirect users to a specific AM page, or to a custom logout page in your web server. For properties to configure logout redirect, see Logout.

Logout redirect is triggered when Disable Logout Redirection is false, and the incoming URL matches a value in Logout URL List or Agent Logout URL Regular Expression.

When 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, configured in AM Logout URL.

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

    • If Enable Invalidate Logout Session is false, the logout page is responsible for invalidating the user session. Configure this if the Logout URL List 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, configured in Logout Redirect URL.

    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 Disable Logout Redirection is true, the agent does not add the goto parameter, and the web client remains in the logout page.

To reset specified cookies during logout, configure Reset Cookies on Logout List.

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 data to a protected resource, the agent stores the POST data temporarily, and redirects the client to the login screen. The data can be any POST content, such as HTML form data or a file upload. After successful authentication, the agent recovers the stored POST data, 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 stores the POST data temporarily in the directory defined by POST Data Storage Directory, and saves data about the request in a standard pre-authentication cookie.

  3. The agent sets a pre-authentication cookie in the browser, and redirects to the /authorize endpoint in AM.

  4. The client authenticates with AM.

  5. AM sends an authentication response to the registered redirect URI.

  6. The agent retrieves the original application URL from the pre-authentication cookie, and replays the request with its body content to the server. The authentication response includes an OIDC token, which the agent sets as a secure cookie in the browser.

  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.

Security considerations for POST data preservation

POST data is stored temporarily in the agent file system before a user is authenticated. Therefore, any unauthenticated user can POST a file that is then stored by the agent. Consider the following points when you configure POST data preservation:

  • Payloads from unauthenticated users are stored in the agent files system. If your threat evaluation does not accept this risk, do not use POST data preservation; set Enable POST Data Preservation to false.

  • By default, POST data is stored in the installation log directory, /path/to/web_agents/agent_type/instances/agent_n/log. Although the log directory is considered secure, using it for POST data can cause the following risks:

    • Permissive access to POST data.

      Log directories can have relatively permissive read or copy permissions compared to other directories.

    • Leakage of personally identifiable information (PII).

      If POST data in log directories is processed by log applications, it could be included in a log view.

    To store POST data in a dedicated directory, set POST Data Storage Directory.

  • POST data is stored for the time defined by POST Data Entries Cache Period and then deleted. To identify threats in POST data before it is deleted, make sure that Intrusion Detection Systems inspect the data within the specified time.

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.

To defend against CSRF attacks when POST data preservation is enabled, the agent uses a secure cookie and a nonce. The nonce must correspond to the authentication response from AM. This defense during authentication is specified in Cross-Site Request Forgery.

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.

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 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-2024 ForgeRock, all rights reserved.