Guide to installing and managing ForgeRock® Access Management Java agents. ForgeRock Access Management provides open source authentication, authorization, entitlement, and federation software.

Configuration Cache

When a Java agent with centralized configuration starts up, it makes a call to AM to retrieve a copy of the Java agent profile and stores it in the cache. The information stored in the cache is valid until one of the following events occurs:

• AM notifies the Java agent of changes to hot-swappable Java agent configuration properties. The agent flushes the configuration cache and rereads the agent profile from AM.

• The Java agent restarts.

• The Java agent rereads the configuration from AM or from local files at the frequency specified by the com.sun.identity.agents.config.load.interval property.

If notifications and the com.sun.identity.agents.config.load.interval property are disabled, cached configuration remains valid until the Java 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 occurs:

• 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 the org.forgerock.openam.agents.config.active.session.cache.ttl.minutes property.

Policy Decision Cache

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

• If the client's session is valid, the Java agent requests a policy decision from AM and then enforces it.

• If the client's session is not valid, the Java 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.

  Once the client authenticates, the Java agent requests policy decision to 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 the com.sun.identity.agents.polling.interval property	Policy decision
Administrator makes a change to policy configuration (and policy notifications are enabled)	All sessions and all policy decisions

Important

A Java agent that loses connectivity to AM cannot request policy decisions. Therefore, the Java 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 Java 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 agents maintain a hit cache and a miss cache for each of the not-enforced lists specified in "Not-Enforced Lists". 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 rules' evaluation 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 properties.

For more information about not-enforced cache lists, see "Not-Enforced Lists", Not-Enforced URI Processing Properties, and Not-Enforced IP Processing Properties.

POST Data Preservation Cache

When POST data preservation is enabled, the Java 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 by the com.sun.identity.agents.config.postdata.preserve.cache.entry.ttl property.

For more information about POST data preservation and its properties, see "POST Data Preservation" and "POST Data Preservation Properties".

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, Java agents cache decoded JWTs.

When a Java 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 Java agent retrieves the decoded JWT from the cache and continues processing the request.

• The hash is not in the cache. The Java 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 the org.forgerock.openam.agents.config.jwt.cache.ttl.minutes property.

For information about the properties that control the JWT cache, see "Profile Properties".

am.encryption.pwd

When using an encrypted password, set this to the encryption key used to encrypt the agent profile password.

org.forgerock.agents.fallback.mode.enabled

When true, the Agent runs in autonomous, "fallback" mode, independently of an AM instance.

The Agents allow access using only not-enforced rules. Access to any resource not covered by not-enforced rules is denied. For more information, see "Autonomous "Fallback" Mode".

Default: false

Type: Boolean

Hot-swap: No

Bootstrap property: Yes

Property: org.forgerock.agents.fallback.mode.enabled, introduced in Java Agent 5.7

Alias: com.forgerock.agents.config.fallback.mode, introduced in Java Agent 5.7

com.iplanet.am.naming.url

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

org.forgerock.agents.encrypted.password

When using a plain text password, set this to the password for the agent profile, and leave am.encryption.pwd blank.

When using an encrypted password, set this to the encrypted version of the password for the agent profile. Use the command ./agentadmin --encrypt agentInstance passwordFile to get the encrypted version.

Default: Empty

Type: String

Hot-swap: No

Bootstrap property: Yes

Property: org.forgerock.agents.encrypted.password, introduced in Java Agent 5.5.2

Alias: com.iplanet.am.service.secret, introduced in Java Agent 5.5.2

org.forgerock.agents.public.am.url

Specifies the full URL of AM when it is behind a proxy during the custom login redirection flow. For example, protocol://public_am_fqdn:port/openam.

Use this property both of the following points are true:

• Your environment uses custom login pages (non-OIDC-compliant flows), and the custom login pages are not in the same domain as the agent.

• Your custom login pages are in a network that can only access AM using a proxy, a firewall, or any other technology that remaps the AM URL to one accessible by the custom login pages.

Consider an example where the traffic between AM and the agent happens through the example-internal.com network, but the custom login pages are on the example-external.com domain. The traffic between the custom pages and AM is translated from am.example-internal.com into am.example-external.com.

You would configure https://am.example-external.com:8443/openam as the public AM URL.

The default value is a combination of the values of AM Host, AM Port, AM Protocol, and AM Path.

org.forgerock.agents.am.path

The URI under which AM is deployed, such as /openam.

Default: Empty

org.forgerock.agents.csv.monitoring.directory

The full path to the directory where the Java agent writes debug log files and CSV files. See Debug Logfile Directory.

Default: None

org.forgerock.agents.local.audit.file.path

The full path of the Java agent's local audit log file. See Audit Logfile Path.

Default: None; local auditing is disabled

org.forgerock.agents.lock.config.enabled

When true, specifies that an agent restart is required to allow agent configuration changes, even for hot-swappable parameters.

Default: false

Type: Boolean

Bootstrap property: Yes

Hot-swap: No

Property: org.forgerock.agents.lock.config.enabled, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.lock.enable, introduced in Java Agent 5.5.2

org.forgerock.agents.agent.profile.realm

The realm name where the agent authenticates to AM.

Default: / (top-level realm)

org.forgerock.agents.profile.name

The profile name used to fetch agent configuration data from AM.

Default: Empty

Type: String

Hot-swap: No

Bootstrap property: Yes

Property:

• org.forgerock.agents.profile.name, introduced in Java Agent 5.5.2

• com.sun.identity.agents.app.username, introduced in Java Agent 5.5.2

• com.sun.identity.agents.config.profilename, introduced in Java Agent 5.5.2

com.sun.identity.agents.config.service.resolver

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Service Resolver Class Name

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

The name of a service resolver class to override the ForgeRock service resolver, and instantiate a new service resolver. Use this property to customize pre-handlers and post-handlers.

For information about how to add a custom task handler to the list of handlers the agent runs for each resource request, and some example handlers that you can use, see "Implementing Custom Task Handlers".

At startup, the Agent tries to instantiate the specified service resolver class. If unsuccessful, it instantiates the original service resolver.

Use the following functions to return a list of class names to customize the task handler:

• List<String> getPreInboundTaskHandlers(): Nominated classes are executed before all other inbound task handlers, and must implement IAmFilterTaskHandler.

• List<String> getPostInboundTaskHandlers(): Nominated classes are executed after all other inbound task handlers, and must implement IAmFilterTaskHandler.

• List<String> getPreSelfRedirectHandlers(): Nominated classes are executed before all other self-redirect task handlers, and must implement IAmFilterTaskHandler.

• List<String> getPostSelfRedirectHandlers(): Nominated classes are executed after all other self-redirect task handlers, and must implement IAmFilterTaskHandler.

• List<String> getPreFilterResultHandlers(): Nominated classes are executed before all other result handlers, and must implement IAmFilterResultHandler.

• List<String> getPostFilterResultHandlers(): Nominated classes are executed after all other result handlers, and must implement IAmFilterResultHandler.

If the named handler classes are not on the classpath, or do not implement the required interface, then:

• Handler instantiation fails.

• A message is logged at ERROR level.

