Features

Cross-Domain Single Sign-On

In cross-domain single sign-on, Java Agent processes requests using authentication provided by AM. Users can access multiple independent services from a single login session, using the agent to transfer the session ID. The agent and AM can be in the same domain or in different domains.

The following diagram illustrates the CDSSO flow:

When the agent is in local configuration mode, configure the Authentication Redirect URI. When the agent is in remote configuration mode, the value is set by the agent configuration in AM.

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

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, the agent can redirect a user from the france.example.com domain to log in to the am.france.example.com AM site.

This section describes a default login redirect, and options to configure the 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 XUI/*, and the agent requires access to json/authenticate, json/sessions, and json/serverinfo.

Set the following properties to redirect a request to a login realm, based on the request domain:

Enable Custom Login Mode: Leave with the default value of false.
OAuth Login URL List: Map the request domain to the required login realm. When this property is set, the agent tries to match the request domain to the list of domains in this property. If there is a match, the agent redirects the user to log in at the matched URI.

The following image shows the first few steps from figure 1, where the redirect is this time configured with the value in OAuth Login URL List.

In the following example, unauthenticated requests are redirected to different login realms according to the request domain:

org.forgerock.agents.oauth.login.url.list[0] = blue.example.com|?realm=blue
org.forgerock.agents.oauth.login.url.list[1] = red.example.com|?realm=red
org.forgerock.agents.oauth.login.url.list[2] = red.example.com/yellow|?realm=orange
org.forgerock.agents.oauth.login.url.list[3] = |?realm=default

The requests are directed as follows:

Requests for a resource in blue.example.com are passed to the oauth2/authorize endpoint to log the user into the blue realm.
Requests for a resource in red.example.com/ruby are passed to the oauth2/authorize endpoint to log the user into the red realm.
Requests for a resource in red.example.com/yellow/ are passed to the oauth2/authorize endpoint to log the user into the orange realm.
Requests for a resource in an unmapped domain are passed to the oauth2/authorize endpoint to log the user in to the specified default realm.

Redirect Login to an OIDC Endpoint Based on the Request Domain

Set the following properties to redirect a request to a different OIDC endpoint, based on the request domain:

Enable Custom Login Mode: Leave with the default value of false.
OAuth Login URL List: Map the request domain to the required login endpoint. When this property is set, the agent tries to match the request domain to the list of domains in this property. If there is a match, the agent redirects the user to the matched URI for login.

In the following example, unauthenticated requests are redirected to different OIDC endpoints according to the request domain: domain:

org.forgerock.agents.oauth.login.url.list[2] = red.example.com/yellow|https://other.example.com:8081/am/other-idp/oauth2/other-authorize?realm=orange
org.forgerock.agents.oauth.login.url.list[3] = |?realm=default

The requests are directed as follows:

Requests for a resource in red.example.com/yellow, are passed to https://other.example.com:8081/am/other-idp/oauth2/other-authorize to log the user in to the orange realm.
Requests for a resource in an unmapped domain are passed to the oauth2/authorize endpoint to log the user in to the specified default realm.

For legacy deployments that require SSO tokens, redirect the login to a custom login page to set the SSO token in the user’s browser after authentication. Use the custom redirection login mode when:

Your environment has customized login pages that expect user sessions to be stored in SSO tokens instead of in OIDC JWTs.
Users cannot access the AM servers directly in your environment.
Custom login pages are not part of AM’s XUI.

Use the following properties to configure custom login redirects:

Enable Custom Login Mode:
- Set to true if the custom login page sets an SSO token in the user’s browser after authentication.
Enable SSO Token Acceptance:
- Set to true to prevent the agent from attempting to convert SSO tokens into OIDC tokens. Use this option to continue to use SSO tokens, when the agent and the token issuer are in the same domain.
- Set to false to allow the agent to convert SSO tokens to OIDC tokens. Use this option for better security, and in web applications and APIs where the backend requires user information in form of an OIDC token.
AM Login URL List or Legacy Login URL List
- If AM Login URL List is configured, the agent redirects the user to the specified custom login page, and appends a resourceURL parameter to the login endpoint.
- If Legacy Login URL List is configured but AM Login URL List is not, the agent matches the request with the domains and URLs specified by Legacy Login URL List, and redirects the user to the appropriate custom login page.
- If neither property is configured, authentication fails.

The following image shows a simplified flow for a custom login redirect, when the agent uses SSO tokens without converting them to OIDC id_tokens:

Redirect Login to Pages Behind a Firewall

When a login page is in a network that accesses AM through a proxy, firewall, or other technology that remaps the AM URL, set Public AM URL to map the AM URL to a URL that the login page can access.

For example, if AM and the agent communicate on example-internal.com, but the custom login pages are on example-external.com, configure the public AM URL as https://openam.example-external.com:8443/openam.

Not Enforced Rules

It is sometimes necessary to allow unauthenticated users, or to users from specific IP addresses, to access specific resources. For example, unauthenticated users should be able to access the HTML files for the public front end of a website. Furthermore, allowing unauthenticated access to non-sensitive resources reduces the overhead of confirming each access with AM.

Java Agent manages unauthenticated access through the configuration of not-enforced rules. When a not-enforced rule applies to a request, the agent allows the request:

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.

The following image shows the data flow when Java Agent evaluates not-enforced rules for a request, first searching for a match in the cache, then in the not enforced lists:

1. A client requests a resource.

2-4. If the not-enforced URI or IP cache is enabled, the Java Agent checks whether the request matches any cached results. If the same request from the client previously matched a not-enforced rule, the Java Agent passes the request without requiring the client to authenticate.

5. If the caches are not enabled, or the request doesn’t match a cached result, the Java Agent checks whether the request matches a rule in a not-enforced list.

The Java 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.

6-8. The Java Agent caches the result and passes the request without requiring the client to authenticate.

9-14. If the request doesn’t match a rule in a not-enforced list, the Java Agent checks whether rules are inverted, and responds as follows:

Not-enforced URI rules	Not-enforced IP rules	Pass request without requiring authentication?
Inverted	Inverted	Yes
Not inverted	Not inverted	No
Inverted	Not inverted	No
Not inverted	Inverted	No

Not-enforced URI rules

Not-enforced IP rules

Pass request without requiring authentication?

Inverted

Yes

Not inverted

Inverted

Not inverted

Inverted

Configure Not-Enforced Rules

Configure not-enforced rules by using the agent properties listed in Not-Enforced Rules in the Properties Reference, or on the Application tab of the AM console. Configure the following lists of not-enforced rules:

Not-enforced URI rules

Allow access to resources, such as images, stylesheets, or the HTML pages that provide the public front end of your site.

Not-enforced IP rules

Allow access to your site from an administrative IP address, an internal network range, or a search engine.

Compound not-enforced URI and IP rules

Allow access based on a combination of resources and IPs. When there are multiple lists of rules, the agent evaluates them in this order:

Compound rules in not-enforced URI and not-enforced IP lists
Rules in not-enforced IP lists
Rules in not-enforced URI lists

Conventions for Not-Enforced Rules

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

Inverting rules

Invert specific rules

Invert any rule in the not-enforced list by preceding it with the keyword NOT, separated by a space (blank) character.

In the following example, requests for a .jpg file in the /private URI require authentication:

NOT /private/*.jpg

In the following example, the agent defers to AM any request from the network specified by the 192.168.1.0/24 CIDR notation:

NOT 192.168.1.0/24

Invert all rules

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

Wildcards

Wildcard for not-enforced IP rules

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

192.168.*

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

Wildcards for not-enforced URI 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:
```
/images/*
/*.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 URI. For example:
```
/css/-*-
```
* and -*- wildcards cannot be used in the same rule, but can be used in different rules in the same list. For example:
```
/css/-*-
/images/*
```
Multiple wildcards in the query parameter section of a not-enforced URI rule match the parameters in any order that they appear in a resource URI. For example, the following not-enforced URI rule applies to any resource URI that contains a member_level and location query parameter, in any order:
```
/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 URI 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

Add the keyword REGEX followed by a blank (space) character before the URI or IP address. For example:

REGEX https?://www\.example\.com/([^/])+/.*\.jpg

REGEX 192\.168\.10\.\d+

Consider the following points when using regular expressions:

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:
```
REGEX 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

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 any request method to 192.168.10.*:

192.168.10.*

The following example does not require authentication for GET requests to /public, but does require authentication for other HTTP methods:

GET /public/*

To specify a list of methods, add a comma-delimited list of methods, followed by a blank (space) character before the item to match.

GET,POST /public/*
GET,POST,PUT /examples/notenforced/*.jpg
GET,REGEX https?://www\.example\.com/([^/])+/.*\.jpg

NOT,GET,REGEX 192\.168\.10\.\d+
POST 192.168.10.*
GET 192.168.10.1-192.168.10.254 192.168.0.1
POST,PUT 192.168.1.0/24

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:

!POST /public/*

!POST 192.168.1.0/24

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

Cookie values

Use the following syntax to apply not-enforced rules when the incoming request has a named cookie with a specified value:

COOKIE(Name/Value/Modifiers) Not Enforced URIs

COOKIE(Name/Value/Modifiers) Not Enforced IPs

Name: Cookie name
Value: Cookie value to search for.
Modifiers: One or more modifiers to change the lookup method:
- c: (For not-enforced URI rules only) Perform a case-insensitive search for the cookie name. By default, the search is case-sensitive.
- i: Perform a case-insensitive search for the cookie value. By default, the search is case-sensitive.
- r: Treat the string in Value as a regular expression.

The following example does not require authentication for requests to /private/admin/images/, when the request contains a cookie named login_result (case-insensitive), with the value VALID (case-insensitive):

COOKIE(login_result/VALID/ci) /private/admin/images/*

The following example does not require authentication for requests to 192.168.* when a cookie present on the request has the name login_result and the case-insensitive value VALID:

COOKIE(login_result/VALID/i) 192.168.*

Combine cookie filters with other filters, such as HTTP methods. Combining a HEADER and COOKIE expression in the same rule implies a logical AND; both expressions must match in order to apply. To apply the rules as a logical OR, create two separate rules.

The following example does not require authentication for GET, POST, and PUT requests to the /other/records/ folder, when the request contains a cookie named internal (case-sensitive), with a value that matches the regular expression .*ID (case-insensitive):

GET,POST,COOKIE(internal/.*ID/ri),PUT /other/records/*.html

The following example does not require authentication for GET, POST, and PUT HTTP requests from the client IP range 192.168.*, when there is a cookie named internal, with a value that matches the regular expression .*ID:

GET,POST,COOKIE(internal/.*ID/r),PUT 192.168.*

Header values

Use the following syntax to apply not-enforced rules when the incoming request has a named header with a specified value:

HEADER(Name/Value/Modifiers) Not Enforced URIs

HEADER(Name/Value/Modifiers) Not Enforced IPs

Name: Header name.
Value: Header value to search for.
Modifiers
- i: Perform a case-insensitive search for the header value. By default, the search is case-sensitive.
- r: Treat the string in Value as a regular expression.

The following example does not require authentication for access to .txt files in /yearly/2021/ when the request contains a header named ID (case-insensitive), with the value validated (case-insensitive):

HEADER(ID/validated/i) /yearly/2021/*.txt

The following example does not require authentication for access to the IP range 192.168.* when the request includes a header named ID with the case-insensitive value validated:

HEADER(ID/validated/i) 192.168.*

Combine cookie filters with other filters, such as HTTP methods. Combining a HEADER and COOKIE expression in the same rule implies a logical AND; both expressions must match. To apply the rules as a logical OR, create two separate rules.

The following example does not require authentication for GET, POST, and PUT requests to HTML resources in the /other/records/ folder when the request contains a header named internal (case-insensitive), with a value that matches the regular expression .*ID (case-insensitive):

The following example does not require authentication for GET, POST, and PUT requests from the IP address range 192.168.*, when the request contains a header named internal (case-insensitive), with a value that matches the regular expression .*ID (case-insensitive):

GET,POST,HEADER(internal/.*ID/ri),PUT /other/records/*.html

Compound rules

Configure compound not-enforced rules to combine not-enforced URI and IP rules in a single rule.

Configure rules in either Not-Enforced Client IP List or Not-Enforced URIs, using an IP rule or list of IP rules, a delimiter, and an URI rule or list of URI rules.

In the following example, the agent does not enforce HTTP requests from the IP range 192.168.1.1-192.168.4.3 to any file in the /images URI:

192.168.1.1-192.168.4.3 | /images/*

Consider the following points for compound rules:

Place keywords, such as HTTP methods, NOT, and REGEX, at the beginning of the compound rule. Keywords affect both the IP and the URI rules.

In the following example, the agent does not enforce GET or POST HTTP requests from the IP range 192.168.1.1-192.168.4.3, to any file (*) in the /images URI.
```
GET,POST 192.168.1.1-192.168.4.3 | /images/*
```
In the following example, the agent defers to AM any request to a method except POST, from any IP address in the 192.168.1 subnet, to any file in the /private URI.
```
NOT,!POST 192.168.1.* | /private/*
```
Check that both sides of a rule using the REGEX keyword can be parsed as a regular expression.

In the following example, the delimiter is &&, because the | character can lead to invalid regular expressions:
```
POST,REGEX 192\.168\.10\.(10|\d) && \/images\/([^/])+\.*\.jpg
```
For information about configuring a different delimiter, see Not-Enforced Compound Rule Separator.
The agent caches hits and misses for each resource accessed.

Caching is enabled if either Enable Not-Enforced IP Cache or Enable Not-Enforced URIs Cache is true.

The cache size takes the biggest value of Max Entries in Not-Enforced IP Cache or Max Entries in Not-Enforced URI Cache.

Extended characters

URLs defined in Not-Enforced URIs can contain any number of extended ASCII characters. The agent container automatically percent-encodes extended characters, before the agent is called.

Extended characters in the resource path of a not-enforced rule

By default, Java Agent uses UTF-8 to percent-encode extended characters in the resource paths of not-enforced rules. To change the character encoding, set Container Character Encoding.

In the following example, the agent does not enforce authentication or request policy evaluation for HTTP requests to the URL http://www.example.com/forstå:

org.forgerock.agents.notenforced.uri.list=http://www.example.com/forstå/*

Note how the extended ASCII character å can be entered without encoding.

Extended characters in HTTP query parameters of a not-enforced rule

By default, Java Agent uses ISO-8859-1 to encode extended characters in HTTP query parameters of not-enforced rules. To change the character encoding, set Container Parameter Encoding.

POST Data Preservation

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.

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

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

Java 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.

Configure POST Data Preservation

Configure POST data preservation by using the agent properties listed in POST Data Preservation in the Properties Reference, or on the Advanced tab of the AM console.

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 Java 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 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:

Continuous Security

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

When the Java Agent requests a policy decision from AM, it can include this information in an environment map , a set of name/value pairs that describe the request IP and DNS name, along with other, optional, information.

In the Java Agent, use continuous security to configure an environment map. 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 the Java Agent, use the continuous security properties Client Hostname Header and Client IP Address Header to configure an environment map with custom keys.

The environment map has the following parts:

requestIp

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

If Client IP Address Header is configured, the Java Agent extracts the IP address from the header.
Otherwise, it uses the Java function HttpServletRequest.getRemoteAddr to determine the 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, the Java Agent extracts the host name from the header.
Otherwise, it uses the Java function HttpServletRequest.getRemoteHost to determine the host name address.

This entry is always created in the map.

Other variable names

An array of cookie or header values, configured by the continuous security properties Client Hostname Header and Client IP Address Header.

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.agents.continuous.security.cookies.map[ssid]=mySsid
org.forgerock.agents.continuous.security.headers.map[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

Environment Maps With Fixed Keys

In the Java Agent, use the continuous security properties GET Parameter List for URL Policy Env, POST Parameter List for URL Policy Env, and JSession Parameter List for URL Policy Env to configure an environment map with fixed keys.

Attribute Fetch Modes

For information about properties to configure attribute fetching, see the Properties Reference.

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

You can configure the type of attributes to fetch, and map the attribute names used on AM to the values used in the containers. The agent securely fetches the user and session data from the authenticated user, as well as policy response attributes.

Autonomous Mode

In autonomous mode, the agent operates independently of AM, without needing to contact an AM instance. Agents allow access to resources as defined in not-enforced lists; otherwise, they deny access.

Agents evaluate not-enforced rules that use the following features:

URLs, IP addresses, IP address ranges, and compound rules.
Rules applied to specific HTTP methods.
Inverted not-enforced rules, by using properties.
Inverted not-enforced rules, by using inline logical operators.
Rules that use regular expressions.
Rules applied in the presence of named cookies with specified values.

Because the agent does not attempt to contact AM, the following functionality is not available in autonomous mode:

Notifications
Remote auditing
Profile attributes
Session attributes
Response attributes
Continuous security

To enable autonomous mode, in the bootstrap properties file, AgentBootstrap.properties, set Autonomous mode to true, and restart the Java container where the agent is installed.

Because the agent does not contact AM when it starts in autonomous mode, the value of Location of Agent Configuration Repository must be LOCAL.

For information about properties to configure attempt limits, see the Properties Reference.

When a client does not present a valid SSO token, the Java Agent redirects the user to the login URL configured in AM. To mitigate redirect loops that can result in an error page presented to the end-user, configure the to limit the number login attempts.

Configure the following properties to limit login attempts and redirects:

Login Attempt Limit, to specify a non-zero value for the number of login attempts. For example, if the property is set to 3, then the agent blocks the fourth login request.
Redirect Attempt Limit, to limit the number of redirections the agent can take for a single browser session.

FQDN Checking

For information about properties to configure FQDN checking, see the Properties Reference.

Clients must use valid URLs with fully qualified domain names (FQDNs) to access resources. If a client uses an invalid URL, policy evaluation can fail because the FQDN does not match the requested URL, and the request fails. Misconfigured URLs can also cause incorrect policy evaluation for subsequent access requests.

In load-balanced and virtual host environments, clients can specify resource URLs that differ from the FQDNs stored in AM policies. The Java Agent provides the following properties:

Default FQDN: Specifies a default URL with valid hostname. If the agent finds an invalid URL in the client request, it redirects the request to this URL.
FQDN Map: Maps invalid URLs, load balanced URLs, and virtual host URLs to valid URLs. Each entry in the map has precedence over the FQDN default.

To prevent redirects to the FQDN default, map all anticipated invalid URLs.

For information about properties to configure cookie reset, see the Properties Reference.

AM provides cookie reset properties that the Java Agent carries out prior to redirecting the client to a login page for authentication.

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

The cookie reset properties include the following:

List of cookies that can be reset
Domain map specifying the domains for each cookie
Path map specifying the path from which the cookie is reset

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

Caching

Java Agent allocates memory from the Java heap space in the web container to the following caches:

Configuration Cache

When the agent starts up in remote configuration mode, it retrieves a copy of the agent profile from AM, and stores it in the cache. The cached information is valid until one of the following events occurs:

AM notifies the agent of changes to hot-swappable agent configuration properties. The agent flushes the configuration cache and rereads the agent profile from AM.
The agent restarts.
The agent rereads the configuration from AM or from local files at the frequency specified by Configuration Reload Interval.

If the reload interval is disabled, and notifications are disabled, the cached configuration remains valid until the agent restarts.

Session Cache

After authentication, AM presents the client with a JWT, containing session information. The agent stores part of that session information in the cache.

A session stored in the session cache is valid until one of the following events occur:

The session contained in the JWT expires.
The client logs out from AM, and session notifications are enabled.
The session reaches the expiration time specified by Session Cache TTL.

Policy Decision Cache

When a client attempts to access a protected resource, the agent checks whether there is a policy decision cached for the resource:

If the client session is valid, the agent requests a policy decision from AM and then enforces it.
If the client 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, the agent requests policy decision from AM and enforces it.

Policy decisions are valid in the cache until one of the following events occur:

Session and Policy Validity in Cache
Event	What is invalidated?
Session contained in the JWT 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
Policy decision reaches the expiration time specified by Policy Cache TTL	Policy decision
Administrator makes a change to policy configuration (and policy notifications are enabled)	All sessions and all policy decisions

A Java Agent that loses connectivity to 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.

Not-Enforced Lists Hit and Miss Caches

The first time the agent receives a request for a resource, it matches the request and the client’s IP address against the rules specified in the not-enforced lists.

Java Agent maintains a cache of hit and miss for each of the not-enforced lists specified in Not-Enforced Rules.

To speed up future requests, the agent stores whether the resource hit or missed not-enforced rules in the corresponding caches. Therefore, if a request for the same resource reaches the agent again, the agent replays the result of the rule evaluations stored in the caches, instead of re-evaluating the request.

Entries stored in the hit and miss caches do not expire unless AM notifies the agent about configuration changes in the not-enforced lists.

POST Data Preservation Cache

When POST data preservation is enabled, the agent caches HTML form data submitted as an HTTP POST by unauthenticated clients.

The POST data expires either when the client recovers the information from the cache or after the time interval specified in POST Data Preservation Cache TTL.

For more information, see POST Data Preservation.

OpenID Connect JSON Web Token (JWT) Cache

Decoding JWTs into JSON objects is a CPU-intensive operation. To reduce the amount of processing required on each request, agents cache decoded JWTs.

When an agent receives a request for a resource, it passes the JWT through a fast hashing algorithm that creates a 128-bit hash unique for that JWT. Then the agent determines if the hash is in the JWT cache. One of the following scenarios occur:

The hash is in the cache. The agent retrieves the decoded JWT from the cache and continues processing the request.
The hash is not in the cache. The agent decodes the JWT and stores it and its hash in the cache. Then it continues processing the request.

JWTs in the cache expire after the time interval specified by JWT Cache TTL.

Query Parameter Handling

For information about properties to configure query parameter handling, see the Properties Reference.

By default, Java Agent considers any query parameters to be part of the URL, and inserts the entire string into the policy decision cache. For example, the agent inserts each of the following URLs in the cache, even though the root URL is the same:

http://agent.example.com:8080/protected/resource.jsp
http://agent.example.com:8080/protected/resource.jsp?a=value1
http://agent.example.com:8080/protected/resource.jsp?b=value2

Web applications that add new parameters to the URL on every request would fill the agent’s policy cache without actually using it, which in turn causes the agent to request policy decision to AM each time.

To prevent this behavior, configure agents to do one of the following:

Retain nominated URL parameters. For example, remove all except that are added as part of the policy evaluation.

Configure one of the following properties:
- Query Parameter List for Policy Evaluation
- Regex Query Parameters List for Policy Evaluation
Discard nominated URL parameters. For example, to remove all parameters added by the angular.js framework.

Configure one of the following properties:
- Remove Query Parameters List for Policy Evaluation
- Regex Remove Query Parameters List for Policy Evaluation

The properties are mutually exclusive, and the agent checks them in the following order of precedence:

Remove Query Parameters
Regular Expression Remove Query Parameters
Retain Query Parameters
Regular Expression Retain Query Parameters

Java Agent strips nominated query parameters from the URL before taking the following actions:

Asking AM for policy evaluation
Checking the not-enforced lists

Ensure the policies defined in AM, and the not-enforced rules configured for the agent, do not expect a parameter that has been removed.

Authentication Failure

For information about properties to configure notifications for authentication failure, see Authentication Failure.

To limit the amount of information available to malicious users, by default Java Agent returns an HTTP 400 message when it or AM cannot authenticate the end user, regardless of the reason.

If, for example the agent returns an "unknown user" message, malicious users can use that information to try with different user names until the error message changes to, for example, "wrong password".

The following table summarizes reasons for the agent to return an HTTP 400 message:

Reason Code Meaning

Reason Code	Meaning
`AUTHN_BOOKKEEPING_COOKIE_MISSING`	The agent cannot find the authentication tracking cookie, defined in Pre-Authentication Cookie Name. This error can happen if the user successfully authenticates, but clicks the back button of the browser to return to the previous page.
`NONCE_MISSING`	The agent found the authentication tracking cookie, but it cannot find the unique identifier of the authentication request inside the cookie. This error can happen if the user successfully authenticates, but clicks the back button of the browser to return to the previous page.
`BAD_AUDIENCE`	The audience in the JWT does not correspond to the audience in the cookie entry. This error can happen if all agents working in a cluster do not have the same Agent Profile Name.
`NO_TOKEN`	The agent cannot find the session ID token.
`TOKEN_EXPIRED`	The agent found the session ID token, but it is past its expiry date.
`AM_SAYS_INVALID`	The agent found the session ID token, the expiry time is correct, but AM returns that the ID token is invalid.
`JWT_INVALID`	The agent found the session ID token, but cannot parse it.
`EXCEPTION`	The agent found the session ID token, but threw an exception while parsing it. Alternatively, the agent cannot connect to AM to validate the ID token, maybe due to a network outage.

AUTHN_BOOKKEEPING_COOKIE_MISSING

The agent cannot find the authentication tracking cookie, defined in Pre-Authentication Cookie Name.

This error can happen if the user successfully authenticates, but clicks the back button of the browser to return to the previous page.

NONCE_MISSING

The agent found the authentication tracking cookie, but it cannot find the unique identifier of the authentication request inside the cookie.

This error can happen if the user successfully authenticates, but clicks the back button of the browser to return to the previous page.

BAD_AUDIENCE

The audience in the JWT does not correspond to the audience in the cookie entry.

This error can happen if all agents working in a cluster do not have the same Agent Profile Name.

NO_TOKEN

The agent cannot find the session ID token.

TOKEN_EXPIRED

The agent found the session ID token, but it is past its expiry date.

AM_SAYS_INVALID

The agent found the session ID token, the expiry time is correct, but AM returns that the ID token is invalid.

JWT_INVALID

The agent found the session ID token, but cannot parse it.

EXCEPTION

The agent found the session ID token, but threw an exception while parsing it.

Alternatively, the agent cannot connect to AM to validate the ID token, maybe due to a network outage.

An HTTP 400 message is not always helpful for debugging the agent flow or when another web application depends on the error message. To customize agent bahaviour, configure the following:

A URL or URI where the agent redirects the end user after the authentication failure. This way, you can control the message that the agent displays to the end user.
User-friendly messages that are mapped to the different conditions that may cause the agent to return an HTTP 400 message.

Connection Pooling

For information about properties to configure notifications for authentication failure, see the Properties Reference.

Use connection pooling to control the number of connections made by the Java Agent to AM. When AM is available over a high-bandwidth connection, connection pooling could possibly reduce performance.

Java Policy Agents 5.9.1

Features

Cross-Domain Single Sign-On

Login Redirect

Default Login Redirect

Redirect Login to a Realm Based on the Request Domain

Redirect Login to an OIDC Endpoint Based on the Request Domain

Redirect Login for Legacy Deployments That Require SSO Tokens

Redirect Login to Pages Behind a Firewall

Not Enforced Rules

Configure Not-Enforced Rules

Conventions for Not-Enforced Rules

Inverting rules

Invert specific rules

Invert all rules

Wildcards

Wildcard for not-enforced IP rules

Wildcards for not-enforced URI rules

Regular expressions

HTTP Methods

Cookie values

Header values

Compound rules

Extended characters

Extended characters in the resource path of a not-enforced rule

Extended characters in HTTP query parameters of a not-enforced rule

POST Data Preservation

Configure POST Data Preservation

Defend Against CSRF Attacks When Using POST Data Preservation

CSRF Attack When POST Data Preservation Is Disabled

CSRF Attack When POST Data Preservation Is Enabled

Continuous Security

Environment Maps With Customizable Keys

Environment Maps With Fixed Keys

Attribute Fetch Modes

Autonomous Mode

Login Attempt Limits

FQDN Checking

Cookie Reset Properties

Caching

Configuration Cache

Session Cache

Policy Decision Cache

Not-Enforced Lists Hit and Miss Caches

POST Data Preservation Cache

OpenID Connect JSON Web Token (JWT) Cache

Query Parameter Handling

Authentication Failure

Connection Pooling