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.
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:
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.
false, which is the default, the agent also manages user authorization, by using the policy engine in AM.
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
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:
Compound not-enforced rules
Rules in not-enforced IP lists
Rules in not-enforced URL lists
The following image shows the data flow when Web Agent evaluates not-enforced rules for a request:
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.
Use the conventions in this section to define not-enforced rules:
Invert all rules in a not-enforced URL list by setting
Invert Not-Enforced URLs
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.
* 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
For more information about using wildcards, see Specifying Resource Patterns with Wildcards.
*to match all characters in a rule, except the question mark
?character. The wildcard cannot be escaped.
The wildcard spans multiple levels. For example:
Multiple forward slashes do not match a single forward slash. Therefore,
mult/*/dirsdoes not match
-*-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:
-*-wildcards cannot be used in the same rule, but can be used in different rules in the same list. For example:
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
locationquery parameter, in any order:
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,
/imagesare equivalent. For more information about using wildcards, see Specifying Resource Patterns with Wildcards.
Regular Expressions for Not-Enforced URLs
true, and consider the following points for using regular expressions in
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:
If an invalid regular expression is specified in a rule, the rule is dropped, and an error message is logged.
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:
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:
To specify a list of methods, add multiple rules:
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:
Unrecognized keywords in a rule are ignored and do not invalidate the rest of the rule.
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
22.214.171.124/24 to any file in
/public, or any files or directories
that start with the string
login in the directory
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.
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
FQDN Default and
FQDN Virtual Host Map properties.
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.
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
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:
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 (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.
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
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.
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.
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
User-Agentheader to fields in an environment map:
If the incoming request contains an
ssidcookie and a
User-Agentheader, the environment map takes the value of the cookie and header, as shown in this example:
requestIp=126.96.36.199.1 requestDnsName=client.example.com mySsid=77xe99f4zqi1l99z myUser-Agent=Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko
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
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:
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
Set the following properties to configure default login redirects:
The following image shows the data flow for a default 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
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
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.
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
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
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:
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 following image shows the data flow:
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
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 following image shows the data flow:
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:
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.
gotoparameter. 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
gotoparameter, 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.|
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:
Web Agent guarantees the integrity of the data, and the authenticity of the client as follows:
An unauthenticated client requests a POST to a protected resource.
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.
The agent redirects the client to AM for authentication, and includes the cookie in the redirect.
The client authenticates with AM.
AM provides an authentication response to the goto URL with the unique identifier, and includes the cookie.
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.
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.
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.
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:
Web Agent supports the following caches to speed up agent operations:
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.
Stored in the shared memory pool defined by the
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:
|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.
Policy decision reaches the expiration time specified by Policy Cache Polling Period.
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(*).|
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 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.
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
Change the location of the policy cache by creating an environment variable named
For more information about properties related to the policy cache, see Environment Variables.
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.
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.