• The agent abandons processing and returns an HTTP 500, effectively denying all requests.

When a handler list is built, make sure that your function returns true if appropriate. Handlers whose isActive is false are evicted from the handler list.

The process function for inbound and self-redirect handlers is invoked until a non-null value, such as continue or block, is returned. The non-null value becomes the result for that resource access. Returning null indicates to carry on to the other handlers. Any filter result handler that returns a null value causes an error.

Manually edit in bootstrap properties: Yes

Default: ServiceResolver.class name

Type: String

Hot-swap: No

Property: org.forgerock.agents.service.resolver.class.name, introduced in Java Agent 5.6.2.1

Login Form URI

Specifies the list of absolute URIs corresponding to a protected application's web.xml form-login-page element, such as /myApp/jsp/login.jsp.

Default: Empty

Property: com.sun.identity.agents.config.login.form

Login Error URI

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Specifies the list of absolute URIs corresponding to a protected application's web.xml form-error-page element, such as /myApp/jsp/error.jsp.

Default: Empty

Property: com.sun.identity.agents.config.login.error.uri

Use Internal Login

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

When enabled, the Java agent uses the internal default content file for the login.

Default: true

Property: com.sun.identity.agents.config.login.use.internal

Login Content File Name

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Full path name to the file containing custom login content when Use Internal Login is enabled.

Default: FormLoginContent.txt

Property: com.sun.identity.agents.config.login.content.file

Redirect to AM's Success URL

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

• true: The agent redirects to the success URL specified in the AM service, if any.

  If no success URL is specified in AM, the agent redirects to the original requested URL, if any.

• false: The agent redirects to the requested URL, if any.

For more information about configuring success URLs in AM, see Configuring Success and Failure Redirection URLs.

Default: false

Type: Boolean

Hot-swap: Yes

Property: org.forgerock.agents.authn.success.redirect.session.url.enabled, introduced in Java Agent 5.6.3

Authentication Exchange URI

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

Allows the administrator to define an endpoint to facilitate the exchange of SSO tokens for OIDC JWTs.

Default: Empty

Type: String (URL of a dummy endpoint within the Agent)

Hot-swap: Yes

Property: org.forgerock.agents.authn.exchange.uri, introduced in Java Agent 5.7

Authentication Exchange Cookie Name

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

Allows the administrator to define an endpoint to facilitate the exchange of SSO tokens for OIDC JWTs.

Default: Empty

Type: String (valid cookie name)

Hot-swap: Yes

Property: org.forgerock.agents.authn.exchange.cookie.name, introduced in Java Agent 5.7

Application Logout Handler

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.logout.application.handler

Application Logout URI

A map of request URIs that cause logout of the user session when invoked. Use the key:value format web application name:logout URI.

To set a global logout URI for applications without other logout URIs defined, leave the key empty, and set the value as /logout.jsp.

To set a logout URI for a specific application, set the key to the name of the application, and set the value to the value of application logout page.

Default: Empty

Type: Map, with format application name:logout URI

Hot-swap: Yes

Property: org.forgerock.agents.logout.endpoint.map, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.logout.uri, introduced in Java Agent 5.5.2

Logout Request Parameter Map

Map of parameters in the HTTP request that trigger logout events. Use the key:value format application name:parameter name to trigger logout.

To set a global logout request parameter for applications without other logout request parameters defined, leave the key empty, and set the value to logoutparam.

To set a logout URI for a specific application, set the key to the name of the application, and set the value to an application logout request parameter, such as logoutparam.

Default: Empty

Type: Map, with format application name:HTTP parameter name

Hot-swap: Yes

Property: org.forgerock.agents.logout.request.param.map, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.logout.request.param, introduced in Java Agent 5.5.2

Logout Introspect Enabled

When true, the Java agent checks the HTTP request body to locate the value of Logout Request Parameter Map.

Default: false

Type: Boolean

Hot-swap: Yes

Property: org.forgerock.agents.logout.introspection.enabled, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.logout.introspect.enabled, introduced in Java Agent 5.5.2

Logout Goto URI

A map of request URIs to go to after logout using an endpoint defined in Application Logout URI.

To set a global URI for applications without other logout URIs defined, leave the key empty, and set a return URI such as /return.html.

To set a logout URI for a specific application, set the key to the name of the application, and set the return URI to the value of application logout entry URI, such as /myApp/return.html.

Default: Empty

Type: Map, with format application name:goto URI

Hot-swap: Yes

Property: org.forgerock.agents.logout.goto.map, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.logout.entry.uri, introduced in Java Agent 5.5.2

Resource Access Denied URI

The URIs of custom pages to return when access is denied. The key is the web application name. The value is the custom URI.

To set a global custom access denied URI for applications without other custom access denied URIs defined, leave the key empty and set the value to the global custom access denied URI, /sample/accessdenied.html.

To set a custom access denied URI for a specific application, set the key to the name of the application, and the value to the application access denied URI, such as /myApp/accessdenied.html.

Tip

Specify a full URL if required, including the host name. For example: https://help.example.com/errors/accessdenied.html.

Default: Empty

Type: Map, with format application name:URI

Hot-swap: Yes

Property: org.forgerock.agents.access.denied.uri.map, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.access.denied.uri, introduced in Java Agent 5.5.2

Not-Enforced Compound Rules Separator

Specifies a delimiter for the not-enforced compound rules. The delimiter can be a single character or a string. For example, setting the delimiter to && allows compound rules to be specified as:

GET 10.5.1.5 100.2.21.36 && /public/*
REGEX 10\.4\.3\.5 && [^/]+\/free.jpg

Default: | (pipe)

Type: String

Hot-swap: Yes

Property:org.forgerock.agents.notenforced.compound.separator, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.notenforced.rule.compound.separator, introduced in Java Agent 5.5.2

For information about not-enforced rule evaluation and caching, see "Not-Enforced Lists".

Not-Enforced URIs

A space-delimited list of URIs that do not require authentication. The following example requires no authentication to access content in the /public and /images paths:

/public/* /images/*

Use the following format to specify not-enforced URIs in a local configuration file, where n is a unique, incrementing integer:

org.forgerock.agents.notenforced.uri.list[n]=Not enforced URI Rule

Percent-encode (URL-encode) spaces or other reserved characters. For example, /my%20public%20app/.

Use the following options to fine-tune the list of not-enforced URIs:

• Inverting Rules

  • Invert specific rules in the not-enforced URI list: Precede the rule with the keyword NOT, separated by a space (blank) character. In the following example, any request for a .jpg file in the /private URI requires authentication:

    NOT /private/*.jpg

  • Invert all rules in the not-enforced URI list: Set the Invert Not-Enforced URIs property to true.

• Wildcards

  • *: Use this wildcard to match all characters in a not-enforced URI rule, except the question mark ? character. The wildcard cannot be escaped, and spans multiple levels in a URI. 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.

  • -*-: Use this wildcard to match all characters in a not-enforced URI 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/-*-

  Consider the following points when using wildcards:

  • Using * and -*- wildcards in the same rule is not supported. However, you can use them 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 falls back to evaluating 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

  To use a regular expression in a not-enforced URI rule, add the keyword REGEX followed by a blank (space) character before the URI. For example:

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

  Consider the following points when using regular expressions:

  • Using classic wildcards and regular expressions in the same rule is not supported.

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

• HTTP Methods

  To apply not-enforced rules only when the incoming request uses a specific HTTP method, add one or more of the following keywords to the not-enforced rule: 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. The following example does not require authentication for any request method to /public:

  /public/*

  When one or more HTTP methods are specified for a rule, the specified methods are not-enforced, but unspecified methods are enforced and require authentication.

  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 URL to match. The following example does not require authentication for GET and POST requests to /public:

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

  To invert a method, add an exclamation mark ! character in front of it. The following example requires authentication for POST requests to /public, but but does not require authentication for other HTTPS methods:

  !POST /public/*

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

• Cookie Values

  To apply not-enforced rules when the incoming request has a named cookie with a specified value, use the following syntax:

  COOKIE(Name/Value/Modifiers) Not Enforced URIs

  Name

  The name of the cookie to inspect for the specified value. By default, the search is case-sensitive.

  Value

  A string to search for in the value field of the specified cookie. By default, the search is case-sensitive.

  Modifiers

  One or more modifiers to change the lookup method:

  c

  Perform a case-insensitive search for the cookie name.

  i

  Perform a case-insensitive search for the cookie value.

  r

  Treat the string specified 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/*

  You can combine cookie filters with other filters, such as HTTP methods.

  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

  Note that 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.

• Header Values

  To apply not-enforced rules when the incoming request has a named header with a specified value, use the following syntax:

  HEADER(Name/Value/Modifiers) Not Enforced URIs

  Name

  The case-insensitive name of the header to inspect for the specified value.

  Value

  A string to search for in the value field of the specified header.

  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 allows access to .txt files in /yearly/2019/ when the request contains a header named ID (case-insensitive), with the value validated (case-insensitive):

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

  You can combine cookie filters with other filters, such as HTTP methods.

  The following example allows GET, POST, and PUT HTTP 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):

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

  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.

• Compound Not-Enforced Rules

  Compound not-enforced rules allow you to combine not-enforced URI and IP rules in a single rule. They can be configured either in the Not-Enforced URIs or the Not-Enforced Client IP List properties.

  To write not-enforced URI and IP rules, follow the guidelines explained in Not-Enforced IP Processing Properties and Not-Enforced URI Processing Properties.

  The format for compound rules requires the IP rule or list of IP rules, a delimiter, by default the horizontal line | character, and the URI rule or list of URI rules. Blank (space) characters around the delimiter are optional. For example:

  192.168.1.1-192.168.4.3 | /images/*

  In the example, the agent will not enforce any HTTP requests coming from the ip range 192.168.1.1-192.168.4.3 to any file (*) in the /images URI.

  When configuring compound rules, consider the following points:

  • Keywords, such as HTTP methods, NOT, and REGEX, are required at the beginning of the compound rule, and affect both the IP and the URI rules. For example:

    GET,POST 192.168.1.1-192.168.4.3 | /images/*

    In the preceding example, the agent will not enforce GET and POST HTTP requests coming from the ip range 192.168.1.1-192.168.4.3 to any file (*) in the /images URI.

    NOT,!POST 192.168.1.* | /private/*

    In the preceding example, the agent will defer to AM (NOT keyword) any request done to all supported HTTP methods but POST (!) coming from any ip address in the 192.168.1 subnet to any file (*) in the /private URI.

  • When working with the REGEX keyword, ensure both sides of the rule can be parsed as a regular expression. For example:

    POST,REGEX 192\.168\.10\.(10|\d) && \/images\/([^/])+\.*\.jpg

    Note that the delimiter in the previous example is &&. This is because the | character can lead to invalid regular expressions. To configure a different delimiter, see the Not-Enforced Compound Rules Multi-Value Separator property in Not-Enforced Processing Properties.

  • When dealing with compound rules, the agent caches hits and misses for each resource accessed. IP and URI not-enforced lists have a property each to enable or disable their caches; for compound rules, caching is enabled if either the IP or URI not-enforced cache is enabled. The size of its cache has the size of the larger of the two IP or URI cache sizes.

    For more information about not-enforced rule evaluation and caching, see "Not-Enforced Lists".

• Encoding Internationalized Resource Identifiers (IRIs)

  To match a resource that uses non-ASCII characters, percent-encode the resource when creating the rule.

  For example, to match resources under an IRI such as http://www.example.com/forstå, specify the following percent-encoded rule:

  /forst%C3%A5/*

Default: Empty

Type: List of URIs

Hot-swap: Yes

Property: org.forgerock.agents.notenforced.uri.list, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.notenforced.uri, introduced in Java Agent 5.5.2

Invert Not-Enforced URIs

When true, enforce policy for the URIs and patterns specified in Not-Enforced URIs instead of allowing access to them without authentication.

Caution

For security considerations, do not enable this property. Instead, ForgeRock recommends using the NOT keyword to invert specific rules in the Not-Enforced URI list.

Default: false

Type: Boolean

Hot-swap: No

Property: org.forgerock.agents.notenforced.uri.invert.enabled, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.notenforced.uri.invert, introduced in Java Agent 5.5.2

Not-Enforced URIs Cache Enabled

When true, the agent caches evaluation (hits and misses) of the Not-Enforced URIs . Enable this setting if you are configuring many rules, such as hundreds.

For more information, see "Not-Enforced Lists".

Default: true

Type: Boolean

Hot-swap: No

Property: org.forgerock.agents.notenforced.uri.cache.enabled, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.notenforced.uri.cache.enable, introduced in Java Agent 5.5.2

Not-Enforced URIs Cache Size

The maximum number of cached resource URLs that are matched by a not-enforced rule (inverted or not inverted).

Default: 1000

Type: Integer

Hot-swap: No

Property: org.forgerock.agents.notenforced.uri.cache.size, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.notenforced.uri.cache.size, introduced in Java Agent 5.5.2

Not Enforced Favicon

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

When true, the agents do not enforce access to any files named favicon.ico, by inserting an internal not-enforced rule of GET */favicon.ico.

Default: true

Type: Boolean

Hot-swap: No

Bootstrap property: Yes

Property: org.forgerock.agents.auto.not.enforce.favicon.enabled, introduced in Java Agent 5.7

Alias: org.forgerock.agents.auto.not.enforce.favicon, introduced in Java Agent 5.7

Refresh Session Idle Time

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

When set to true, the agent resets the CTS-based session idle time when granting access to a not-enforced URI, prolonging the time before the user must authenticate again. This setting has no effect on users with client-based (stateless) sessions.

Default: false

Property: com.sun.identity.agents.config.notenforced.refresh.session.idletime

For information about not-enforced rule evaluation and caching, see "Not-Enforced Lists".

Not-Enforced Client List

A space-delimited list of IP addresses or network CIDR notation for which no authentication is required.

Supported values are IPV4 and IPV6 addresses, IPV4 and IPV6 ranges of addresses delimited by the - character, and network ranges specified in CIDR notation. For example:

192.168.1.0/24 192.168.100.0/24
2001:5c0:9168:0:0:0:0:2/128
192.168.1.1-192.168.4.3
2001:5c0:9168:0:0:0:0:1-2001:5c0:9168:0:0:0:0:2

If you are using a local configuration file rather than the administration console, use the following format when specifying not-enforced client lists, where n is a unique, incrementing integer:

org.forgerock.agents.notenforced.ip.list[n]=Not enforced IP Rule

To fine-tune the not-enforced IP list, the Java agent supports inverting rules, using regular expressions and wildcards, and specifying HTTP methods:

• Inverting Rules

  Not-enforced IP rules can be inverted either by rule or by property:

  • By rule. Invert any rule in the Not-Enforced Client IP List property by preceding it with the keyword NOT, separated by a space (blank) character. In the following example, the agent will defer to AM any request from the network specified by the 192.168.1.0/24 CIDR notation:

    NOT 192.168.1.0/24

  • By property. Invert all the rules in the Not-Enforced Client IP List property by setting the Not-Enforced IP Invert List to true.

• Wildcards, Regular Expressions, and HTTP Methods

  For finer control over the filtering of not-enforced IP rules, use wildcards, regular expressions, HTTP methods, cookie values, and headers:

  • Wildcards

    The * wildcard matches all characters except the question mark ? character, and cannot be escaped. For example:

    192.168.*

    For more information on wildcard usage, see Specifying Resource Patterns with Wildcards.

  • Regular Expressions

    To use regular expressions in a not-enforced IP rule, add the keyword REGEX followed by a blank (space) character before the URI to match. For example:

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

    When using regular expressions in a not-enforced IP list, consider the following points:

    • The use of wildcards and regular expressions in the same rule is not supported.

    • The use of 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 will show in the logs.

  • HTTP Methods

    Specify not-enforced HTTP methods by adding one of the following keywords: GET,HEAD, POST, PUT, PATCH, DELETE, OPTIONS, and TRACE.

    By default, if no HTTP method is specified for a particular rule, all methods are not-enforced for that rule. For example, the following rule does not enforce every supported HTTP method for the ips specified by 192.168.10.*:

    192.168.10.*

    To specify which methods should not be not-enforced, add a comma-delimited list of methods followed by a blank (space) character before the URL to match. For example:

    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

    Any method that is not specified will be enforced.

    Methods can be inverted by adding an exclamation point ! character in front of them. For example, all methods but POST are enforced in the following example:

    !POST 192.168.1.0/24

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

  • Cookie Values

    To apply not-enforced rules when the incoming request has a named cookie with a specified value, use the following syntax:

    COOKIE(Name/Value/Modifiers) Not Enforced IPs

    Where:

    Name

    The name of the cookie to inspect for the specified value.

    The Agent searches for the cookie name, using a case-sensitive search. If a match is found, the cookie is returned. If the match fails, the Agent searches again, using a case-insensitive search. If a match is found the cookie is returned, and a warning is issued to the logs.

    Value

    A string to search for in the value field of the specified cookie.

    Modifiers

    Specify one or more of the following optional modifiers to alter the method for looking up the value:

    i

    Perform a case-insensitive search for the cookie value. By default, the search is case-sensitive.

    r

    Treat the string specified in Value as a regular expression.

    For example, to allow access from 192.168.* when there is a cookie named login_result present on the request that has a value VALID case-insensitive, specify a rule similar to the following:

    COOKIE(login_result/VALID/i) 192.168.*

    You can combine cookie filters with other filters, such as HTTP methods.

    For example, the following rule allows GET, POST, and PUT HTTP requests from the client IP range 192.168.*, providing that there is a cookie named internal present, and it has a value that matches the regular expression .*ID - that is; strings that end with ID - ignoring case:

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

    Note that combining a HEADER and COOKIE expression in the same rule implies a logical AND is applied, such that both expressions must match in order to apply. To apply the rules as a logical OR, create two separate rules.

  • Header Values

    You can create not-enforced rules that only apply when the incoming request has a named header, with a specified value.

    The syntax for specifying rules that apply to headers with a specified value is as follows:

    HEADER(Name/Value/Modifiers) Not Enforced IPs

    Where:

    Name

    Specifies the name of the header to inspect for the specified value.

    The name of the header is not case-sensitive.

    Value

    Specifies a string to look for in the value field of the specified header.

    Modifiers

    Specify one or more of the following optional modifiers to alter the method for looking up the value:

    i

    Perform a case-insensitive string comparison.

    r

    Treat the string specified in Value as a regular expression.

    For example, to allow access to the IP range 192.168.* when there is a header named ID present on the request that has a value validated, ignoring case, specify a rule similar to the following:

    HEADER(ID/validated/i) 192.168.*

    You can combine cookie filters with other filters, such as HTTP methods.

    For example, the following rule allows GET, POST, and PUT HTTP requests from the IP address range 192.168.*, providing that there is a header named internal present, and it has a value that matches the regular expression .*ID - that is; strings that end with ID - ignoring case:

    GET,POST,HEADER(internal/.*ID/ri),PUT 192.168.*

    Note that combining a HEADER and COOKIE expression in the same rule implies a logical AND is applied, such that both expressions must match in order to apply. To apply the rules as a logical OR, create two separate rules.

• Compound Not-Enforced Rules

  Compound not-enforced rules allow you to combine not-enforced URI and IP rules in a single rule. They can be configured either in the Not-Enforced URIs or the Not-Enforced Client IP List properties.

  To write not-enforced URI and IP rules, follow the guidelines explained in Not-Enforced IP Processing Properties and Not-Enforced URI Processing Properties.

  The format for compound rules requires the IP rule or list of IP rules, a delimiter, by default the horizontal line | character, and the URI rule or list of URI rules. Blank (space) characters around the delimiter are optional. For example:

  192.168.1.1-192.168.4.3 | /images/*

  In the example, the agent will not enforce any HTTP requests coming from the ip range 192.168.1.1-192.168.4.3 to any file (*) in the /images URI.

  When configuring compound rules, consider the following points:

  • Keywords, such as HTTP methods, NOT, and REGEX, are required at the beginning of the compound rule, and affect both the IP and the URI rules. For example:

    GET,POST 192.168.1.1-192.168.4.3 | /images/*

    In the preceding example, the agent will not enforce GET and POST HTTP requests coming from the ip range 192.168.1.1-192.168.4.3 to any file (*) in the /images URI.

    NOT,!POST 192.168.1.* | /private/*

    In the preceding example, the agent will defer to AM (NOT keyword) any request done to all supported HTTP methods but POST (!) coming from any ip address in the 192.168.1 subnet to any file (*) in the /private URI.

  • When working with the REGEX keyword, ensure both sides of the rule can be parsed as a regular expression. For example:

    POST,REGEX 192\.168\.10\.(10|\d) && \/images\/([^/])+\.*\.jpg

    Note that the delimiter in the previous example is &&. This is because the | character can lead to invalid regular expressions. To configure a different delimiter, see the Not-Enforced Compound Rules Multi-Value Separator property in Not-Enforced Processing Properties.

  • When dealing with compound rules, the agent caches hits and misses for each resource accessed. IP and URI not-enforced lists have a property each to enable or disable their caches; for compound rules, caching is enabled if either the IP or URI not-enforced cache is enabled. The size of its cache has the size of the larger of the two IP or URI cache sizes.

    For more information about not-enforced rule evaluation and caching, see "Not-Enforced Lists".

• Encoding Internationalized Resource Identifiers (IRIs)

  To match a resource that uses non-ASCII characters, percent-encode the resource when creating the rule.

  For example, to match resources under an IRI such as http://www.example.com/forstå, specify the following percent-encoded rule:

  /forst%C3%A5/*

Default: Empty

Type: List of IP addresses

Hot-swap: Yes

Property: org.forgerock.agents.notenforced.ip.list, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.notenforced.ip, introduced in Java Agent 5.5.2

Invert Not Enforced IPs

When true, enforce policy for the IPs specified in Not-Enforced Client List property instead of allowing access to them without authentication.

Caution

For security considerations, do not enable this property. Instead, ForgeRock recommends using the NOT keyword to invert specific rules in the Not-Enforced Client IP List.

Default: false

Type: Boolean

Hot-swap: No

Property: org.forgerock.agents.notenforced.ip.invert.enabled, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.notenforced.ip.invert, introduced in Java Agent 5.5.2

Not-Enforced IP Cache Enabled

When true, the agent caches evaluation (hits and misses) of the not-enforced IP list. Enable this setting if you are configuring many rules, such as hundreds.

For more information, see "Not-Enforced Lists".

Default: true

Type: Boolean

Hot-swap: No

Property: org.forgerock.agents.notenforced.ip.cache.enabled, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.notenforced.ip.cache.enable, introduced in Java Agent 5.5.2

Not-Enforced IP Cache Size

The maximum number of cached IP addresses that are matched by a not-enforced rule (inverted or not inverted).

Default: 1000

Type: Integer

Hot-swap: No

Property: org.forgerock.agents.notenforced.ip.cache.size, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.notenforced.ip.cache.size, introduced in Java Agent 5.5.2

Profile Attribute Fetch Mode

• NONE: Profile attributes are not gathered

• HTTP_HEADER: Profile attributes are taken from the HTTP headers

• REQUEST_ATTRIBUTE: Profile attributes are taken from the request attributes

• HTTP_COOKIE: Profile attributes are taken from HTTP cookies

Default: NONE

Type: Constrained string

Hot-swap: Yes

Property: org.forgerock.agents.response.profile.fetch.mode, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.profile.attribute.fetch.mode, introduced in Java Agent 5.5.2

Profile Attribute Mapping

Maps the profile attributes to HTTP headers for the currently authenticated user. Map Keys are attribute names, and Map Values are HTTP header names. The user profile can be stored in LDAP or any other arbitrary data store.

To populate the value of profile attribute CN under CUSTOM-Common-Name: enter CN in the Map Key field, and enter CUSTOM-Common-Name in the Corresponding Map Value field. This corresponds to org.forgerock.agents.profile.attribute.map[cn]=CUSTOM-Common-Name.

In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, common-name becomes HTTP_COMMON_NAME.

Default: Empty

Type: Map, with format profile attribute:HTTP header

Hot-swap: Yes

Property: org.forgerock.agents.profile.attribute.map, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.profile.attribute.mapping, introduced in Java Agent 5.5.2

Response Attribute Fetch Mode

• NONE: Response attributes are not gathered

• HTTP_HEADER: Response attributes are taken from the HTTP headers

• REQUEST_ATTRIBUTE: Response attributes are taken from the request attributes

• HTTP_COOKIE: Response attributes are taken from HTTP cookies

Default: NONE

Type: Constrained string

Hot-swap: Yes

Property: org.forgerock.agents.response.attribute.fetch.mode, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.response.attribute.fetch.mode, introduced in Java Agent 5.5.2

Response Attribute Mapping

Maps the policy response attributes to HTTP headers for the currently authenticated user. The response attribute is the attribute in the policy response to be fetched.

To populate the value of response attribute uid under CUSTOM-User-Name: enter uid in the Map Key field, and enter CUSTOM-User-Name in the Corresponding Map Value field. This corresponds to org.forgerock.agents.response.attribute.map[uid]=Custom-User-Name.

In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, response-attr-one becomes HTTP_RESPONSE_ATTR_ONE.

Default: Empty

Type: Map, with format response attribute:HTTP header

Hot-swap: Yes

Property: org.forgerock.agents.response.attribute.map, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.response.attribute.mapping, introduced in Java Agent 5.5.2

Cookie Separator Character

The separator for multiple values of the same attribute when it is set as a cookie.

Default: |

Type: String

Hot-swap: Yes

Property: org.forgerock.agents.attribute.cookie.separator, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.attribute.cookie.separator, introduced in Java Agent 5.5.2

Fetch Attribute Date Format

The java.text.SimpleDateFormat of date attribute values used when an attribute is set in an HTTP header.

Default: EEE, d MMM yyyy hh:mm:ss z

Type: String (java.text.SimpleDateFormat)

Hot-swap: Yes

Property: org.forgerock.agents.attribute.date.format, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.attribute.date.format, introduced in Java Agent 5.5.2

Attribute Cookie Encode

When true, attribute values are URL-encoded before being set as a cookie.

Default: true

Type: Boolean

Hot-swap: Yes

Property: org.forgerock.agents.attribute.cookie.encode.enabled, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.attribute.cookie.encode, introduced in Java Agent 5.5.2

Session Attribute Fetch Mode

• NONE: Session attributes are not gathered

• HTTP_HEADER: Session attributes are taken from the HTTP headers

• REQUEST_ATTRIBUTE: Session attributes are taken from the request attributes

• HTTP_COOKIE: Session attributes are taken from HTTP cookies

Default: NONE

Type: Constrained string

Hot-swap: Yes

Property: org.forgerock.agents.session.attribute.fetch.mode, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.session.attribute.fetch.mode, introduced in Java Agent 5.5.2

Session Attribute Mapping

Maps session attributes to HTTP headers for the currently authenticated user. The session attribute is the attribute in the session to be fetched.

To populate the value of session attribute UserToken under CUSTOM-userid: enter UserToken in the Map Key field, and enter CUSTOM-userid in the Corresponding Map Value field. This corresponds to org.forgerock.agents.session.attribute.map[UserToken]=CUSTOM-userid.

In most cases, in a destination application where an HTTP header name shows up as a request header, it is prefixed by HTTP_, lower case letters become upper case, and hyphens (-) become underscores (_). For example, success-url becomes HTTP_SUCCESS_URL.

Default: Empty

Type: Map, with format session attribute:HTTP header

Hot-swap: Yes

Property: org.forgerock.agents.session.attribute.map, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.session.attribute.mapping, introduced in Java Agent 5.5.2

 The following properties do not apply to Java Agents 5.7, although they may appear in the AM console:

Default Privileged Attribute

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.default.privileged.attribute

Privileged Attribute Type

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.privileged.attribute.type

Privileged Attributes To Lower Case

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.privileged.attribute.tolowercase

Privileged Session Attribute

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.privileged.session.attribute

Enable Privileged Attribute Mapping

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.privileged.attribute.mapping.enable

Privileged Attribute Mapping

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.privileged.attribute.mapping

 The following properties do not apply to Java Agents 5.7, although they may appear in the AM console:

Custom Authentication Handler

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.auth.handler

Custom Logout Handler

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.logout.handler

Custom Verification Handler

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.verification.handler

For information about continuous security, see "Continuous Security".

Continuous Security Cookies

Maps cookie values available in inbound resource requests to entries in the environmental conditions map, which Java agents send to AM during policy evaluation.

This property has the format [cookie_name]=map_entry_name, where:

• cookie_name specifies the name of the cookie in the inbound request.

  The Agent searches for the cookie name, using a case-sensitive search. If a match is found, the cookie is returned. If the match fails, the Agent searches again, using a case-insensitive search. If a match is found the cookie is returned, and a warning is issued to the logs.

• map_entry_name specifies the name of the entry within the environmental conditions map that contains the value of cookie_name.

Example:

org.forgerock.agents.continuous.security.cookies.map[trackingcookie1]=myCookieEntry

Java agents add entries from both of the continuous security properties into the environmental conditions map, which AM's authorization framework accesses during policy evaluation.

Use server-side authorization scripts to:

• Access the map's contents

• Write scripted conditions based on cookies and headers in the request

For more information about server-side authorization scripts in AM, see the ForgeRock Access Management Authorization Guide.

When you specify continuous security properties, Java agents generate environmental condition entries in the map as follows:

Key	Value
requestIp [a]	Contains the inbound request's IP address. The Java agent determines the IP as follows: If the com.sun.identity.agents.config.client.ip.header property is configured, the agent extracts the IP address from the header. If the com.sun.identity.agents.config.client.ip.header property is not configured, the agent uses the HttpServletRequest.getRemoteAddr Java function to determine the IP address.
requestDNSName [b]	Contains the inbound request's host name. The Java agent determines the host name as follows: If the com.sun.identity.agents.config.client.hostname.header property is configured, the agent extracts the host name from the header. If the com.sun.identity.agents.config.client.hostname.header property is not configured, the agent uses the HttpServletRequest.getRemoteHost Java function to determine the host name.
variable_name [c]	Contains an array of cookie or header values.
[a] The requestIp entry is created in the map regardless of how the continuous security properties are configured. [b] The requestDNSName entry is created in the map regardless of how the continuous security properties are configured. [c] There may be as many variable_name entries as values specified in the continuous security properties.

Consider the following example:

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

Assuming the incoming request contains an ssid cookie and an User-Agent header, the environmental conditions map would contain the following variables:

• requestIp, containing the IP address of the client. For example, 192.16.8.0.1.

• requestDNSName, containing the host name of the client. For example, client.example.com.

• mySsid, containing the value of the ssid cookie. For example, 77xe99f4zqi1l99z.

• myUser-Agent, containing the value of the from header. For example, Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko.

Default: Empty

Type: Map

Hot-swap: Yes

Property: org.forgerock.agents.continuous.security.cookies.map[cookie_name]=map_entry_name, introduced in Java Agent 5.5.2

Alias: org.forgerock.openam.agents.config.continuous.security.cookies, introduced in Java Agent 5.5.2

Continuous Security Headers

Maps header values in inbound resource requests to entries in the environmental conditions map, which Java agents send to AM during policy evaluation.

This property has the format [header_name]=map_entry_name, where:

• header_name specifies the name of the header in the inbound request.

• map_entry_name specifies the name of the entry within the environmental conditions map that contains the value of header_name.

Example:

org.forgerock.agents.continuous.security.headers.map[User-Agent]=myUserAgentHeaderEntry

Java agents add entries from both of the continuous security properties into the environmental conditions map, which AM's authorization framework accesses during policy evaluation.

Use server-side authorization scripts to:

• Access the map's contents

• Write scripted conditions based on cookies and headers in the request

For more information about server-side authorization scripts in AM, see the ForgeRock Access Management Authorization Guide.

When you specify continuous security properties, Java agents generate environmental condition entries in the map as follows:

Key	Value
requestIp [a]	Contains the inbound request's IP address. The Java agent determines the IP as follows: If the com.sun.identity.agents.config.client.ip.header property is configured, the agent extracts the IP address from the header. If the com.sun.identity.agents.config.client.ip.header property is not configured, the agent uses the HttpServletRequest.getRemoteAddr Java function to determine the IP address.
requestDNSName [b]	Contains the inbound request's host name. The Java agent determines the host name as follows: If the com.sun.identity.agents.config.client.hostname.header property is configured, the agent extracts the host name from the header. If the com.sun.identity.agents.config.client.hostname.header property is not configured, the agent uses the HttpServletRequest.getRemoteHost Java function to determine the host name.
variable_name [c]	Contains an array of cookie or header values.
[a] The requestIp entry is created in the map regardless of how the continuous security properties are configured. [b] The requestDNSName entry is created in the map regardless of how the continuous security properties are configured. [c] There may be as many variable_name entries as values specified in the continuous security properties.

Consider the following example:

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

Assuming the incoming request contains an ssid cookie and an User-Agent header, the environmental conditions map would contain the following variables:

• requestIp, containing the IP address of the client. For example, 192.16.8.0.1.

• requestDNSName, containing the host name of the client. For example, client.example.com.

• mySsid, containing the value of the ssid cookie. For example, 77xe99f4zqi1l99z.

• myUser-Agent, containing the value of the from header. For example, Mozilla/5.0 (Windows NT 6.3; Trident/7.0; rv:11.0) like Gecko.

Default: Empty

Type: Map

Hot-swap: Yes

Property: org.forgerock.agents.continuous.security.headers.map[header_name]=map_entry_name, introduced in Java Agent 5.5.2

Alias: org.forgerock.openam.agents.config.continuous.security.headers, introduced in Java Agent 5.5.2

For information about how the Java agent handles query parameters, see "Query Parameter Handling".

Remove Query Parameters

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

Specifies a list of query parameters to be removed from a URL for policy decision and caching purposes. The property has the format [Domain/path] | parameter[,parameter...] with no spaces between values. Specify values as follows:

• Domain/path

  Specifies the incoming request URL. It can take the following values:

  • A domain. For example, example.com.

    When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

    Domains can also include path information, for example, example.com/market, but cannot specify ports.

  • A subdomain. For example, mydomain.example.com.

    When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

    Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

  • A path. For example, /myapp.

  • No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

• parameter[,parameter...]

  Specifies a comma-separated list of query parameters to remove from the incoming request URL.

  Consider the following constraints when constructing the list of parameters:

  • Add a comma (,) character at the beginning or the end of the list to remove all unnamed parameters. For example, myapp.example.com/customers|,lang would match both lang and any unnamed parameters.

  • Add the asterisk (*) character to the list to remove all parameters, including unnamed ones.

  The remaining parameters (those that do not match the list of parameters) are sorted alphabetically.

Examples:

org.forgerock.agents.unwanted.http.url.param.list[0]=myapp.example.com/customers|location,lang
      org.forgerock.agents.unwanted.http.url.param.list[1]=example.com/customers|*

For example, an incoming URL request such as http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456 that matches a rule such as myapp.example.com/customers|,lang, will be cached by the agent as http://myapp.example.com/customers?area=1343456&country=uk, where both lang and the unnamed parameter are removed and the rest of the parameters are sorted alphabetically.

Default: Empty

Type: List of HTTP query parameter names

Hot-swap: Yes

Property: org.forgerock.agents.unwanted.http.url.param.list[n], introduced in Java Agent 5.5.2

Alias: org.forgerock.openam.agents.config.conditional.unwanted.http.url.params, introduced in Java Agent 5.5.2

Regular Expression Remove Query Parameters

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

Specifies a list of regular expressions the agent uses to match query parameters to be removed from a URL for policy decision and caching purposes. The property has the format [Domain/path] | regular_expression[,regular_expression...] with no spaces between values. Specify values as follows:

• Domain/path

  Specifies the incoming request URL. It can take the following values:

  • A domain. For example, example.com.

    When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

    Domains can also include path information, for example, example.com/market, but cannot specify ports.

  • A subdomain. For example, mydomain.example.com.

    When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

    Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

  • A path. For example, /myapp.

  • No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

• regular_expression[,regular_expression...]

  Specifies a comma-separated list of regular expressions the agent uses to match query parameters to be removed from the incoming request URL.

  Consider the following constraints when constructing your list of regular expressions:

  • Add a comma (,) character at the beginning or the end of the list to remove all unnamed parameters. For example, myapp.example.com/customers|,lang would match both lang and any unnamed parameters.

  • Consider creating multiple simple regular expressions instead of a single complicated one.

  The remaining parameters (those that do not match the list of parameters) are sorted alphabetically.

Examples:

org.forgerock.agents.unwanted.http.url.params.list.regexp[0]=myapp.example.com|b.*,gp(a|p|s),
org.forgerock.agents.unwanted.http.url.params.list.regexp[1]=|.*

For example, an incoming URL request such as http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456 that matches a rule such as myapp.example.com/customers|,coun.*?, will be cached by the agent as http://myapp.example.com/customers?=bristol&lang=en_GB, where both country and unnamed parameter are removed and the remaining parameters are sorted alphabetically.

Default: Empty

Type: List of HTTP query parameter names

Hot-swap: Yes

Property: org.forgerock.agents.unwanted.http.url.params.regex.list[n], introduced in Java Agent 5.5.2

Alias: org.forgerock.agents.unwanted.http.url.params.regexp.list, introduced in Java Agent 5.5.2, and org.forgerock.openam.agents.config.conditional.unwanted.http.url.params.regexp, introduced in Java Agent 5.5.2

Retain Query Parameters

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

Specifies a list of query parameters to be retained for policy decision and caching purposes. The property has the format [Domain/path] | parameter[,parameter...] with no spaces between values. Specify values as follows:

• Domain/path

  Specifies the incoming request URL. It can take the following values:

  • A domain. For example, example.com.

    When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

    Domains can also include path information, for example, example.com/market, but cannot specify ports.

  • A subdomain. For example, mydomain.example.com.

    When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

    Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

  • A path. For example, /myapp.

  • No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

• parameter[,parameter...]

  Specifies a comma-separated list of query parameters to retain from the incoming request URL.

  Consider the following constraints when constructing the list of parameters:

  • Add a comma (,) character at the beginning or the end of the list to retain all unnamed parameters. For example, myapp.example.com/customers|,lang would match both lang and any unnamed parameters.

  • Add the asterisk (*) character to the list to retain all parameters, including unnamed ones.

  The remaining parameters (those that match the list of parameters) are sorted alphabetically.

Examples:

org.forgerock.agents.wanted.http.url.param.list[0]=myapp.example.com/news|area
org.forgerock.agents.wanted.http.url.param.list[1]=example.com/news|area,country,location,

For example, an incoming URL request such as http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456 that matches a rule such as myapp.example.com/customers|,lang, will be cached by the agent as http://myapp.example.com/customers?=bristol&lang=en_GB, where both lang and the unnamed parameter are retained and sorted alphabetically.

Default: Empty

Type: List of HTTP query parameter names

Hot-swap: Yes

Property: org.forgerock.agents.wanted.http.url.param.list[n], introduced in Java Agent 5.5.2

Alias: org.forgerock.openam.agents.config.conditional.wanted.http.url.params, introduced in Java Agent 5.5.2

Regular Expression Retain Query Parameters

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

Specifies a list of regular expressions the agent uses to match query parameters to be retained for policy decision and caching purposes. The property has the format [Domain/path] | regular_expression[,regular_expression...] with no spaces between values. Specify values as follows:

• Domain/path

  Specifies the incoming request URL. It can take the following values:

  • A domain. For example, example.com.

    When you specify a domain, Java agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

    Domains can also include path information, for example, example.com/market, but cannot specify ports.

  • A subdomain. For example, mydomain.example.com.

    When you specify a subdomain, Java agents match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com, too.

    Subdomains can include path information, for example, mydomain.example.com/secure, but cannot specify ports.

  • A path. For example, /myapp.

  • No value, in which case nothing is specified before the | character and the rule applies to every incoming request.

• regular_expression[,regular_expression...]

  Specifies a comma-separated list of regular expressions the agent uses to match query parameters to be retained from the incoming request URL.

  Consider the following constraints when constructing your list of regular expressions:

  • Add a comma (,) character at the beginning or the end of the list to retain all unnamed parameters. For example, myapp.example.com/customers|,lang would match both lang and any unnamed parameters.

  • Consider creating multiple simple regular expressions instead of a single complicated one.

  The remaining parameters (those that match the list of parameters) are sorted alphabetically.

Examples:

org.forgerock.agents.wanted.http.url.params.list.regexp[0]=example.com/market|regist.*
      org.forgerock.agents.wanted.http.url.params.list.regexp[1]=myapp.example.com/register|,.*

For example, an incoming URL request such as http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456 that matches a rule such as myapp.example.com/customers|,coun.*?, will be cached by the agent as http://myapp.example.com/customers?=bristol,country=uk, where both country and the unnamed parameter are retained and sorted alphabetically.

Default: Empty

Type: List of HTTP query parameter names

Hot-swap: Yes

Property: org.forgerock.agents.wanted.http.url.params.list.regexp[n], introduced in Java Agent 5.5.2

Alias: org.forgerock.agents.wanted.http.url.params.regexp.list, introduced in Java Agent 5.5.2, and org.forgerock.openam.agents.config.conditional.wanted.http.url.params.regexp, introduced in Java Agent 5.5.2

Authentication Fail Reason Url

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

The URL or URI to which the agent redirects the user after a failed authentication. For example, app/AuthFailed.html.

Note that authentication failure can happen for reasons other than wrong credentials. For more information, see "Authentication Failure Notification".

If this property is not set, the agent redirects the user to the URL defined in the Goto URL property. If both are unset, the agent returns an HTTP 400 message.

To configure the agent to send the reason for authentication failure in a query parameter, configure Login Reason Parameter Name.

Default: Empty

Type: URI/URL string

Property: org.forgerock.agents.authn.fail.url, introduced in Java Agent 5.7

Authentication Fail Reason Parameter Name

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

Specifies a query parameter name to contains the reason why authentication failed. The agent appends this parameter to the URL or URI defined by Authentication Fail Reason Url .

For example, if the value of property is reason, the agent redirects the end user to a URL similar to the following:

http://myapp.example.com:8080/app/AuthFailed.html?reason=AUTHN_BOOKKEEPING_COOKIE_MISSING

If not set, the agent does not append the reason for the authentication failure, when redirecting to the URL or URI. This property requires Authentication Fail Reason Url to be set.

Caution

For increased security, remap the reason for authentication failure, using Authentication Fail Reason Parameter Value Map.

Default: Empty

Type: String

Property: org.forgerock.agents.authn.fail.reason.parameter.name, introduced in Java Agent 5.7

Authentication Fail Reason Parameter Value Map

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

Caution

After an authentication failure, malicious users can use the information you expose to gain access to the system. Map the reason for authentication failure to something generic, or something that is meaningful inside your organization.

Map reasons for authentication failure to custom messages, as follows:

Authentication Failure Reasons

Reason Code	Meaning
AUTHN_BOOKKEEPING_COOKIE_MISSING	The agent cannot find the authentication tracking cookie (defined in the org.forgerock.agents.authn.cookie.name property). 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 did 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	This reason can have the following meanings: The agent found the session ID token, but threw an exception while parsing it. The agent cannot connect to AM to validate the ID token, maybe due to a network outage.

Specify the authentication failure reason from the preceding table as the map key, and your custom error identifier string as the value. For example:

org.forgerock.agents.authn.fail.reason.remapper[TOKEN_EXPIRED]=MY_ERROR_MESSAGE

Consider remapping all the failure reasons to a new error message, for example, ERROR, then be specific on those that hold more meaning for your environment. For example:

org.forgerock.agents.authn.fail.reason.remapper=ERROR
org.forgerock.agents.authn.fail.reason.remapper[AUTHN_BOOKKEEPING_COOKIE_MISSING]=BACK_BUTTON_PRESSED
org.forgerock.agents.authn.fail.reason.remapper[NONCE_MISSING]=BACK_BUTTON_PRESSED

To map all the authentication failure reasons to the same message, you do not need to specify a key in the property.

This property requires Authentication Fail Reason Url to be set.

Default: Empty

Type: Map, keyed by reason for failure

Property: org.forgerock.agents.authn.fail.reason.remapper[REASON], introduced in Java Agent 5.7

Goto Url

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

The URL to which the agent redirects the user when required redirection properties are not set in the agent configuration.

For example, after an authentication failure, if the property Authentication Fail Reason Url is not set, the agent redirects the user to the URL defined in this property. If both are unset, the agent returns an HTTP 400.

Default: Empty

Type: String, or an URL or URI of an HTML or other page

Hot-swap: Yes

Property: org.forgerock.agents.default.goto.url, introduced in Java Agent 5.7

Alias: com.sun.identity.agents.config.openam.agent.default_goto_url, introduced before Java Agent 5.5.2

Cookie Name

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.iplanet.am.cookie.name

Http Only

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

When true, cookies are flagged as HTTPOnly. Use this property prevent scripts and third-party programs from accessing the cookies.

Default: true

Type: Boolean

Hot-swap: Yes

Property: com.sun.identity.cookie.httponly, introduced in Java Agent 5.5.2

Encode Cookies

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

When true, cookies are encoded.

Default: false

Type: Boolean

Hot-swap: Yes

Property: com.iplanet.am.cookie.encode, introduced in Java Agent 5.5.2

Pre-Authenticated Cookie Name

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

The name of the bookkeeping "pre-authentication" cookie the agent uses for unauthenticated requests, to check that the authentication URL (used to invoke AM for authentication) isn't being used in a replay attack.

• (Default) One cookie is used for all unauthenticated requests.

  Dozens or even hundreds of requests can be bundled into the same cookie, and if the number of concurrent requests is large enough, the cookie can exceed the browser size limit and requests can fail.

  As a workaround, add as many resources as possible to the not-enforced lists, because these are not tracked in the cookie.

• (From version 5.7) One cookie is used for each unauthenticated request The cookie name contains the secure ID in a user-defined manner.

  Place the %n string once in the name of the cookie. For example:

  org.forgerock.agents.authn.cookie.name=pre-authn-%n
  org.forgerock.agents.authn.cookie.name=pre-%n-authn
  org.forgerock.agents.authn.cookie.name=%n-pre-authn
  org.forgerock.agents.authn.cookie.name=%n

  Alternatively, set the cookie name to %n. The agent translates the string to a unique identifier when it creates the cookie.

  Caution

  Use this mode only if required; creating additional cookies can impact performance.

The following information is stored in the cookie:

• URL of the original request

• HTTP mode

• Secure ID (subsequently baked into the nonce of the returned JWT)

• Audience

• Relevant ACR information

• Transaction ID

• Authentication bookkeeping cookie expiry time

The cookie is compressed and finally signed.

Default: amFilterCDSSORequest

Type: String

Hot-swap: Yes

Property: org.forgerock.agents.authn.cookie.name, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.cdsso.cookie.name, introduced in Java Agent 5.5.2

Pre-Authenticated Cookie Max Age

Not available in the console for AM 6.5.x and earlier versions.

To set as a custom property in AM, go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Advanced > Custom Properties.

The maximum age in seconds of the authentication bookkeeping cookie.

Default: 300

Type: Integer

Hot-swap: Yes

Property: org.forgerock.agents.authn.cookie.max.age.seconds, introduced in Java Agent 5.6.3

SSO Cache Enable

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.amsso.cache.enable

Cross-Domain SSO

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

CDSSO is always enabled.

Property: com.sun.identity.agents.config.cdsso.enable

CDSSO Redirect URI

Specifies a URI the Java agent uses to process CDSSO requests.

Caution

Changing the value of this property while the Agent is running prevents it from functioning if OIDC authentication is being used. The Agent must be restarted as soon as the value in AM has been altered and the properties saved.

Default: None. The value of this property must be provided by AM.

Type: URI

Hot-swap: No

Property: org.forgerock.agents.authn.redirect.uri, introduced in Java Agent 5.5.2

Alias: com.sun.identity.agents.config.cdsso.redirect.uri, introduced in Java Agent 5.5.2

CDSSO Servlet URL

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.cdsso.cdcservlet.url

CDSSO Clock Skew

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.cdsso.clock.skew

CDSSO Trusted ID Provider

 This property does not apply to Java Agents 5.7, although it might appear in the AM console.

Property: com.sun.identity.agents.config.cdsso.trusted.id.provider

Secure Cookies Enable

When true, all cookies written by the agent are secure. For backward compatibility, the default is false.

Default: false

Type: Boolean

Hot-swap: Yes

Property: org.forgerock.agents.secure.cookies.enabled, introduced in Java Agent 5.5.2

Alias: com.iplanet.am.cookie.secure, introduced in Java Agent 5.5.2, and com.sun.identity.agents.config.cdsso.secure.enable, introduced in Java Agent 5.5.2