Java Agents 2024.9

Properties reference

This reference describes agent configuration properties.

When you create an agent profile, you choose whether to store the agent configuration in AM’s configuration store or locally to the agent installation. The local configuration file syntax is the same as that of a standard Java properties file.

Property aliases

A property alias specifies a path for a property. A property can have multiple aliases but each alias is unique to that property.

How the agent manages multiple aliases

When you assign multiple values to the same property through different aliases, the agent assigns the values as follows:

  • For list properties, it appends each assignment to the list.

  • For simple string properties, it overwrites the current value with each new value. The final value is the last value to be assigned.

The following example assigns different values to a string property with three aliases:

com.sun.identity.agents.app.username=one
com.sun.identity.agents.config.profilename=two
org.forgerock.agents.profile.name=three

The final value of the property is three, the last value to be assigned.

How AM manages multiple aliases

Each version of AM recognizes a different group of agent aliases. When you are using AM commands, such as ssoadm to configure an agent, consider the following points on using recognized and unrecognized aliases:

  • When you use a recognized alias in an ssoadm command (for example, com.sun.identity.agents.config.notenforced.ip.cache.size=2000), the agent updates the value for the property represented by that alias.

    For the above example, Max Entries in Not-Enforced IP Cache is displayed as 2000 in the Application tab of the AM console.

  • When you use an unrecognized alias in an ssoadm command (for example, org.forgerock.agents.notenforced.ip.cache.size=4000), the agent creates a custom property.

    For the above example, org.forgerock.agents.notenforced.ip.cache.size=4000 is displayed in Custom Properties, in the Advanced tab of the AM console.

  • When a property is set by both a standard property and a custom property, the custom property takes precedence. The value of the standard property is not updated, and both values are displayed in the configuration.

List properties

List properties can be configured with or without an index location. The following formats are allowed and equivalent:

property[0]=one
property[1]=two
property[2]=three
property=one
property=two
property=three

When the agent assigns values to a list property, it adds to the list in the order the assignments are made, ignoring any index specified, and appending to the end of the list. The following formats are equivalent:

property[]=one
property[]=two
property[]=three
property[10]=one
property[1]=two
property[42]=three

The agent uses the index location only in the following cases:

  • When the index location is set to @ and the value is comma-separated:

    The agent sets multiple properties according to the number of comma-separated values specified. In the following example, there are three comma-separated values:

    property[@]=one,two,three

    The agent sets three individual properties. The final assignment is as follows:

    property[]=one
    property[]=two
    property[]=three
  • When the value for an index location is empty:

    The agent deletes that location in the list. In the following example, the last value for index location [1] is empty:

    property[0]=one
    property[1]=two
    property[2]=three
    property[1]=

    The agent deletes index location [1] from the list and then moves index location [2] to [1]. The final assignment is as follows:

    property[0]=one
    property[1]=three
  • When the index location is empty and the value is empty:

    The agent deletes all values from the list; the list exists, but is empty. In the following example, the second value for index location [] is empty:

    property[]=one
    property[]=
    property[]=two
    property[]=three

    The agent does the following:

    • Adds the text "one" to the list

    • Deletes all values from the list

    • Adds the text "two" into index location [0]

    • Adds the text "three" into index location [1]

    The final assignment is as follows:

    property[0]=two
    property[1]=three

List of bootstrap properties

Property Description Function

Agent

Profile, Required

Profile, Required

Authentication service, Required

Authentication service, Required

Authentication service, Required

Authentication service, Required

Audit

Audit

Deprecated

Audit

Audit

Agent, Required

Monitoring

Profile

Connection pooling

Connection pooling

Connection pooling

Audit

Notifications

Notifications

Global

Encryption, Required

Profile

Session

Connection pooling

Connection pooling

Not-enforced

Profile

Profile

Audit

Profile, Required

Session

Profile

Policy enforcement

POST data preservation

Profile

Connection pooling

Policy enforcement

Not-enforced

Policy enforcement

POST data preservation

POST data preservation

POST data preservation

POST data preservation

Miscellaneous, Required

Miscellaneous

Session

Agent

List of all properties

Property Description (UI name) Function

Access denied

Logs

Agent

Profile, Required

Profile, Required

Agent

Agent

Agent

Logout

Authentication service, Required

Authentication service, Required

Authentication service, Required

Authentication service, Required

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Audit

Audit

Audit

Deprecated

Audit

Audit

Audit

Login

Login

Authentication failure

Authentication failure

Authentication failure

Cross-domain single sign-on, Required

Agent, Required

Bad configuration detection

Bad configuration detection

Bad configuration detection

Client identification, Continuous security

Client identification, Continuous security

Client identification

Client identification

Logout

Profile

Container, Not-enforced

Container, Not-enforced

Continuous security

Continuous security

SSO cookie handling

Cookie reset

Attributes

Monitoring

Miscellaneous

Fully qualified domain name

Attributes

Policy enforcement

Profile

Connection pooling

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Cookie

Fully qualified domain name

Global

Connection pooling

Connection pooling

Cookie

Connection pooling

Miscellaneous

Cookie

Audit

Logout

Not-enforced

Not-enforced

Notifications

Notifications

Notifications

Notifications

Policy enforcement

POST data preservation

Global

Login

Custom login redirect, Login redirect, SSO cookie handling

User mapping

Miscellaneous, Required

Encryption, Required

Authentication service, Encryption

Profile

SameSite

Session

Monitoring

Attributes

Fully qualified domain name

Fragment

Policy enforcement

Global

Authentication failure

Global

Global

Global

Global

Global

Connection pooling

Miscellaneous

Connection pooling

Miscellaneous

Not-enforced

Not-enforced

Not-enforced

Policy enforcement

Profile

Profile

Profile

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Cookie

Audit

Locale

Locale

Profile, Required

Deprecated

Deprecated

Custom login redirect, Login redirect

Login

Logout

Logout

Logout

Cookie, Pre-authentication

Session

Profile

Not-enforced

Not-enforced

Policy enforcement

POST data preservation

Profile

Connection pooling

Cookie

Policy enforcement

POST data preservation

Not-enforced

Not-enforced

Not-enforced

Not-enforced

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Policy enforcement

Policy enforcement

Policy enforcement

POST data preservation

POST data preservation

Cookie, POST data preservation

POST data preservation

POST data preservation

POST data preservation

POST data preservation

POST data preservation

POST data preservation

POST data preservation

Policy enforcement

Cookie, Pre-authentication

Cookie, POST data preservation, Pre-authentication

Attributes, Cookie reset, Profile

Profile

Miscellaneous, Required

Query parameter

Configure behaviour

Agent

Miscellaneous

Login

Query parameter

Query parameter

Query parameter

Cookie reset

Cookie reset

Cookie reset

Attributes, Response

Response

Policy enforcement

Configure behaviour

Miscellaneous

Attributes, Cookie reset, Session

Session

Session

SameSite

SameSite

SSO cookie handling

Agent

Cross-domain single sign-on

User mapping

User mapping

User mapping

Profile

Timeout

Timeout

Cross-site scripting

Cross-site scripting

Access denied

Access Denied URI Map

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 web applications without other custom access denied URIs defined, leave the key empty and set the value to the global custom access denied URI, /s6ample/accessdenied.html.

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

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

Property name

org.forgerock.agents.access.denied.uri.map

Aliases

com.sun.identity.agents.config.access.denied.uri
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.access.denied.uri.map
  Introduced in Java Agent 5.6

Function

Access denied

Type

Map

  • Keys: web application

  • Values: URI of page saying 'access denied'

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Access Denied URI Map

Legacy title: Resource Access Denied URI

Agent

Alternative Agent Protocol

In environments when agents are behind a load balancer or reverse proxy which does a SSL offloading, the request URL is changed to match the URL that the agent receives.

The agent then uses the new URL as the redirection value in the pre-authentication cookie, created during the first unauthenticated request to the agent.

Use the following properties to override the agent redirection value with the URL of the original client request: Alternative Agent Host Name, and Alternative Agent Port Number.

Property name

org.forgerock.agents.agent.protocol

Aliases

com.sun.identity.agents.config.agent.protocol
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.agent.protocol
  Introduced in Java Agent 5.6

Function

Agent

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: Alternative Agent Protocol

Autonomous mode

When true 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.

Property name

org.forgerock.agents.fallback.mode.enabled

Aliases

com.forgerock.agents.config.fallback.mode
  Introduced in Java Agent 5.9.0

org.forgerock.agents.fallback.mode.enabled
  Introduced in Java Agent 5.9.0

org.forgerock.agents.autonomous.mode.enabled
  Introduced in Java Agent 5.9.0

Function

Agent, Required

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Recheck availability of AM

The duration after which the agent rechecks AM availability, when Autonomous mode is false, and AM becomes unavailable at runtime.

Consider these points when you configure this property:

  • If the duration is too short, the agent checks AM availability too often, and agent performance can be reduced.

  • If the duration is zero, the agent checks AM availability for every call. Requests that match not-enforced rules can take longer.

Property name

org.forgerock.agents.am.unavailability.recheck.window.in.seconds

Aliases

org.forgerock.agents.am.unavailability.recheck.window.in.seconds
  Introduced in Java Agent 5.9.0
  Recognized from AM 7.2

Function

Agent

Type

Integer

Default

5

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Profile (from AM 7.2)

Title: Recheck availability of AM

Alternative Agent Port Number

In environments when agents are behind a load balancer or reverse proxy which does a SSL offloading, the request URL is changed to match the URL that the agent receives.

The agent then uses the new URL as the redirection value in the pre-authentication cookie, created during the first unauthenticated request to the agent.

Use the following properties to override the agent redirection value with the URL of the original client request: Alternative Agent Host Name, and Alternative Agent Protocol.

Property name

org.forgerock.agents.agent.port

Aliases

com.sun.identity.agents.config.agent.port
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.agent.port
  Introduced in Java Agent 5.6

Function

Agent

Type

Integer

Default

-2147483648

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: Alternative Agent Port Number

Alternative Agent Host Name

In environments when agents are behind a load balancer or reverse proxy which does a SSL offloading, the request URL is changed to match the URL that the agent receives.

The agent then uses the new URL as the redirection value in the pre-authentication cookie, created during the first unauthenticated request to the agent.

Use the following properties to override the agent redirection value with the URL of the original client request: Alternative Agent Port Number and Alternative Agent Protocol.

Property name

org.forgerock.agents.agent.hostname

Aliases

com.sun.identity.agents.config.agent.host
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.agent.hostname
  Introduced in Java Agent 5.6

Function

Agent

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: Alternative Agent Host Name

Agent Filter Mode Map

A map of web application name to agent filter mode:

  • Key: Web application name.

  • Value: Agent filter mode.

The following example configures one filter mode for the BankApp web application. All other web applications use the default filter mode, URL_POLICY: org.forgerock.agents.filter.mode.map[BankApp]=SSO_ONLY

The following example configures the NONE filter mode for all applications in the web container: org.forgerock.agents.filter.mode.map[ALL]=NONE

The mode J2EE_POLICY does not apply to Java Agents 5.10. However, for backward-compatibility, it is displayed in the AM agent profile page.

Property name

org.forgerock.agents.filter.mode.map

Aliases

com.sun.identity.agents.config.filter.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.filter.mode.map
  Introduced in Java Agent 5.6.2.1

Function

Agent

Supported settings

NONE

The agent performs no authentication check, and grants access to any resource. When the value is NONE and logging is enabled, for auditing purposes, the agent filter logs all incoming requests.

SSO_ONLY

Any user having either a valid SSO token or JWT can access any resource.

URL_POLICY

The normal operating mode of the agent, in which resource access is granted by AM policy evaluation.

Default

URL_POLICY

Bootstrap property

Yes

Required property

No

Restart required

No

Local configuration file

AgentBootstrap.properties

AM console

Tab: Global

Title: Agent Filter Mode Map

Legacy title: Agent Filter Mode

Strategy when AM unavailable

When Autonomous mode is false, this property defines the strategy to use when AM becomes unavailable at runtime (for example, due to network errors).

Default: EVAL_NER_USE_CACHE_UNTIL_EXPIRED_ELSE_503

Property name

org.forgerock.agents.strategy.when.am.unavailable

Aliases

org.forgerock.agents.strategy.when.am.unavailable
  Introduced in Java Agent 5.9.0

Function

Agent

Supported settings

IMMEDIATE_403

When AM is unavailable, immediately return HTTP 403 for every request

IMMEDIATE_503

When AM is unavailable, immediately return HTTP 503 for every request

EVAL_NER_ELSE_403

When AM is unavailable, match incoming requests against not-enforced rules. Grant access to matched resources. Return HTTP 403 for all other requests.

EVAL_NER_ELSE_503

When AM is unavailable, match incoming requests against not-enforced rules. Grant access to matched resources. Return HTTP 503 for all other requests.

EVAL_NER_USE_CACHE_UNTIL_EXPIRED_ELSE_403

When AM is unavailable, match incoming requests against not-enforced rules. Resolve unmatched requests against the cache. Return HTTP 403 for requests that don’t match the cache result. Cached entries expire naturally. After the interval defined in "Policy Cache TTL" (org.forgerock.agents.policy.cache.ttl.minutes), this becomes exactly like EVAL_NER_ELSE_403.

EVAL_NER_USE_CACHE_UNTIL_EXPIRED_ELSE_503

When AM is unavailable, match incoming requests against not-enforced rules. Resolve unmatched requests against the cache. Return HTTP 503 for requests that don’t match the cache result. Cached entries expire naturally. After the interval defined in "Policy Cache TTL" (org.forgerock.agents.policy.cache.ttl.minutes), this becomes exactly like EVAL_NER_ELSE_503.

EVAL_NER_CACHE_INDEFINITELY_ELSE_403

As soon as AM becomes unavailable, freeze values in the agent caches and preserve them indefinitely. Match incoming requests against not-enforced rules. Resolve unmatched requests against the frozen cache. Return HTTP 403 for requests that don’t match the cache result.

EVAL_NER_CACHE_INDEFINITELY_ELSE_503

As soon as AM becomes unavailable, freeze values in the agent caches and preserve them indefinitely. Match incoming requests against not-enforced rules. Resolve unmatched requests against the frozen cache. Return HTTP 503 for requests that don’t match the cache result.

Default

EVAL_NER_USE_CACHE_UNTIL_EXPIRED_ELSE_503

Bootstrap property

Yes

Required property

No

Restart required

No

Local configuration file

AgentBootstrap.properties

Attributes

Session Attribute Fetch Mode

Map the name of an AM session attribute specified in Session Attribute Map as follows:

  • NONE: Do not map

  • HTTP_HEADER: Map the to the name of an HTTP session header

  • HTTP_COOKIE: Map to the name of an HTTP cookie

  • REQUEST_ATTRIBUTE: Map to the name of an HTTP session attribute

When the value is HTTP_COOKIE, Cookie Reset is automatically set to true. Before redirecting the client for login, and when the client logs out, the agent resets profile and session attributes cookies, and cookies in the Reset Cookie List.

Property name

org.forgerock.agents.session.attribute.fetch.mode

Aliases

org.forgerock.agents.session.attribute.fetch.mode
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.session.attribute.fetch.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Attributes, Cookie reset, Session

Supported settings

NONE

No AM attributes are mapped.

HTTP_HEADER

The named AM attributes are mapped to headers in the outgoing HTTP response.

REQUEST_ATTRIBUTE

The named AM attributes are mapped to request attributes in the outgoing HTTP response.

HTTP_COOKIE

The named AM attributes are mapped to cookies in the outgoing HTTP response.

Default

NONE

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Session Attribute Fetch Mode

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

Property name

org.forgerock.agents.attribute.cookie.separator

Aliases

com.sun.identity.agents.config.attribute.cookie.separator
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.attribute.cookie.separator
  Introduced in Java Agent 5.6

Function

Attributes

Type

String

Default

|

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Cookie Separator Character

Fetch Attribute Date Format

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

Property name

org.forgerock.agents.attribute.date.format

Aliases

com.sun.identity.agents.config.attribute.date.format
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.attribute.date.format
  Introduced in Java Agent 5.6

Function

Attributes

Type

String

Default

EEE, d MMM yyyy hh:mm:ss z

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Fetch Attribute Date Format

Response Attribute Fetch Mode

Map the name of an AM policy response attribute specified in Response Attribute Map as follows:

  • NONE: Do not map

  • HTTP_HEADER: Map the to the name of an HTTP response header

  • HTTP_COOKIE: Map to the name of an HTTP cookie

  • REQUEST_ATTRIBUTE: Map to the name of an HTTP request attribute

Property name

org.forgerock.agents.response.attribute.fetch.mode

Aliases

com.sun.identity.agents.config.response.attribute.fetch.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.response.attribute.fetch.mode
  Introduced in Java Agent 5.6

Function

Attributes, Response

Supported settings

NONE

No AM attributes are mapped.

HTTP_HEADER

The named AM attributes are mapped to headers in the outgoing HTTP response.

REQUEST_ATTRIBUTE

The named AM attributes are mapped to request attributes in the outgoing HTTP response.

HTTP_COOKIE

The named AM attributes are mapped to cookies in the outgoing HTTP response.

Default

NONE

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Response Attribute Fetch Mode

Profile Attribute Fetch Mode

Map the name of an AM profile attribute specified in Profile Attribute Map as follows:

  • NONE: Do not map

  • HTTP_HEADER: Map the to the name of an HTTP profile header

  • HTTP_COOKIE: Map to the name of an HTTP cookie

  • REQUEST_ATTRIBUTE: Map to the name of an HTTP profile attribute

Property name

org.forgerock.agents.profile.attribute.fetch.mode

Aliases

com.sun.identity.agents.config.profile.attribute.fetch.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.profile.attribute.fetch.mode
  Introduced in Java Agent 5.6

Function

Attributes, Cookie reset, Profile

Supported settings

NONE

No AM attributes are mapped.

HTTP_HEADER

The named AM attributes are mapped to headers in the outgoing HTTP response.

REQUEST_ATTRIBUTE

The named AM attributes are mapped to request attributes in the outgoing HTTP response.

HTTP_COOKIE

The named AM attributes are mapped to cookies in the outgoing HTTP response.

Default

NONE

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Profile Attribute Fetch Mode

Enable Attribute Encoding

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

Property name

org.forgerock.agents.attribute.cookie.encode.enabled

Aliases

com.sun.identity.agents.config.attribute.cookie.encode
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.attribute.cookie.encode.enabled
  Introduced in Java Agent 5.6

Function

Attributes

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Enable Attribute Encoding

Legacy title: Attribute Cookie Encode

Audit

Audit Log Directory

The full path to the directory for the agent’s local audit log files.

Default: None; local auditing is disabled

Property name

org.forgerock.agents.local.audit.dir.path

Aliases

org.forgerock.agents.local.audit.dir.path
  Introduced in Java Agent 2024.6

Function

Audit

Type

String

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Enable Local Audit Log Rotation

When true, rotate local audit log files that have reached the size specified by Local Audit Log Rotation Size.

Property name

org.forgerock.agents.local.audit.log.rotation.enabled

Aliases

org.forgerock.agents.local.audit.log.rotation.enabled
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.local.log.rotate
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Audit

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Global

Title: Enable Local Audit Log Rotation

Legacy title: Rotate Local Audit Log

Local Audit Log Rotation Size

The maximum size in bytes of the local audit log files. When Enable Local Audit Log Rotation is true, the agent rotates the log file when it reaches this size.

Property name

org.forgerock.agents.local.audit.log.rotation.bytes

Aliases

com.sun.identity.agents.config.local.log.size
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.local.audit.log.rotation.bytes
  Introduced in Java Agent 5.7

Function

Audit

Type

Integer

Default

52428800

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Global

Title: Local Audit Log Rotation Size

Audit Log Include Paths

A list of JSON paths to include in audit logs. Audit event fields use JSON pointer notation and are taken from the JSON schema for the audit event content.

To prevent logging of sensitive data for an audit event, the Common Audit Framework uses a safelist to specify which audit event fields appear in the logs. By default, only safelisted audit event fields are included in the logs.

Before you include non-safelisted audit event fields in the logs, consider the impact on security. Inclusion of some headers, query parameters, or cookies could cause credentials or tokens to be logged, and allow anyone with access to the logs to impersonate the holder of these credentials or tokens.

Audit Log Exclude Paths takes precedence over this property. If a path is specified here and in Audit Log Exclude Paths, the corresponding audit event field is excluded.

The following example excludes Header1 but includes Header2 and Cookie1:

org.forgerock.agents.audit.exclude.path.list[0]=/access/http/request/headers/Header1Name

org.forgerock.agents.audit.include.path.list[0]=/access/http/request/headers/Header2Name

org.forgerock.agents.audit.include.path.list[1]=/access/http/request/cookies/Cookie1Name

Property name

org.forgerock.agents.audit.include.path.list

Aliases

org.forgerock.agents.audit.include.path.list
  Introduced in Java Agent 2024.6
  Recognized from AM 7.1

Function

Audit

Type

List

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Audit Log Exclude Paths

A list of JSON paths to exclude from audit logs. Audit event fields use JSON pointer notation and are taken from the JSON schema for the audit event content.

To prevent logging of sensitive data for an audit event, the Common Audit Framework uses a safelist to specify which audit event fields appear in the logs. By default, only safelisted audit event fields are included in the logs.

This property takes precedence over Audit Log Include Paths. If a path is specified here and in Audit Log Include Paths, the corresponding audit event field is excluded.

The following example excludes Header1 but includes Header2 and Cookie1:

org.forgerock.agents.audit.exclude.path.list[0]=/access/http/request/headers/Header1Name

org.forgerock.agents.audit.include.path.list[0]=/access/http/request/headers/Header2Name

org.forgerock.agents.audit.include.path.list[1]=/access/http/request/cookies/Cookie1Name

Property name

org.forgerock.agents.audit.exclude.path.list

Aliases

org.forgerock.agents.audit.exclude.path.list
  Introduced in Java Agent 2024.6

Function

Audit

Type

List

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Audit Logfile Retention Count

The number of audit log files to retain after rotation. When the specified limit is reached, the oldest file is deleted when a file rotation occurs.

When the value is -1, all rotated files are kept. When the value is, for example, 10, the current file and nine older rotated files are kept.

Property name

org.forgerock.agents.local.audit.log.retention.count

Aliases

org.forgerock.agents.local.audit.log.retention.count
  Introduced in Java Agent 5.7
  Recognized from AM 7

Function

Audit

Type

Integer

Default

-1

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Global (from AM 7)

Title: Audit Logfile Retention Count

Audit Access Types

The type of messages to audit.

Property name

org.forgerock.agents.audit.what

Aliases

com.sun.identity.agents.config.audit.accesstype
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.audit.what
  Introduced in Java Agent 5.6

Function

Audit

Supported settings

LOG_NONE

Don’t audit anything.

LOG_ALLOW

Audit only allowed requests.

LOG_DENY

Audit only denied requests.

LOG_BOTH

Audit both allowed and denied requests.

Default

LOG_NONE

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: Audit Access Types

Audit Log Location

The location where the agent logs audit messages. If Audit Access Types is LOG_NONE, this property has no effect.

Property name

org.forgerock.agents.audit.where

Aliases

com.sun.identity.agents.config.log.disposition
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.audit.where
  Introduced in Java Agent 5.6

Function

Audit

Supported settings

NONE

Don’t audit anything, anywhere.

LOCAL

Audit locally only.

REMOTE

Audit remotely only.

ALL

Audit both locally and remotely.

Default

NONE

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: Audit Log Location

Authentication failure

Authentication Fail Reason Parameter Name

A query parameter name to contain the reason why authentication failed. The agent appends this parameter to the URL or URI defined by Authentication Fail URL.

If this property is not set, the agent does not append the reason for the authentication failure, when redirecting to the URL or URI.

To reduce the risk of leaking useful information, configure Authentication Fail Reason Parameter Value Map to change the strings for the above values.

Property name

org.forgerock.agents.authn.fail.reason.parameter.name

Aliases

org.forgerock.agents.authn.fail.reason.parameter.name
  Introduced in Java Agent 5.7
  Recognized from AM 7

Function

Authentication failure

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Authentication Fail Reason Parameter Name

Authentication Fail Reason Parameter Value Map

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.

When Authentication Fail URL is set, this property maps reasons for authentication failure to custom messages, as follows:

  • AUTHN_BOOKKEEPING_COOKIE_MISSING: The agent cannot find the authentication tracking cookie. 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: 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.

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

Property name

org.forgerock.agents.authn.fail.reason.remapper

Aliases

org.forgerock.agents.authn.fail.reason.remapper
  Introduced in Java Agent 5.7
  Recognized from AM 7

Function

Authentication failure

Type

Map

  • Keys: failed auth reason code

  • Values: masked value

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Authentication Fail Reason Parameter Value Map

Authentication Fail URL

The URL or URI to which the agent redirects the user after a failed authentication.

If this property is not set, the agent redirects the user to the URL defined in Goto URL. If neither property is set, the agent returns an HTTP 400 Bad Request.

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

Property name

org.forgerock.agents.authn.fail.url

Aliases

org.forgerock.agents.authn.fail.url
  Introduced in Java Agent 5.7
  Recognized from AM 7

Function

Authentication failure

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Authentication Fail URL

Legacy title: Authentication Fail Reason Url

Goto URL

When Authentication Fail URL is not set, this property sets the URL or URI to which the agent redirects the user after a failed authentication. If neither property is set, the agent returns an HTTP 400 Bad Request.

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

Property name

org.forgerock.agents.default.goto.url

Aliases

com.sun.identity.agents.config.openam.agent.default_goto_url
  Introduced in Java Agent 5.0
  Recognized from AM 7

org.forgerock.agents.default.goto.url
  Introduced in Java Agent 5.7

Function

Authentication failure

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Goto URL

Authentication service

AM Authentication Service Path

The path to the AM server.

Property name

org.forgerock.agents.am.path

Aliases

com.iplanet.am.services.deploymentDescriptor
  Introduced in Java Agent 5.0

org.forgerock.agents.am.path
  Introduced in Java Agent 5.6

Function

Authentication service, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM Authentication Service Protocol

The protocol used by the AM server. Set to one of the following values:

  • HTTP

  • HTTPS

Property name

org.forgerock.agents.am.protocol

Aliases

org.forgerock.agents.am.protocol
  Introduced in Java Agent 5.6

com.iplanet.am.server.protocol
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Authentication service, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: AM Services

Title: AM Authentication Service Protocol

Encryption Key/Salt

The key/salt used by the default encryption class to perform encryption and decryption within the agent.

Generate a secure, random key with agentadmin --key or agentadmin --rotate commands as described in Rotate the agent profile password.

If this property is not set, the agent terminates with a configuration error.

If you are changing this property manually or with agentadmin --key, you must re-encrypt the agent profile password. For more information, refer to Encrypted Agent Password.

Property name

org.forgerock.agents.encryption.key

Aliases

org.forgerock.agents.encryption.key
  Introduced in Java Agent 5.10.1
  Recognized from AM 7.1

am.encryption.pwd
  Introduced in Java Agent 5.0

com.sun.identity.client.encryptionKey
  Introduced in Java Agent 5.0

Function

Authentication service, Encryption

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM Authentication Service Host Name

The AM server host name.

Property name

org.forgerock.agents.am.hostname

Aliases

com.iplanet.am.server.host
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.am.hostname
  Introduced in Java Agent 5.6

Function

Authentication service, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: AM Services

Title: AM Authentication Service Host Name

AM Authentication Service Port

The AM server port number.

Property name

org.forgerock.agents.am.port

Aliases

com.iplanet.am.server.port
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.am.port
  Introduced in Java Agent 5.6

Function

Authentication service, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: AM Services

Title: AM Authentication Service Port

Bad configuration detection

Bad advice loop termination HTTP status

When a user has insufficient credentials to access a requested resource, AM can return policy advice that requires the user to authenticate at a higher level.

If there is an error in the AM configuration, an infinite authentication loop can occur, where the user is repeatedly asked to authenticate.

This property defines the HTTP status code to return to the user’s browser when the agent breaks a loop.

Integers in the range 100-299 and 400-599 are valid; however, not all browsers accept all status codes in this range.

Property name

org.forgerock.agents.bad.advice.loop.termination.http.code

Aliases

org.forgerock.agents.bad.advice.loop.termination.http.code
  Introduced in Java Agent 2023.11
  Recognized from AM 7.1

Function

Bad configuration detection

Type

Integer

Default

508

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Bad advice loop termination counter

When a user has insufficient credentials to access a requested resource, AM can return policy advice that requires the user to authenticate at a higher level.

If there is an error in the AM configuration, an infinite authentication loop can occur, where the user is repeatedly asked to authenticate.

This property defines the maximum number of times the agent asks the user to authenticate before breaking a loop.

Property name

org.forgerock.agents.bad.advice.loop.termination.counter

Aliases

org.forgerock.agents.bad.advice.loop.termination.counter
  Introduced in Java Agent 2023.11
  Recognized from AM 7.1

Function

Bad configuration detection

Type

Integer

Default

5

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Bad advice loop termination URL

When a user has insufficient credentials to access a requested resource, AM can return policy advice that requires the user to authenticate at a higher level.

If there is an error in the AM configuration, an infinite authentication loop can occur, where the user is repeatedly asked to authenticate.

This property defines the URL or URI of a page to display when the agent breaks a loop. Consider indicating on the page that there is an AM configuration error.

Property name

org.forgerock.agents.bad.advice.loop.termination.url

Aliases

org.forgerock.agents.bad.advice.loop.termination.url
  Introduced in Java Agent 2023.11
  Recognized from AM 7.1

Function

Bad configuration detection

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Client identification

Client Hostname Header

The name of the HTTP header used to determine the hostname of a client. See also Client IP Address Header.

If this property is not set, the value returned by HttpServletRequest.getRemoteHost is used.

Property name

org.forgerock.agents.http.header.containing.remote.hostname

Aliases

org.forgerock.agents.http.header.containing.remote.hostname
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.client.hostname.header
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Client identification, Continuous security

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: Client Hostname Header

Client IP Validation Mode

For each authenticated request from a named web application, check that the IP address of the request satisfies one of the following acceptance criteria:

  • It originates from the IP address used for first authentication.

  • It has acceptable changes only, as mapped in Client IP Validation Address Map

  • If the web application is not named, check the the IP address globally, for all web applications.

Property name

org.forgerock.agents.original.ip.check.mode.map

Aliases

org.forgerock.agents.original.ip.check.mode.map
  Introduced in Java Agent 5.8.0
  Recognized from AM 7.1

Function

Client identification

Supported settings

OFF

IP address checking is disabled.

DENY

An "unacceptable" IP address change triggers an HTTP 403 response.

LOGOUT

An "unacceptable" IP address change causes the agent to invalidate the user token by calling the logout endpoint in AM and killing the user’s cookies.

Default

OFF

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application (from AM 7.1)

Title: Client IP Validation Mode

Client IP Validation Address Map

A map of acceptable alternative values for IP addresses, or address ranges in CIDR format, that incoming requests may change to without triggering DENY or LOGOUT behaviour.

This property is used by Client IP Validation Mode.

Property name

org.forgerock.agents.acceptable.ip.address.map

Aliases

org.forgerock.agents.acceptable.ip.address.map
  Introduced in Java Agent 5.8.0
  Recognized from AM 7.1

Function

Client identification

Type

Map

  • Keys: web application

  • Values: acceptable IP addresses, comma separated, CIDR format acceptable

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application (from AM 7.1)

Title: Client IP Validation Address Map

Client IP Address Header

The name of the HTTP header used to determine the IP address of a client. See also Client Hostname Header.

If this property is not set, the value returned by HttpServletRequest.getRemoteAddr is used.

Property name

org.forgerock.agents.http.header.containing.ip.address

Aliases

com.sun.identity.agents.config.client.ip.header
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.http.header.containing.ip.address
  Introduced in Java Agent 5.6

Function

Client identification, Continuous security

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: Client IP Address Header

Configure behaviour

Retain previous override behaviour

When true, the agent does not substitute the Alternative Agent Host Name, Alternative Agent Port Number or Alternative Agent Protocol into the URL used for matching against not enforced rules, or policy evaluation.

When false, the values are substituted as expected.

The default value preserves backward compatibility.

Property name

org.forgerock.agents.retain.previous.override.behaviour.enabled

Aliases

org.forgerock.agents.retain.previous.override.behaviour.enabled
  Introduced in Java Agent 2023.6

Function

Configure behaviour

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Raw URL path invalidation regex list

This property lists regular expressions, which are matched against every incoming URL path, before it is normalized.

If any regular expression matches, the request is rejected with an HTTP 400.

Note any regular expression in the list is not required to match the entire path, so "%5[Cc]" is sufficient, as opposed to "^.%5[Cc].$" (although the latter would also work).

Property name

org.forgerock.agents.raw.url.path.invalidation.regex.list

Aliases

org.forgerock.agents.raw.url.path.invalidation.regex.list
  Introduced in Java Agent 2024.9

Function

Configure behaviour

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Connection pooling

Max HTTP Connection Count

When Enable Connection Pooling is true, this property defines the maximum number of HTTP connections allowed at any time.

Property name

org.forgerock.agents.http.client.max.connections

Aliases

org.forgerock.agents.http.client.max.connections
  Introduced in Java Agent 5.8.0

Function

Connection pooling

Type

Integer

Default

1000

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Redirect

Title: Max HTTP Connection Count

HTTP Connection Timeout

When Enable Connection Pooling is true, this property defines the connection timeout in seconds.

Property name

org.forgerock.agents.http.client.connection.timeout.seconds

Aliases

org.forgerock.agents.http.client.connection.timeout.seconds
  Introduced in Java Agent 5.8.0

Function

Connection pooling

Type

Integer

Default

10

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Redirect

Title: HTTP Connection Timeout

Enable HTTP Connection Reuse

When Enable Connection Pooling is true, this property enables connection reuse.

Property name

org.forgerock.agents.http.client.reuse.connections.enabled

Aliases

org.forgerock.agents.http.client.reuse.connections.enabled
  Introduced in Java Agent 5.8.0

Function

Connection pooling

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Enable HTTP Connection State

This option only applies when these properties are true:

Set this property to true to change the Apache HTTP Client default behavior, and allow connection reuse.

Because the client certificate is defined at the client level, all requests to the same target share the same client certificate, so enabling this property should not be an issue.

Property name

org.forgerock.agents.http.client.connection.state.enabled

Aliases

org.forgerock.agents.http.client.connection.state.enabled
  Introduced in Java Agent 5.8.0

Function

Connection pooling

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Enable Connection Pooling

When true, the agent uses connection pooling. Use connection pooling to improve performance when AM is available over low bandwidth connections, or to throttle the maximum number of connections made by the agent.

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

Property name

org.forgerock.agents.use.connection.pooling.enabled

Aliases

org.forgerock.agents.use.connection.pooling.enabled
  Introduced in Java Agent 5.8.0

Function

Connection pooling

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

HTTP Socket Timeout

When Enable Connection Pooling is true, this property defines the socket timeout in seconds.

Property name

org.forgerock.agents.http.client.socket.timeout.seconds

Aliases

org.forgerock.agents.http.client.socket.timeout.seconds
  Introduced in Java Agent 5.8.0

Function

Connection pooling

Type

Integer

Default

10

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Enable HTTP Retry

When Enable Connection Pooling is true, this property enables retries after failed requests.

Property name

org.forgerock.agents.http.client.retry.requests.enabled

Aliases

org.forgerock.agents.http.client.retry.requests.enabled
  Introduced in Java Agent 5.8.0

Function

Connection pooling

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Container

Container Character Encoding

The character encoding used by the agent when encoding extended characters in the resource paths of not-enforced rules.

Property name

org.forgerock.agents.container.encoding

Aliases

org.forgerock.agents.container.encoding
  Introduced in Java Agent 5.9.1

Function

Container, Not-enforced

Type

String

Default

UTF-8

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Container Parameter Encoding

The character encoding used by the agent when encoding extended characters in the HTTP query parameters of not-enforced rules.

Property name

org.forgerock.agents.container.param.encoding

Aliases

org.forgerock.agents.container.param.encoding
  Introduced in Java Agent 5.9.1

Function

Container, Not-enforced

Type

String

Default

ISO-8859-1

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Continuous security

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

Property name

org.forgerock.agents.continuous.security.cookies.map

Aliases

org.forgerock.agents.continuous.security.cookies.map
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.continuous.security.cookies
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Continuous security

Type

Map

  • Keys: incoming cookie name

  • Values: name of entry in environment map

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Continuous Security Cookie Map

Legacy title: Continuous Security Cookies

Continuous Security Header Map

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

Example:

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

Property name

org.forgerock.agents.continuous.security.headers.map

Aliases

org.forgerock.agents.continuous.security.headers.map
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.continuous.security.headers
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Continuous security

Type

Map

  • Keys: incoming header name

  • Values: name of entry in environment map

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Continuous Security Header Map

Legacy title: Continuous Security Headers

Client Hostname Header

The name of the HTTP header used to determine the hostname of a client. See also Client IP Address Header.

If this property is not set, the value returned by HttpServletRequest.getRemoteHost is used.

Property name

org.forgerock.agents.http.header.containing.remote.hostname

Aliases

org.forgerock.agents.http.header.containing.remote.hostname
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.client.hostname.header
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Client identification, Continuous security

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: Client Hostname Header

Client IP Address Header

The name of the HTTP header used to determine the IP address of a client. See also Client Hostname Header.

If this property is not set, the value returned by HttpServletRequest.getRemoteAddr is used.

Property name

org.forgerock.agents.http.header.containing.ip.address

Aliases

com.sun.identity.agents.config.client.ip.header
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.http.header.containing.ip.address
  Introduced in Java Agent 5.6

Function

Client identification, Continuous security

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: Client IP Address Header

Maximum Decompression Size

The maximum size, in bytes, a compressed cookie is allowed to expand to when decompressed.

Property name

org.forgerock.agents.max.decompression.size.bytes

Aliases

org.forgerock.agents.max.decompression.size.bytes
  Introduced in Java Agent 5.10.0

Function

Cookie

Type

Integer

Default

32768

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Pre-Authn and Post Data Preservation Cookie Signing Value

The key to sign pre-authentication cookies and POST data preservation cookies.

The key is set during installation, when the agent requests the path to a file containing the cookie signing key, and then uses the key to set the cookie signing value in the AgentKey.properties file. For information about how to set or change the key after installation, see Rotate cookie signing keys.

For security, you are recommended to configure cookie signing. The agent does not sign cookies when:

  • The path to the signing key is left blank during installation.

  • The signing key in the AgentKey.properties file is less than 64-characters long.

Property name

org.forgerock.agents.cookie.signing.value

Aliases

org.forgerock.agents.cookie.signing.value
  Introduced in Java Agent 5.10.0

Function

Cookie, POST data preservation, Pre-authentication

Type

String

Bootstrap property

No

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentKey.properties

The maximum age in seconds of the pre-authentication cookie configured in Pre-Authentication Cookie Name.

Property name

org.forgerock.agents.authn.cookie.max.age.seconds

Aliases

org.forgerock.agents.authn.cookie.max.age.seconds
  Introduced in Java Agent 5.6.3.0
  Recognized from AM 7

Function

Cookie, Pre-authentication

Type

Integer

Default

600

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global (from AM 7)

Title: Max Age of Pre-Authentication Cookie

Legacy title: Pre-Authenticated Cookie Max Age

The load balancer cookie name. Make sure that this property has the same value as the AM property com.iplanet.am.lbcookie.name.

Property name

org.forgerock.agents.load.balancer.cookie.name

Aliases

org.forgerock.agents.load.balancer.cookie.name
  Introduced in Java Agent 5.8.0
  Recognized from AM 7.1

Function

Cookie

Type

String

Default

amlbcookie

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global (from AM 7.1)

Title: Load Balancer Cookie Name

Enable Encoded Cookies

When true, cookies are base64-encoded.

Property name

com.iplanet.am.cookie.encode

Aliases

com.iplanet.am.cookie.encode
  Introduced in Java Agent 5.6
  Recognized from AM 7

Function

Cookie

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7)

Title: Enable Encoded Cookies

Legacy title: Encode Cookies

Enable HTTP Only Cookies

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

Property name

com.sun.identity.cookie.httponly

Aliases

com.sun.identity.cookie.httponly
  Introduced in Java Agent 5.0
  Recognized from AM 7

Function

Cookie

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7)

Title: Enable HTTP Only Cookies

Legacy title: Http Only

The name of the pre-authentication cookie. This cookie tracks the progress of authentication with AM, and protects requests from replay attacks. It contains the following information:

  • URL of the original request

  • HTTP mode

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

  • Relevant ACR information

  • Transaction ID

  • Expiry time configured by Max Age of Pre-Authentication Cookie

(Before Java Agent 5.7), The agent creates a single cookie containing records to identify all concurrent authentication requests to AM. In environments with lots of concurrent requests, or where the protected URLs are long, the cookie can reach the maximum size supported by the browser. When this happens, new authentication requests fail and the agent issues a 403 HTTP message to the user.

(Java Agent 5.7 and later versions) The agent can optionally create a cookie for each authentication request to AM. In some environments, this creates a large number of cookies. If you have tests in your environment that make multiple requests to AM from the same browser, you may find intermittent 403 HTTP messages; browsers can limit how many cookies they handle.

Configure the cookie name as follows:

  • To use one cookie for all concurrent authentication requests to AM, configure as a string. For example, org.forgerock.agents.authn.cookie.name=cookie-name.

  • To use one cookie for each authentication request to AM, configure as %n, or as %n before, in the middle of, or after a string. When the agent creates the cookie, it translates the string %n into a unique identifier. For example:

    • org.forgerock.agents.authn.cookie.name=%n

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

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

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

The agent compresses and then signs the cookie.

Property name

org.forgerock.agents.authn.cookie.name

Aliases

com.sun.identity.agents.config.cdsso.cookie.name
  Introduced in Java Agent 5.0
  Recognized from AM 7

org.forgerock.agents.authn.cookie.name
  Introduced in Java Agent 5.6

Function

Cookie, Pre-authentication

Type

String

Default

amFilterCDSSORequest

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global (from AM 7)

Title: Pre-Authentication Cookie Name

Legacy title: Pre-Authenticated Cookie Name

Post Data Preservation Cookie Name

The name of the Post Data Preservation cookie. This cookie maintains the security of the data in unauthenticated POST requests. It contains a unique one-time code which is cross-checked against the stored data making it extremely difficult for malicious actors to replay the stored data for other users.

Since Java Agent 5.10, there is the option of creating one cookie for all concurrent PDP requests, or alternatively to have one uniqely named cookie per request.

If you have tests in your environment that make multiple PDP requests to the agent, you may find intermittent failures as browsers can limit how many cookies they handle.

Configure the cookie name as follows:

  • To use one cookie for all concurrent PDP requests to AM, configure as a string. For example, org.forgerock.agents.pdp.cookie.name=cookie-name.

  • To use one cookie for each authentication request to AM, configure as %n before, in the middle, or after a string. When the agent creates the cookie, it substitutes %n for a unique identifier. For example:

    • org.forgerock.agents.pdp.cookie.name=%n

    • org.forgerock.agents.pdp.cookie.name=%n-cookie-name

    • org.forgerock.agents.pdp.cookie.name=cookie-%n-name

    • org.forgerock.agents.pdp.cookie.name=cookie-name-%n

The agent compresses and then signs the cookie.

Property name

org.forgerock.agents.pdp.cookie.name

Aliases

org.forgerock.agents.pdp.cookie.name
  Introduced in Java Agent 5.10.0
  Recognized from AM 7.1

Function

Cookie, POST data preservation

Type

String

Default

PDP_Nonce

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Enable Load Balancer Cookies

When true, the agent writes load balancer cookies each time it invokes AM.

Use this property with Load Balancer Cookie Name to improve performance. Load balancer cookies can reduce the number of calls that different AM instances make to the Core Token Service (CTS).

Because the agent invokes AM to log out a user, it creates a load-balancer cookie on logout. To remove these cookies on logout, add them to the Reset Cookie List.

Property name

org.forgerock.agents.load.balancer.cookies.enabled

Aliases

org.forgerock.agents.load.balancer.cookies.enabled
  Introduced in Java Agent 5.8.0
  Recognized from AM 7.1

Function

Cookie

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global (from AM 7.1)

Title: Enable Load Balancer Cookies

Legacy title: Load Balancer Cookie Enabled

A list of cookies to reset before redirecting the client for login, and when the client logs out. Cookie Reset must be true.

The agent searches for the cookie name using a case-sensitive search. If it finds a match, the cookie is reset. Otherwise, the agent searches again using a case-insensitive search. If it then finds a match, the cookie is reset and a warning is issued to the logs.

The list does not need to include the names of cookies created when Profile Attribute Fetch Mode or Session Attribute Fetch Mode has the value HTTP_COOKIE.

Property name

org.forgerock.agents.cookie.reset.name.list

Aliases

org.forgerock.agents.cookie.reset.name.list
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.cookie.reset.name
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Cookie reset

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO

Title: Reset Cookie List

Legacy title: Cookies Reset Name List

Session Attribute Fetch Mode

Map the name of an AM session attribute specified in Session Attribute Map as follows:

  • NONE: Do not map

  • HTTP_HEADER: Map the to the name of an HTTP session header

  • HTTP_COOKIE: Map to the name of an HTTP cookie

  • REQUEST_ATTRIBUTE: Map to the name of an HTTP session attribute

When the value is HTTP_COOKIE, Cookie Reset is automatically set to true. Before redirecting the client for login, and when the client logs out, the agent resets profile and session attributes cookies, and cookies in the Reset Cookie List.

Property name

org.forgerock.agents.session.attribute.fetch.mode

Aliases

org.forgerock.agents.session.attribute.fetch.mode
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.session.attribute.fetch.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Attributes, Cookie reset, Session

Supported settings

NONE

No AM attributes are mapped.

HTTP_HEADER

The named AM attributes are mapped to headers in the outgoing HTTP response.

REQUEST_ATTRIBUTE

The named AM attributes are mapped to request attributes in the outgoing HTTP response.

HTTP_COOKIE

The named AM attributes are mapped to cookies in the outgoing HTTP response.

Default

NONE

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Session Attribute Fetch Mode

When true, the agent resets the cookies in the response before redirecting the client for login, and when the client logs out.

The agent resets the cookies listed in Reset Cookie List, and cookies that store profile or session attributes (when Profile Attribute Fetch Mode or Session Attribute Fetch Mode has the value HTTP_COOKIE).

To reset cookies that store response attributes (when Response Attribute Fetch Mode has the value HTTP_COOKIE), add them to the Reset Cookie List.

Property name

org.forgerock.agents.cookie.reset.enabled

Aliases

org.forgerock.agents.cookie.reset.enabled
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.cookie.reset.enable
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Cookie reset

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO

Title: Cookie Reset

Maps the cookie name specified in Reset Cookie List to a domain. After the cookie reset, the cookie is used in the domain.

Property name

org.forgerock.agents.cookie.reset.domain.map

Aliases

org.forgerock.agents.cookie.reset.domain.map
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.cookie.reset.domain
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Cookie reset

Type

Map

  • Keys: cookie name

  • Values: cookie domain

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO

Title: Reset Cookie Domain Map

Legacy title: Cookies Reset Domain Map

Maps cookie name specified in Reset Cookie List to a path. After cookie reset, the cookie is used in the path.

Property name

org.forgerock.agents.cookie.reset.path.map

Aliases

com.sun.identity.agents.config.cookie.reset.path
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.cookie.reset.path.map
  Introduced in Java Agent 5.6

Function

Cookie reset

Type

Map

  • Keys: cookie name

  • Values: cookie path

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO

Title: Reset Cookie Path Map

Legacy title: Cookies Reset Path Map

Profile Attribute Fetch Mode

Map the name of an AM profile attribute specified in Profile Attribute Map as follows:

  • NONE: Do not map

  • HTTP_HEADER: Map the to the name of an HTTP profile header

  • HTTP_COOKIE: Map to the name of an HTTP cookie

  • REQUEST_ATTRIBUTE: Map to the name of an HTTP profile attribute

Property name

org.forgerock.agents.profile.attribute.fetch.mode

Aliases

com.sun.identity.agents.config.profile.attribute.fetch.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.profile.attribute.fetch.mode
  Introduced in Java Agent 5.6

Function

Attributes, Cookie reset, Profile

Supported settings

NONE

No AM attributes are mapped.

HTTP_HEADER

The named AM attributes are mapped to headers in the outgoing HTTP response.

REQUEST_ATTRIBUTE

The named AM attributes are mapped to request attributes in the outgoing HTTP response.

HTTP_COOKIE

The named AM attributes are mapped to cookies in the outgoing HTTP response.

Default

NONE

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Profile Attribute Fetch Mode

Cross-domain single sign-on

Transmit Cookies Securely

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

Property name

org.forgerock.agents.secure.cookies.enabled

Aliases

com.sun.identity.agents.config.cdsso.secure.enable
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.secure.cookies.enabled
  Introduced in Java Agent 5.6

com.iplanet.am.cookie.secure
  Introduced in Java Agent 5.0

Function

Cross-domain single sign-on

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO

Title: Transmit Cookies Securely

Legacy title: CDSSO Secure Enable

Authentication Redirect URI

The URI the agent uses to process authentication requests.

When this property is not defined, the redirect URI is provided by AM.

When this property is defined and Location of Agent Configuration Repository is REMOTE, AM overwrites this property.

If OIDC authentication is being used, changing the value of this property while the agent is running prevents it from functioning. Restart the agent immediately after the value in AM is altered and the properties saved.

Property name

org.forgerock.agents.authn.redirect.uri

Aliases

org.forgerock.agents.authn.redirect.uri
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.cdsso.redirect.uri
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Cross-domain single sign-on, Required

Type

String

Bootstrap property

No

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentConfig.properties

AM console

Tab: SSO

Title: Authentication Redirect URI

Legacy title: CDSSO Redirect URI

Cross-site scripting

XSS Code Element List

Strings that, when found in the request, cause the agent to redirect the client to an error page.

Property name

org.forgerock.agents.xss.code.element.list

Aliases

org.forgerock.agents.xss.code.element.list
  Introduced in Java Agent 5.7

com.sun.identity.agents.config.xss.code.elements
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Cross-site scripting

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: XSS Code Element List

Legacy title: Possible XSS code elements

XSS Redirect URI Map

A map of web application name to URI. When a cross-site scripting attack is detected, the agent redirects to the URI specified in the map. The URI is expected to be a page (HTML, or otherwise) indicating that such an attack has been detected.

For example, to redirect clients of MyApp to /myapp/error.html, enter MyApp as the map key and /myapp/error.html as the map value.

Property name

org.forgerock.agents.xss.redirect.uri.map

Aliases

com.sun.identity.agents.config.xss.redirect.uri
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.xss.redirect.uri.map
  Introduced in Java Agent 5.7

Function

Cross-site scripting

Type

Map

  • Keys: web application

  • Values: cross site scripting URI

Default

/agentapp/XSSCodeDetected.html

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: XSS Redirect URI Map

Legacy title: XSS detection redirect URI

Custom login redirect

Enable SSO Token Acceptance

Set this property as follows:

  • true: Accept SSO tokens. Use this option when the agent and the token issuer are in the same domain, and for web applications and APIs where the backend accepts user information from SSO tokens.

  • false: Do not accept SSO tokens; require OIDC JWTs for authentication.

During session upgrade the format of the composite advice is as follows:

  • When both this property and Enable Custom Login Mode are true, the composite advice has the following format: ?authIndexType=composite_advice&authIndexValue=<Advices Value>

  • When either property is false, the composite advice has the following format: ?composite_advice=<Advices Value>

Property name

org.forgerock.agents.accept.sso.tokens.enabled

Aliases

org.forgerock.agents.accept.sso.tokens.enabled
  Introduced in Java Agent 5.7.1
  Recognized from AM 7.1

org.forgerock.agents.accept.sso.tokens
  Introduced in Java Agent 5.7.1

com.forgerock.agents.accept.sso.tokens
  Introduced in Java Agent 5.7.1

Function

Custom login redirect, Login redirect, SSO cookie handling

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7.1)

Title: Enable SSO Token Acceptance

Legacy title: Accept SSO Tokens

OAuth Login URL List

Use only when Enable Custom Login Mode is false and AM Login URL List is empty.

Specify rules to evaluate the incoming request URL, based on domain, path, request header, or query parameters. Specify a URL for login redirect with optional parameters.

Format, with no spaces between values:

[domain/path][header:value][?param=value[,param=value]]|[URL][?param=value&param=value]

When an unauthenticated request URL matches a rule specified by this property, the agent redirects the request to the specified URL for login.

When this property configures multiple rules, the agent sorts the rules into the following order and applies them in that order until it finds a match:

  1. Header specification - a rule with a header specification is applied before other rules

  2. Longest domain

  3. Longest path

  4. Highest number of parameter specifications

During redirect, the agent appends the goto parameter configured in Goto Parameter Name, and a nonce parameter, to the agent’s CDSSO endpoint. If Enable FQDN Checking is true, the agent iterates through the list of URLs until it finds a redirect URL that matches the FQDN check values. Otherwise, the agent redirects the user to the URL configured in the conditional redirect rules.

[domain/path]

The incoming request URL:

  • Domain: For example, example.com. The agent must match the domain 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.

  • Subdomain: For example, mydomain.example.com. The agent match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com. Subdomains can include path information, for example, mydomain.example.com/s6ecure, but cannot specify ports.

  • Path: For example, /myapp.

  • No value: Nothing is specified before the | character and the rule applies to every incoming request.

[header:value]

One header/value pair provided in the incoming request. If the header value is not provided, the header can take any value. For example:

Requests containing a header called X-local with the value provided are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|

Requests containing a header called X-local with any value are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[0]= X-local:|

[?param=value[,param=value]

One or more parameter and value pairs provided in the incoming request. If the parameter value is not provided, the parameter can take any value. For example:

Requests containing a parameter called site with the value shopping are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping|

Requests containing a parameter called target`with the value `cooking AND a parameter called price with the value low are redirected to the default URL:+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking,price=low|

[URL]

The login URL. The URL can be an AM instance, an AM site, or a website other than AM.

Specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example:

https://myweb.example.com/authApp/login.jsp

https://am.example.com:8443/openam/XUI/#login/

https://am.example.com:8443/openam/customlogin/login.jsp

If [URL] is not specified, the agent redirects the request to the AM instance or site specified by the following bootstrap properties:

org.forgerock.agents.am.protocol://org.forgerock.agents.am.hostname:org.forgerock.agents.am.port/org.forgerock.agents.am.path

[?param=value&param=value]

One or more parameters to add to the login URL. Chain multiple parameters with an ampersand (&), for example, realm=value&parameter1=value1&parameter2=value2.

When the parameter is ?realm=value it specifies the AM realm into which the agent logs the users. For example, ?realm=marketplace.

When redirecting to AM’s XUI, use an ampersand (&) instead of a question mark (?). For example, https://am.example.com:8443/openam/XUI/#login/&realm=marketplace.

A realm parameter is not required in the login URL when any of the following conditions are true:

  • The custom login page itself sets the realm parameter, for example, because it lets the user choose it. In this case, you must ensure the custom login page always returns a realm parameter to the agent.

  • The realm that the agent is logging the user into has DNS aliases configured in AM.

  • AM logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL logs in the marketplace realm if the realm alias is set to marketplace.example.com.

  • The users should always log in to the Top Level Realm.

Examples

+

Requests containing a header called X-local with the value provided are redirected to the specified URL in the beta realm:

+

org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|http://mysite.local.com:8081/login?realm=beta

+

Requests containing a header called X-local with any value are redirected to the default URL in the gamma realm:

+

org.forgerock.agents.oauth.login.url.list[1]= X-local:|?realm=gamma

+

Requests containing a parameter called site with the value shopping AND a parameter called mode with the value discount are redirected to the default URL in the discountshopping realm:

+

org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping,mode=discount|?realm=discountshopping

+

Requests containing a parameter called target with the value cooking are redirected to the AM XUI page in the kitchen realm. Note the use of & before the realm parameter:

+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking|https://am.example.com:8443/openam/XUI/#login/&realm=kitchen

+

Requests containing a parameter called target with the value cooking are redirected to a non-AM login page in the kitchen realm. Note the use of ? before the realm parameter:

+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking|https://mysite.example.com:8443/login/?realm=kitchen

Property name

org.forgerock.agents.oauth.login.url.list

Aliases

org.forgerock.agents.oauth.login.url.list
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.conditional.login.url
  Introduced in Java Agent 5.6
  Recognized from AM 6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: OAuth Login URL List

Legacy title: AM Conditional Login URL

Enable Custom Login Mode

Set the login redirection mode, as follows:

  • false: Use default login redirection mode.

    • The agent can redirect requests to any AM instance that supports the /oauth2/authorize endpoint. By default, this is the AM instance that is specified during installation.

    • The /oauth2/authorize endpoint returns an OIDC ID token. This is the only response the agent accepts.

    • Use with OAuth Login URL List to modify or redirect calls to the endpoint that provides the tokens.

  • true: Use custom login redirection mode.

    • The agent handles JWTs or SSO tokens as session tokens for authentication and authorization, and can can redirect login anywhere.

    • Use with AM Login URL List and Legacy Login URL List to modify or redirect calls.

During session upgrade, the format of the composite advice is as follows:

  • When both this property and Enable SSO Token Acceptance are true, the composite advice has the following format: ?authIndexType=composite_advice&authIndexValue=<Advices Value>

  • When either property is false, the composite advice has the following format: ?composite_advice=<Advices Value>

Property name

org.forgerock.agents.legacy.login.enabled

Aliases

org.forgerock.agents.legacy.login.enabled
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.allow.custom.login
  Introduced in Java Agent 5.6
  Recognized from AM 7

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Enable Custom Login Mode

Legacy title: Allow Custom Login Mode

AM Login URL List

The URL of the login page to use for authentication.

During the redirect, the agent appends the following parameters to the agent’s CDSSO endpoint:

Use the format URL[?realm=realm_name?parameter1=value1&…​], where:

  • URL: URL of the login page to use for authentication

  • [?realm=realm_name&parameter1=value1&…​]: Optional parameters that the agent passes to the login page, for example, the AM realm at which to authenticate.

You do not need to specify an authentication realm if any of the following conditions are true:

  • The custom login page sets the realm parameter, for example, because it lets the user choose the realm.

  • The user authenticates into a realm that has DNS aliases configured in AM. AM then logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from http://marketplace.example.com logs in the marketplace realm if the realm alias is set to marketplace.example.com.

  • The user authenticates to the top-level realm.

This parameter can be overwritten by the custom login page if, for example, the user chooses the authentication realm.

Specify as many parameters your custom login pages require.

Example:

https://login.example.com/login.jsp?realm=marketplace&param1=value1

In some versions of AM you can configure more than one value for this property, but only the first value is honored.

Property name

com.sun.identity.agents.config.login.url

Aliases

com.sun.identity.agents.config.login.url
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: AM Login URL List

Legacy title: AM Login URL

Login Reason Parameter Name

When Enable Custom Login Mode is true, this property specifies the name of a parameter included in calls to the custom login URL, to indicate why authentication is required. The parameter value can be used in a custom login page to provide additional feedback to the authenticating user.

If this property is specified, the agent includes a parameter named with the property value, and including one of the following values:

  • NO_TOKEN: No token present in the original request.

  • TOKEN_EXPIRED: Expiry time of the JWT was in the past.

  • EXCEPTION: An unknown exception occurred, either while parsing the JWT or at some other stage of authentication.

To reduce the risk of leaking useful information, use the property Login Reason Value Map to change the strings for the above values.

For example, specifying org.forgerock.agents.login.reason.parameter.name=auth_reason can cause the agent to redirect authentication to the following URL: https://custom.example.com:8443/…​./login_endpoint?…​&auth_reason=TOKEN_EXPIRED&…​

Do not enter a value that clashes with other parameters used for authentication; for example, realm or goto.

Property name

org.forgerock.agents.login.reason.parameter.name

Aliases

org.forgerock.agents.login.reason.parameter.name
  Introduced in Java Agent 5.7

Function

Custom login redirect, Login redirect

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Login Reason Parameter Name

Legacy Login URL List

Adds parameters conditionally to legacy login URLs.

Format, with no spaces between values:

domain/path|url?param1=value1&param2=value2

Domain/path

The incoming request URL:

  • Domain: For example, example.com. The agent must match the domain 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.

  • Subdomain: For example, mydomain.example.com. The agent match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com. Subdomains can include path information, for example, mydomain.example.com/s6ecure, but cannot specify ports.

  • Path: For example, /myapp.

  • No value: Nothing is specified before the | character and the rule applies to every incoming request.

URL

The URL to which redirect incoming login requests. The URL may be an AM instance, an AM site, or a website other than AM.

Specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example:

https://myweb.example.com/authApp/login.jsp

https://am.example.com:8443/openam/XUI/#login/

https://am.example.com:8443/openam/customlogin/login.jsp

If the URL is not specified, the agent redirects the request to the AM instance or site specified by the following bootstrap properties:

org.forgerock.agents.am.protocol://org.forgerock.agents.am.hostname:org.forgerock.agents.am.port/org.forgerock.agents.am.path

&parameter1=value1

Parameters that can be added to the URL. Add as many parameters as your custom login pages need. Chain parameters with an & character, for example, realm=value&parameter1=value1&parameter2=value2.

Examples

org.forgerock.agents.legacy.login.url.list[0]=example.com|https://am.example.com/openam/XUI/#login&realm=customers

org.forgerock.agents.legacy.login.url.list[1]=myapp.domain.com|https://login.example.com/apps/login.jsp?realm=sales

org.forgerock.agents.legacy.login.url.list[2]=sales.example.com/marketplace|?realm=marketplace

org.forgerock.agents.legacy.login.url.list[3]=|https://login.example.com/apps/login.jsp?realm=sales&isblue=true&carowner=true

org.forgerock.agents.legacy.login.url.list[4]=|?realm=sales

Property name

org.forgerock.agents.legacy.login.url.list

Aliases

org.forgerock.openam.agents.config.conditional.custom.login.url
  Introduced in Java Agent 5.6
  Recognized from AM 7

org.forgerock.agents.legacy.login.url.list
  Introduced in Java Agent 5.6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Legacy Login URL List

Legacy title: Custom Conditional Login URL

Default Login Redirect

OAuth Login URL List

Use only when Enable Custom Login Mode is false and AM Login URL List is empty.

Specify rules to evaluate the incoming request URL, based on domain, path, request header, or query parameters. Specify a URL for login redirect with optional parameters.

Format, with no spaces between values:

[domain/path][header:value][?param=value[,param=value]]|[URL][?param=value&param=value]

When an unauthenticated request URL matches a rule specified by this property, the agent redirects the request to the specified URL for login.

When this property configures multiple rules, the agent sorts the rules into the following order and applies them in that order until it finds a match:

  1. Header specification - a rule with a header specification is applied before other rules

  2. Longest domain

  3. Longest path

  4. Highest number of parameter specifications

During redirect, the agent appends the goto parameter configured in Goto Parameter Name, and a nonce parameter, to the agent’s CDSSO endpoint. If Enable FQDN Checking is true, the agent iterates through the list of URLs until it finds a redirect URL that matches the FQDN check values. Otherwise, the agent redirects the user to the URL configured in the conditional redirect rules.

[domain/path]

The incoming request URL:

  • Domain: For example, example.com. The agent must match the domain 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.

  • Subdomain: For example, mydomain.example.com. The agent match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com. Subdomains can include path information, for example, mydomain.example.com/s6ecure, but cannot specify ports.

  • Path: For example, /myapp.

  • No value: Nothing is specified before the | character and the rule applies to every incoming request.

[header:value]

One header/value pair provided in the incoming request. If the header value is not provided, the header can take any value. For example:

Requests containing a header called X-local with the value provided are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|

Requests containing a header called X-local with any value are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[0]= X-local:|

[?param=value[,param=value]

One or more parameter and value pairs provided in the incoming request. If the parameter value is not provided, the parameter can take any value. For example:

Requests containing a parameter called site with the value shopping are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping|

Requests containing a parameter called target`with the value `cooking AND a parameter called price with the value low are redirected to the default URL:+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking,price=low|

[URL]

The login URL. The URL can be an AM instance, an AM site, or a website other than AM.

Specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example:

https://myweb.example.com/authApp/login.jsp

https://am.example.com:8443/openam/XUI/#login/

https://am.example.com:8443/openam/customlogin/login.jsp

If [URL] is not specified, the agent redirects the request to the AM instance or site specified by the following bootstrap properties:

org.forgerock.agents.am.protocol://org.forgerock.agents.am.hostname:org.forgerock.agents.am.port/org.forgerock.agents.am.path

[?param=value&param=value]

One or more parameters to add to the login URL. Chain multiple parameters with an ampersand (&), for example, realm=value&parameter1=value1&parameter2=value2.

When the parameter is ?realm=value it specifies the AM realm into which the agent logs the users. For example, ?realm=marketplace.

When redirecting to AM’s XUI, use an ampersand (&) instead of a question mark (?). For example, https://am.example.com:8443/openam/XUI/#login/&realm=marketplace.

A realm parameter is not required in the login URL when any of the following conditions are true:

  • The custom login page itself sets the realm parameter, for example, because it lets the user choose it. In this case, you must ensure the custom login page always returns a realm parameter to the agent.

  • The realm that the agent is logging the user into has DNS aliases configured in AM.

  • AM logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL logs in the marketplace realm if the realm alias is set to marketplace.example.com.

  • The users should always log in to the Top Level Realm.

Examples

+

Requests containing a header called X-local with the value provided are redirected to the specified URL in the beta realm:

+

org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|http://mysite.local.com:8081/login?realm=beta

+

Requests containing a header called X-local with any value are redirected to the default URL in the gamma realm:

+

org.forgerock.agents.oauth.login.url.list[1]= X-local:|?realm=gamma

+

Requests containing a parameter called site with the value shopping AND a parameter called mode with the value discount are redirected to the default URL in the discountshopping realm:

+

org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping,mode=discount|?realm=discountshopping

+

Requests containing a parameter called target with the value cooking are redirected to the AM XUI page in the kitchen realm. Note the use of & before the realm parameter:

+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking|https://am.example.com:8443/openam/XUI/#login/&realm=kitchen

+

Requests containing a parameter called target with the value cooking are redirected to a non-AM login page in the kitchen realm. Note the use of ? before the realm parameter:

+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking|https://mysite.example.com:8443/login/?realm=kitchen

Property name

org.forgerock.agents.oauth.login.url.list

Aliases

org.forgerock.agents.oauth.login.url.list
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.conditional.login.url
  Introduced in Java Agent 5.6
  Recognized from AM 6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: OAuth Login URL List

Legacy title: AM Conditional Login URL

Enable Custom Login Mode

Set the login redirection mode, as follows:

  • false: Use default login redirection mode.

    • The agent can redirect requests to any AM instance that supports the /oauth2/authorize endpoint. By default, this is the AM instance that is specified during installation.

    • The /oauth2/authorize endpoint returns an OIDC ID token. This is the only response the agent accepts.

    • Use with OAuth Login URL List to modify or redirect calls to the endpoint that provides the tokens.

  • true: Use custom login redirection mode.

    • The agent handles JWTs or SSO tokens as session tokens for authentication and authorization, and can can redirect login anywhere.

    • Use with AM Login URL List and Legacy Login URL List to modify or redirect calls.

During session upgrade, the format of the composite advice is as follows:

  • When both this property and Enable SSO Token Acceptance are true, the composite advice has the following format: ?authIndexType=composite_advice&authIndexValue=<Advices Value>

  • When either property is false, the composite advice has the following format: ?composite_advice=<Advices Value>

Property name

org.forgerock.agents.legacy.login.enabled

Aliases

org.forgerock.agents.legacy.login.enabled
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.allow.custom.login
  Introduced in Java Agent 5.6
  Recognized from AM 7

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Enable Custom Login Mode

Legacy title: Allow Custom Login Mode

AM Login URL List

The URL of the login page to use for authentication.

During the redirect, the agent appends the following parameters to the agent’s CDSSO endpoint:

Use the format URL[?realm=realm_name?parameter1=value1&…​], where:

  • URL: URL of the login page to use for authentication

  • [?realm=realm_name&parameter1=value1&…​]: Optional parameters that the agent passes to the login page, for example, the AM realm at which to authenticate.

You do not need to specify an authentication realm if any of the following conditions are true:

  • The custom login page sets the realm parameter, for example, because it lets the user choose the realm.

  • The user authenticates into a realm that has DNS aliases configured in AM. AM then logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from http://marketplace.example.com logs in the marketplace realm if the realm alias is set to marketplace.example.com.

  • The user authenticates to the top-level realm.

This parameter can be overwritten by the custom login page if, for example, the user chooses the authentication realm.

Specify as many parameters your custom login pages require.

Example:

https://login.example.com/login.jsp?realm=marketplace&param1=value1

In some versions of AM you can configure more than one value for this property, but only the first value is honored.

Property name

com.sun.identity.agents.config.login.url

Aliases

com.sun.identity.agents.config.login.url
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: AM Login URL List

Legacy title: AM Login URL

Legacy Login URL List

Adds parameters conditionally to legacy login URLs.

Format, with no spaces between values:

domain/path|url?param1=value1&param2=value2

Domain/path

The incoming request URL:

  • Domain: For example, example.com. The agent must match the domain 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.

  • Subdomain: For example, mydomain.example.com. The agent match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com. Subdomains can include path information, for example, mydomain.example.com/s6ecure, but cannot specify ports.

  • Path: For example, /myapp.

  • No value: Nothing is specified before the | character and the rule applies to every incoming request.

URL

The URL to which redirect incoming login requests. The URL may be an AM instance, an AM site, or a website other than AM.

Specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example:

https://myweb.example.com/authApp/login.jsp

https://am.example.com:8443/openam/XUI/#login/

https://am.example.com:8443/openam/customlogin/login.jsp

If the URL is not specified, the agent redirects the request to the AM instance or site specified by the following bootstrap properties:

org.forgerock.agents.am.protocol://org.forgerock.agents.am.hostname:org.forgerock.agents.am.port/org.forgerock.agents.am.path

&parameter1=value1

Parameters that can be added to the URL. Add as many parameters as your custom login pages need. Chain parameters with an & character, for example, realm=value&parameter1=value1&parameter2=value2.

Examples

org.forgerock.agents.legacy.login.url.list[0]=example.com|https://am.example.com/openam/XUI/#login&realm=customers

org.forgerock.agents.legacy.login.url.list[1]=myapp.domain.com|https://login.example.com/apps/login.jsp?realm=sales

org.forgerock.agents.legacy.login.url.list[2]=sales.example.com/marketplace|?realm=marketplace

org.forgerock.agents.legacy.login.url.list[3]=|https://login.example.com/apps/login.jsp?realm=sales&isblue=true&carowner=true

org.forgerock.agents.legacy.login.url.list[4]=|?realm=sales

Property name

org.forgerock.agents.legacy.login.url.list

Aliases

org.forgerock.openam.agents.config.conditional.custom.login.url
  Introduced in Java Agent 5.6
  Recognized from AM 7

org.forgerock.agents.legacy.login.url.list
  Introduced in Java Agent 5.6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Legacy Login URL List

Legacy title: Custom Conditional Login URL

Deprecated

Login Attempt Limit (deprecated)

When the value of this property is greater than zero, it defines the maximum number of failed login attempts allowed during a browser session. After this number, the agent blocks requests from the user.

Specify a value greater than zero. For example, if the property is set to 3, the agent blocks the fourth login request.

Use this property to mitigate the risk of brute force attacks.

Property name

org.forgerock.agents.login.attempt.limit.count

Aliases

org.forgerock.agents.login.attempt.limit.count
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.login.attempt.limit
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Deprecated

Type

Integer

Default

0

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: Login Attempt Limit (deprecated)

The name of the cookie used to record the number of login attempts.

Property name

org.forgerock.agents.login.counter.cookie.name

Aliases

com.sun.identity.agents.config.login.counter.name
  Introduced in Java Agent 5.0
  Recognized from AM 7

org.forgerock.agents.login.counter.cookie.name
  Introduced in Java Agent 5.6

Function

Deprecated

Type

String

Default

amFilterParam

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global (from AM 7)

Title: Login Attempt Limit Cookie Name (deprecated)

Audit Log Filename (deprecated)

This property is deprecated; the log filename is fixed and can’t be specified. If this property is specified and Audit Log Directory is empty, the directory name is extracted from this property and used in Audit Log Directory.

Default: None; local auditing is disabled

Property name

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

Aliases

com.sun.identity.agents.config.local.logfile
  Introduced in Java Agent 5.0
  Recognized from AM 7

org.forgerock.agents.local.audit.file.path
  Introduced in Java Agent 5.6

Function

Deprecated

Type

String

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Encryption

Encryption Class

The name of the class used by the agent to implement encryption and decryption. The class must implement both com.iplanet.services.util.AMEncryption and com.iplanet.services.util.ConfigurableKey.

After changing this property, you must re-encrypt the agent profile password. For more information, refer to Encrypted Agent Password.

Property name

org.forgerock.agents.encryptor.classname

Aliases

org.forgerock.agents.encryptor.classname
  Introduced in Java Agent 5.0

com.iplanet.security.encryptor
  Introduced in Java Agent 5.0

Function

Encryption, Required

Type

Classname

Default

org.forgerock.openam.shared.security.crypto.AESWrapEncryption

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

No

Local configuration file

AgentBootstrap.properties

Encryption Key/Salt

The key/salt used by the default encryption class to perform encryption and decryption within the agent.

Generate a secure, random key with agentadmin --key or agentadmin --rotate commands as described in Rotate the agent profile password.

If this property is not set, the agent terminates with a configuration error.

If you are changing this property manually or with agentadmin --key, you must re-encrypt the agent profile password. For more information, refer to Encrypted Agent Password.

Property name

org.forgerock.agents.encryption.key

Aliases

org.forgerock.agents.encryption.key
  Introduced in Java Agent 5.10.1
  Recognized from AM 7.1

am.encryption.pwd
  Introduced in Java Agent 5.0

com.sun.identity.client.encryptionKey
  Introduced in Java Agent 5.0

Function

Authentication service, Encryption

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Fragment

Fragment Relay URI

A URI to act as a dummy endpoint within the agent for capturing URL fragments in unauthenticated requests:

  • When empty, unauthenticated requests to a URL with a fragment are authenticated and then redirected to the URL without the fragment.

  • When set, unauthenticated requests are authenticated and then redirected to the requested URL. An extra redirect is incurred for all unauthenticated requests, to capture and process the URL fragment.

Use a dummy URI within the agent web application, such as /agentapp/pre-authn-fragment-capture. Avoid dummy URIs used for other purposes.

Property name

org.forgerock.agents.authn.fragment.relay.uri

Aliases

org.forgerock.agents.authn.fragment.relay.uri
  Introduced in Java Agent 5.7
  Recognized from AM 7

Function

Fragment

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced (from AM 7)

Title: Fragment Relay URI

Fully qualified domain name

Default FQDN

The default FQDN to use when the agent cannot find a match in the FQDN Map. If this property is not defined, Enable FQDN Checking is set to false.

Use this property to map requests with virtual, invalid, or partial hostnames to URLs that contain a correct FQDN.

Property name

org.forgerock.agents.fqdn.default

Aliases

org.forgerock.agents.fqdn.default
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.fqdn.default
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Fully qualified domain name

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: Default FQDN

Legacy title: FQDN Default

FQDN Map

Key:Value maps of incoming hostname to outgoing domain. Use this property to map requests with virtual, invalid, or partial hostnames to a correct FQDN.

This property requires Enable FQDN Checking to be true, and Default FQDN to be set to suitable default FQDN.

The agent maintains the following maps, which can each contain multiple entries:

  • Map 1, where the key is the incoming hostname without wildcards, and the value is the outgoing domain.

  • Map 2, where the key is the incoming hostname with wildcards (* or ?), and the value is the outgoing domain.

Map keys are case insensitive. Incoming hostnames are converted to lowercase before the agent maps them, and the agent automatically converts uppercase keys and values to lowercase before mapping.

The agent maps FQDNs as follows:

  1. Searches map 1 for the incoming hostname. If there is a match, the agent redirects the request to the mapped value.

  2. Searches map 2 for a pattern that matches the incoming hostname, iterating through the entries in random order. If there is a match, the agent redirects the request to the mapped value.

  3. Redirects the request to the hostname in Default FQDN.

Examples:

org.forgerock.agents.fqdn.map[agent]=agent.localtest.me

org.forgerock.agents.fqdn.map[agent.virtualtest.me]=virtual-host.localtest.me

org.forgerock.agents.fqdn.map[agent-*.localtest.me]=agent.localtest.me

Property name

org.forgerock.agents.fqdn.map

Aliases

com.sun.identity.agents.config.fqdn.mapping
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.fqdn.map
  Introduced in Java Agent 5.6

Function

Fully qualified domain name

Type

Map

  • Keys: canonical name of invalid server

  • Values: canonical name of valid server

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: FQDN Map

Legacy title: FQDN Virtual Host Map

Enable FQDN Checking

When true, the agent compares the hostname of each request to the mappings in FQDN Map.

  • If it finds a match, it transforms the request URL to the mapped URL.

  • If it doesn’t find a match, it transforms the request URL to the value in Default FQDN.

If Default FQDN is not set, this property is automatically set to false.

Property name

org.forgerock.agents.fqdn.check.enabled

Aliases

com.sun.identity.agents.config.fqdn.check.enable
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.fqdn.check.enabled
  Introduced in Java Agent 5.6

Function

Fully qualified domain name

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: Enable FQDN Checking

Legacy title: FQDN Check

Global

Enable Prometheus Monitoring

When true, the agent will produce Prometheus monitoring output. When false, the agent will not produce any output.

Property name

org.forgerock.agents.prometheus.monitoring.enabled

Aliases

org.forgerock.agents.prometheus.monitoring.enabled
  Introduced in Java Agent 5.6

Function

Global

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

Yes

Required property

No

Restart required

No

Local configuration file

AgentBootstrap.properties

AM console

Tab: Monitoring

Title: Enable Prometheus Monitoring

HTTP 302 Redirect Data

When Enable HTTP 302 Redirects, this property specifies the data to return instead of an HTTP 302 Redirect.

Property name

org.forgerock.agents.302.redirect.http.data

Aliases

org.forgerock.agents.302.redirect.http.data
  Introduced in Java Agent 5.8.0
  Recognized from AM 7.1

Function

Global

Type

String

Default

{ "redirect": { "requestUri": "%REQUEST_URI%", "requestUrl": "%REQUEST_URL%", "targetUrl": "%TARGET%" } }

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7.1)

Title: HTTP 302 Redirect Data

HTTP 302 Redirect Not-Enforced List

When Enable HTTP 302 Redirects, this property specifies a list of URLs for which HTTP 302 Redirect does not take place.

If a request matches an entry in the list, HTTP 302 Redirect does not take place for that request, and the agent returns a block of configurable JSON.

Property name

org.forgerock.agents.config.json.url

Aliases

org.forgerock.agents.config.json.url
  Introduced in Java Agent 5.8.0

org.forgerock.agents.302.redirect.ner.list
  Introduced in Java Agent 5.8.0
  Recognized from AM 7.1

Function

Global

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7.1)

Title: HTTP 302 Redirect Not-Enforced List

Legacy title: HTTP 302 Redirect Not Enforced List

HTTP 302 Redirect Replacement HTTP Status Code

When Enable HTTP 302 Redirects is false, this property specifies the HTTP code to return instead of an HTTP 302 (Redirect).

Property name

org.forgerock.agents.302.redirect.http.status.code

Aliases

org.forgerock.agents.302.redirect.http.status.code
  Introduced in Java Agent 5.8.0
  Recognized from AM 7.1

org.forgerock.agents.config.json.response.code
  Introduced in Java Agent 5.8.0

Function

Global

Type

Integer

Default

200

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7.1)

Title: HTTP 302 Redirect Replacement HTTP Status Code

Legacy title: HTTP 302 Redirect Replacement HTTP Code

Goto Parameter Name

Renames the goto parameter. During redirection, the agent appends the requested URL to the named parameter.

Use this property when your web application requires a parameter other than goto.

In the following example, the parameter is renamed to goto2:

com.sun.identity.agents.config.redirect.param=goto2

The redirection URL becomes like this:

https://www.example.com:8443/accessDenied.html?goto2=http%3A%2F%www.example.com%3A8020%managers%2Findex.jsp

The URL appended to the goto2 parameter is the URL that the user tried to access when the agent redirected the request to the accessDenied.html page, configured with Access Denied URI Map.

Property name

com.sun.identity.agents.config.redirect.param

Aliases

com.sun.identity.agents.config.redirect.param
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Global

Type

String

Default

goto

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous

Title: Goto Parameter Name

HTTP 302 Redirect Content Type

When Enable HTTP 302 Redirects, this property specifies the content type of the data to return instead of an HTTP 302 Redirect.

Property name

org.forgerock.agents.302.redirect.http.content.type

Aliases

org.forgerock.agents.302.redirect.http.content.type
  Introduced in Java Agent 5.8.0
  Recognized from AM 7.1

Function

Global

Type

String

Default

application/json

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7.1)

Title: HTTP 302 Redirect Content Type

HTTP 302 Redirect Invert Not-Enforced List

When Enable HTTP 302 Redirects is false, and this property is true, the agent inverts the meaning of HTTP 302 Redirect Not-Enforced List, so that it specifies a list of URLs for which HTTP 302 Redirect does take place.

Property name

org.forgerock.agents.config.json.url.invert

Aliases

org.forgerock.agents.config.json.url.invert
  Introduced in Java Agent 5.8.0

org.forgerock.agents.302.redirect.invert.enabled
  Introduced in Java Agent 5.8.0
  Recognized from AM 7.1

Function

Global

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7.1)

Title: HTTP 302 Redirect Invert Not-Enforced List

Enable HTTP 302 Redirects

Controls how the agent handles redirects, as follows:

  • true: HTTP 302 Redirects are enabled. When an unauthenticated request is made, and not-enforced rules do not apply, the agent returns an HTTP 302 code to redirect the user to an authentication endpoint.

  • false: HTTP 302 Redirects are disabled. When an unauthenticated request is made, the agent returns a block of configurable JSON that can be intercepted.

The returned HTTP code, content type, and data is configured by the following properties

Lists of URLs in a not-enforced rule style, for which the data is produced are configured by the following properties

Use this option when it is difficult to handle 302, for example, when the agent is accessed by a JavaScript application, or by something other than a browser.

Property name

org.forgerock.agents.302.redirects.enabled

Aliases

org.forgerock.agents.302.redirects.enabled
  Introduced in Java Agent 5.8.0
  Recognized from AM 7.1

Function

Global

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7.1)

Title: Enable HTTP 302 Redirects

Legacy title: HTTP 302 Redirects Enabled

Locale

Locale Country

The agent country. Changing this has no effect.

Property name

org.forgerock.agents.locale.country

Aliases

org.forgerock.agents.locale.country
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.locale.country
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Locale

Type

String

Default

US

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous

Title: Locale Country

Locale Language

The agent language. Changing this has no effect.

Property name

org.forgerock.agents.locale.language

Aliases

org.forgerock.agents.locale.language
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.locale.language
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Locale

Type

String

Default

en

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous

Title: Locale Language

Login

Enable Redirect to AM Success URL

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

When false, the agent redirects to the requested URL, if any.

Property name

org.forgerock.agents.authn.success.redirect.session.url.enabled

Aliases

org.forgerock.agents.authn.success.redirect.session.url.enabled
  Introduced in Java Agent 5.6.3.0
  Recognized from AM 7

Function

Login

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Enable Redirect to AM Success URL

Legacy title: Redirect to AM’s Success URL

A cooke name that will be used by the authentication exchange endpoint. The value is empty by default, and the endpoint is not able to examine cookie values.

Property name

org.forgerock.agents.authn.exchange.cookie.name

Aliases

org.forgerock.agents.authn.exchange.cookie.name
  Introduced in Java Agent 5.7

Function

Login

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7)

Title: Authentication Exchange Cookie Name

Login Reason Value Map

When Login Reason Parameter Name is set, this property specifies alternative strings to use for the supported values. For example:

Consider the example where Login Reason Parameter Name is set to auth_reason, and this property is set as follows:

org.forgerock.agents.login.reason.map[NO_TOKEN]=notoken

org.forgerock.agents.login.reason.map[TOKEN_EXPIRED]=expired

org.forgerock.agents.login.reason.map[EXCEPTION]=exception

The agent redirects authentication to the following URL:

https://custom.example.com:8443/…​./login_endpoint?…​&auth_reason=notoken&…​

Property name

org.forgerock.agents.login.reason.remapper

Aliases

org.forgerock.agents.login.reason.remapper
  Introduced in Java Agent 5.7

org.forgerock.agents.login.reason.map
  Introduced in Java Agent 5.7
  Recognized from AM 7

Function

Login

Type

Map

  • Keys: failed login reason code

  • Values: masked value

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Login Reason Value Map

Redirect Attempt Limit

When the value of this property is greater than zero, it defines the maximum number of redirects allowed for a browser session. After this number, the agent blocks the request.

Specify a value greater than zero. For example, if the property is set to 3, then the agent blocks the request on the fourth redirect.

Use this property to mitigate the risk of infinite redirection loops.

Property name

org.forgerock.agents.redirect.attempt.limit

Aliases

org.forgerock.agents.redirect.attempt.limit
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.redirect.attempt.limit
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Login

Type

Integer

Default

0

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: Redirect Attempt Limit

Authentication Exchange URI

This property allows the administrator to enable an endpoint to facilitate the exchange of SSO tokens for OIDC JWTs. The value is empty by default and thus the endpoint is not accessible.

Property name

org.forgerock.agents.authn.exchange.uri

Aliases

org.forgerock.agents.authn.exchange.uri
  Introduced in Java Agent 5.7
  Recognized from AM 7

Function

Login

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7)

Title: Authentication Exchange URI

Login Redirect (Default)

OAuth Login URL List

Use only when Enable Custom Login Mode is false and AM Login URL List is empty.

Specify rules to evaluate the incoming request URL, based on domain, path, request header, or query parameters. Specify a URL for login redirect with optional parameters.

Format, with no spaces between values:

[domain/path][header:value][?param=value[,param=value]]|[URL][?param=value&param=value]

When an unauthenticated request URL matches a rule specified by this property, the agent redirects the request to the specified URL for login.

When this property configures multiple rules, the agent sorts the rules into the following order and applies them in that order until it finds a match:

  1. Header specification - a rule with a header specification is applied before other rules

  2. Longest domain

  3. Longest path

  4. Highest number of parameter specifications

During redirect, the agent appends the goto parameter configured in Goto Parameter Name, and a nonce parameter, to the agent’s CDSSO endpoint. If Enable FQDN Checking is true, the agent iterates through the list of URLs until it finds a redirect URL that matches the FQDN check values. Otherwise, the agent redirects the user to the URL configured in the conditional redirect rules.

[domain/path]

The incoming request URL:

  • Domain: For example, example.com. The agent must match the domain 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.

  • Subdomain: For example, mydomain.example.com. The agent match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com. Subdomains can include path information, for example, mydomain.example.com/s6ecure, but cannot specify ports.

  • Path: For example, /myapp.

  • No value: Nothing is specified before the | character and the rule applies to every incoming request.

[header:value]

One header/value pair provided in the incoming request. If the header value is not provided, the header can take any value. For example:

Requests containing a header called X-local with the value provided are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|

Requests containing a header called X-local with any value are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[0]= X-local:|

[?param=value[,param=value]

One or more parameter and value pairs provided in the incoming request. If the parameter value is not provided, the parameter can take any value. For example:

Requests containing a parameter called site with the value shopping are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping|

Requests containing a parameter called target`with the value `cooking AND a parameter called price with the value low are redirected to the default URL:+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking,price=low|

[URL]

The login URL. The URL can be an AM instance, an AM site, or a website other than AM.

Specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example:

https://myweb.example.com/authApp/login.jsp

https://am.example.com:8443/openam/XUI/#login/

https://am.example.com:8443/openam/customlogin/login.jsp

If [URL] is not specified, the agent redirects the request to the AM instance or site specified by the following bootstrap properties:

org.forgerock.agents.am.protocol://org.forgerock.agents.am.hostname:org.forgerock.agents.am.port/org.forgerock.agents.am.path

[?param=value&param=value]

One or more parameters to add to the login URL. Chain multiple parameters with an ampersand (&), for example, realm=value&parameter1=value1&parameter2=value2.

When the parameter is ?realm=value it specifies the AM realm into which the agent logs the users. For example, ?realm=marketplace.

When redirecting to AM’s XUI, use an ampersand (&) instead of a question mark (?). For example, https://am.example.com:8443/openam/XUI/#login/&realm=marketplace.

A realm parameter is not required in the login URL when any of the following conditions are true:

  • The custom login page itself sets the realm parameter, for example, because it lets the user choose it. In this case, you must ensure the custom login page always returns a realm parameter to the agent.

  • The realm that the agent is logging the user into has DNS aliases configured in AM.

  • AM logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL logs in the marketplace realm if the realm alias is set to marketplace.example.com.

  • The users should always log in to the Top Level Realm.

Examples

+

Requests containing a header called X-local with the value provided are redirected to the specified URL in the beta realm:

+

org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|http://mysite.local.com:8081/login?realm=beta

+

Requests containing a header called X-local with any value are redirected to the default URL in the gamma realm:

+

org.forgerock.agents.oauth.login.url.list[1]= X-local:|?realm=gamma

+

Requests containing a parameter called site with the value shopping AND a parameter called mode with the value discount are redirected to the default URL in the discountshopping realm:

+

org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping,mode=discount|?realm=discountshopping

+

Requests containing a parameter called target with the value cooking are redirected to the AM XUI page in the kitchen realm. Note the use of & before the realm parameter:

+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking|https://am.example.com:8443/openam/XUI/#login/&realm=kitchen

+

Requests containing a parameter called target with the value cooking are redirected to a non-AM login page in the kitchen realm. Note the use of ? before the realm parameter:

+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking|https://mysite.example.com:8443/login/?realm=kitchen

Property name

org.forgerock.agents.oauth.login.url.list

Aliases

org.forgerock.agents.oauth.login.url.list
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.conditional.login.url
  Introduced in Java Agent 5.6
  Recognized from AM 6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: OAuth Login URL List

Legacy title: AM Conditional Login URL

Enable Custom Login Mode

Set the login redirection mode, as follows:

  • false: Use default login redirection mode.

    • The agent can redirect requests to any AM instance that supports the /oauth2/authorize endpoint. By default, this is the AM instance that is specified during installation.

    • The /oauth2/authorize endpoint returns an OIDC ID token. This is the only response the agent accepts.

    • Use with OAuth Login URL List to modify or redirect calls to the endpoint that provides the tokens.

  • true: Use custom login redirection mode.

    • The agent handles JWTs or SSO tokens as session tokens for authentication and authorization, and can can redirect login anywhere.

    • Use with AM Login URL List and Legacy Login URL List to modify or redirect calls.

During session upgrade, the format of the composite advice is as follows:

  • When both this property and Enable SSO Token Acceptance are true, the composite advice has the following format: ?authIndexType=composite_advice&authIndexValue=<Advices Value>

  • When either property is false, the composite advice has the following format: ?composite_advice=<Advices Value>

Property name

org.forgerock.agents.legacy.login.enabled

Aliases

org.forgerock.agents.legacy.login.enabled
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.allow.custom.login
  Introduced in Java Agent 5.6
  Recognized from AM 7

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Enable Custom Login Mode

Legacy title: Allow Custom Login Mode

AM Login URL List

The URL of the login page to use for authentication.

During the redirect, the agent appends the following parameters to the agent’s CDSSO endpoint:

Use the format URL[?realm=realm_name?parameter1=value1&…​], where:

  • URL: URL of the login page to use for authentication

  • [?realm=realm_name&parameter1=value1&…​]: Optional parameters that the agent passes to the login page, for example, the AM realm at which to authenticate.

You do not need to specify an authentication realm if any of the following conditions are true:

  • The custom login page sets the realm parameter, for example, because it lets the user choose the realm.

  • The user authenticates into a realm that has DNS aliases configured in AM. AM then logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from http://marketplace.example.com logs in the marketplace realm if the realm alias is set to marketplace.example.com.

  • The user authenticates to the top-level realm.

This parameter can be overwritten by the custom login page if, for example, the user chooses the authentication realm.

Specify as many parameters your custom login pages require.

Example:

https://login.example.com/login.jsp?realm=marketplace&param1=value1

In some versions of AM you can configure more than one value for this property, but only the first value is honored.

Property name

com.sun.identity.agents.config.login.url

Aliases

com.sun.identity.agents.config.login.url
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: AM Login URL List

Legacy title: AM Login URL

Legacy Login URL List

Adds parameters conditionally to legacy login URLs.

Format, with no spaces between values:

domain/path|url?param1=value1&param2=value2

Domain/path

The incoming request URL:

  • Domain: For example, example.com. The agent must match the domain 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.

  • Subdomain: For example, mydomain.example.com. The agent match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com. Subdomains can include path information, for example, mydomain.example.com/s6ecure, but cannot specify ports.

  • Path: For example, /myapp.

  • No value: Nothing is specified before the | character and the rule applies to every incoming request.

URL

The URL to which redirect incoming login requests. The URL may be an AM instance, an AM site, or a website other than AM.

Specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example:

https://myweb.example.com/authApp/login.jsp

https://am.example.com:8443/openam/XUI/#login/

https://am.example.com:8443/openam/customlogin/login.jsp

If the URL is not specified, the agent redirects the request to the AM instance or site specified by the following bootstrap properties:

org.forgerock.agents.am.protocol://org.forgerock.agents.am.hostname:org.forgerock.agents.am.port/org.forgerock.agents.am.path

&parameter1=value1

Parameters that can be added to the URL. Add as many parameters as your custom login pages need. Chain parameters with an & character, for example, realm=value&parameter1=value1&parameter2=value2.

Examples

org.forgerock.agents.legacy.login.url.list[0]=example.com|https://am.example.com/openam/XUI/#login&realm=customers

org.forgerock.agents.legacy.login.url.list[1]=myapp.domain.com|https://login.example.com/apps/login.jsp?realm=sales

org.forgerock.agents.legacy.login.url.list[2]=sales.example.com/marketplace|?realm=marketplace

org.forgerock.agents.legacy.login.url.list[3]=|https://login.example.com/apps/login.jsp?realm=sales&isblue=true&carowner=true

org.forgerock.agents.legacy.login.url.list[4]=|?realm=sales

Property name

org.forgerock.agents.legacy.login.url.list

Aliases

org.forgerock.openam.agents.config.conditional.custom.login.url
  Introduced in Java Agent 5.6
  Recognized from AM 7

org.forgerock.agents.legacy.login.url.list
  Introduced in Java Agent 5.6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Legacy Login URL List

Legacy title: Custom Conditional Login URL

Login redirect

Enable SSO Token Acceptance

Set this property as follows:

  • true: Accept SSO tokens. Use this option when the agent and the token issuer are in the same domain, and for web applications and APIs where the backend accepts user information from SSO tokens.

  • false: Do not accept SSO tokens; require OIDC JWTs for authentication.

During session upgrade the format of the composite advice is as follows:

  • When both this property and Enable Custom Login Mode are true, the composite advice has the following format: ?authIndexType=composite_advice&authIndexValue=<Advices Value>

  • When either property is false, the composite advice has the following format: ?composite_advice=<Advices Value>

Property name

org.forgerock.agents.accept.sso.tokens.enabled

Aliases

org.forgerock.agents.accept.sso.tokens.enabled
  Introduced in Java Agent 5.7.1
  Recognized from AM 7.1

org.forgerock.agents.accept.sso.tokens
  Introduced in Java Agent 5.7.1

com.forgerock.agents.accept.sso.tokens
  Introduced in Java Agent 5.7.1

Function

Custom login redirect, Login redirect, SSO cookie handling

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7.1)

Title: Enable SSO Token Acceptance

Legacy title: Accept SSO Tokens

OAuth Login URL List

Use only when Enable Custom Login Mode is false and AM Login URL List is empty.

Specify rules to evaluate the incoming request URL, based on domain, path, request header, or query parameters. Specify a URL for login redirect with optional parameters.

Format, with no spaces between values:

[domain/path][header:value][?param=value[,param=value]]|[URL][?param=value&param=value]

When an unauthenticated request URL matches a rule specified by this property, the agent redirects the request to the specified URL for login.

When this property configures multiple rules, the agent sorts the rules into the following order and applies them in that order until it finds a match:

  1. Header specification - a rule with a header specification is applied before other rules

  2. Longest domain

  3. Longest path

  4. Highest number of parameter specifications

During redirect, the agent appends the goto parameter configured in Goto Parameter Name, and a nonce parameter, to the agent’s CDSSO endpoint. If Enable FQDN Checking is true, the agent iterates through the list of URLs until it finds a redirect URL that matches the FQDN check values. Otherwise, the agent redirects the user to the URL configured in the conditional redirect rules.

[domain/path]

The incoming request URL:

  • Domain: For example, example.com. The agent must match the domain 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.

  • Subdomain: For example, mydomain.example.com. The agent match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com. Subdomains can include path information, for example, mydomain.example.com/s6ecure, but cannot specify ports.

  • Path: For example, /myapp.

  • No value: Nothing is specified before the | character and the rule applies to every incoming request.

[header:value]

One header/value pair provided in the incoming request. If the header value is not provided, the header can take any value. For example:

Requests containing a header called X-local with the value provided are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|

Requests containing a header called X-local with any value are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[0]= X-local:|

[?param=value[,param=value]

One or more parameter and value pairs provided in the incoming request. If the parameter value is not provided, the parameter can take any value. For example:

Requests containing a parameter called site with the value shopping are redirected to the default URL:

org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping|

Requests containing a parameter called target`with the value `cooking AND a parameter called price with the value low are redirected to the default URL:+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking,price=low|

[URL]

The login URL. The URL can be an AM instance, an AM site, or a website other than AM.

Specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example:

https://myweb.example.com/authApp/login.jsp

https://am.example.com:8443/openam/XUI/#login/

https://am.example.com:8443/openam/customlogin/login.jsp

If [URL] is not specified, the agent redirects the request to the AM instance or site specified by the following bootstrap properties:

org.forgerock.agents.am.protocol://org.forgerock.agents.am.hostname:org.forgerock.agents.am.port/org.forgerock.agents.am.path

[?param=value&param=value]

One or more parameters to add to the login URL. Chain multiple parameters with an ampersand (&), for example, realm=value&parameter1=value1&parameter2=value2.

When the parameter is ?realm=value it specifies the AM realm into which the agent logs the users. For example, ?realm=marketplace.

When redirecting to AM’s XUI, use an ampersand (&) instead of a question mark (?). For example, https://am.example.com:8443/openam/XUI/#login/&realm=marketplace.

A realm parameter is not required in the login URL when any of the following conditions are true:

  • The custom login page itself sets the realm parameter, for example, because it lets the user choose it. In this case, you must ensure the custom login page always returns a realm parameter to the agent.

  • The realm that the agent is logging the user into has DNS aliases configured in AM.

  • AM logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL logs in the marketplace realm if the realm alias is set to marketplace.example.com.

  • The users should always log in to the Top Level Realm.

Examples

+

Requests containing a header called X-local with the value provided are redirected to the specified URL in the beta realm:

+

org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|http://mysite.local.com:8081/login?realm=beta

+

Requests containing a header called X-local with any value are redirected to the default URL in the gamma realm:

+

org.forgerock.agents.oauth.login.url.list[1]= X-local:|?realm=gamma

+

Requests containing a parameter called site with the value shopping AND a parameter called mode with the value discount are redirected to the default URL in the discountshopping realm:

+

org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping,mode=discount|?realm=discountshopping

+

Requests containing a parameter called target with the value cooking are redirected to the AM XUI page in the kitchen realm. Note the use of & before the realm parameter:

+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking|https://am.example.com:8443/openam/XUI/#login/&realm=kitchen

+

Requests containing a parameter called target with the value cooking are redirected to a non-AM login page in the kitchen realm. Note the use of ? before the realm parameter:

+

org.forgerock.openam.agents.config.conditional.login.url[0]= ?target=cooking|https://mysite.example.com:8443/login/?realm=kitchen

Property name

org.forgerock.agents.oauth.login.url.list

Aliases

org.forgerock.agents.oauth.login.url.list
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.conditional.login.url
  Introduced in Java Agent 5.6
  Recognized from AM 6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: OAuth Login URL List

Legacy title: AM Conditional Login URL

Enable Custom Login Mode

Set the login redirection mode, as follows:

  • false: Use default login redirection mode.

    • The agent can redirect requests to any AM instance that supports the /oauth2/authorize endpoint. By default, this is the AM instance that is specified during installation.

    • The /oauth2/authorize endpoint returns an OIDC ID token. This is the only response the agent accepts.

    • Use with OAuth Login URL List to modify or redirect calls to the endpoint that provides the tokens.

  • true: Use custom login redirection mode.

    • The agent handles JWTs or SSO tokens as session tokens for authentication and authorization, and can can redirect login anywhere.

    • Use with AM Login URL List and Legacy Login URL List to modify or redirect calls.

During session upgrade, the format of the composite advice is as follows:

  • When both this property and Enable SSO Token Acceptance are true, the composite advice has the following format: ?authIndexType=composite_advice&authIndexValue=<Advices Value>

  • When either property is false, the composite advice has the following format: ?composite_advice=<Advices Value>

Property name

org.forgerock.agents.legacy.login.enabled

Aliases

org.forgerock.agents.legacy.login.enabled
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.allow.custom.login
  Introduced in Java Agent 5.6
  Recognized from AM 7

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Enable Custom Login Mode

Legacy title: Allow Custom Login Mode

AM Login URL List

The URL of the login page to use for authentication.

During the redirect, the agent appends the following parameters to the agent’s CDSSO endpoint:

Use the format URL[?realm=realm_name?parameter1=value1&…​], where:

  • URL: URL of the login page to use for authentication

  • [?realm=realm_name&parameter1=value1&…​]: Optional parameters that the agent passes to the login page, for example, the AM realm at which to authenticate.

You do not need to specify an authentication realm if any of the following conditions are true:

  • The custom login page sets the realm parameter, for example, because it lets the user choose the realm.

  • The user authenticates into a realm that has DNS aliases configured in AM. AM then logs the user into the realm whose DNS alias matches the incoming request URL. For example, an inbound request from http://marketplace.example.com logs in the marketplace realm if the realm alias is set to marketplace.example.com.

  • The user authenticates to the top-level realm.

This parameter can be overwritten by the custom login page if, for example, the user chooses the authentication realm.

Specify as many parameters your custom login pages require.

Example:

https://login.example.com/login.jsp?realm=marketplace&param1=value1

In some versions of AM you can configure more than one value for this property, but only the first value is honored.

Property name

com.sun.identity.agents.config.login.url

Aliases

com.sun.identity.agents.config.login.url
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: AM Login URL List

Legacy title: AM Login URL

Login Reason Parameter Name

When Enable Custom Login Mode is true, this property specifies the name of a parameter included in calls to the custom login URL, to indicate why authentication is required. The parameter value can be used in a custom login page to provide additional feedback to the authenticating user.

If this property is specified, the agent includes a parameter named with the property value, and including one of the following values:

  • NO_TOKEN: No token present in the original request.

  • TOKEN_EXPIRED: Expiry time of the JWT was in the past.

  • EXCEPTION: An unknown exception occurred, either while parsing the JWT or at some other stage of authentication.

To reduce the risk of leaking useful information, use the property Login Reason Value Map to change the strings for the above values.

For example, specifying org.forgerock.agents.login.reason.parameter.name=auth_reason can cause the agent to redirect authentication to the following URL: https://custom.example.com:8443/…​./login_endpoint?…​&auth_reason=TOKEN_EXPIRED&…​

Do not enter a value that clashes with other parameters used for authentication; for example, realm or goto.

Property name

org.forgerock.agents.login.reason.parameter.name

Aliases

org.forgerock.agents.login.reason.parameter.name
  Introduced in Java Agent 5.7

Function

Custom login redirect, Login redirect

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Login Reason Parameter Name

Legacy Login URL List

Adds parameters conditionally to legacy login URLs.

Format, with no spaces between values:

domain/path|url?param1=value1&param2=value2

Domain/path

The incoming request URL:

  • Domain: For example, example.com. The agent must match the domain 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.

  • Subdomain: For example, mydomain.example.com. The agent match the domain, the subdomain, and any sub-subdomain. For example, mydomain.example.com matches true.mydomain.example.com. Subdomains can include path information, for example, mydomain.example.com/s6ecure, but cannot specify ports.

  • Path: For example, /myapp.

  • No value: Nothing is specified before the | character and the rule applies to every incoming request.

URL

The URL to which redirect incoming login requests. The URL may be an AM instance, an AM site, or a website other than AM.

Specify a URL in the format protocol://FQDN[:port]/URI, where the port is optional if it is 80 or 443. For example:

https://myweb.example.com/authApp/login.jsp

https://am.example.com:8443/openam/XUI/#login/

https://am.example.com:8443/openam/customlogin/login.jsp

If the URL is not specified, the agent redirects the request to the AM instance or site specified by the following bootstrap properties:

org.forgerock.agents.am.protocol://org.forgerock.agents.am.hostname:org.forgerock.agents.am.port/org.forgerock.agents.am.path

&parameter1=value1

Parameters that can be added to the URL. Add as many parameters as your custom login pages need. Chain parameters with an & character, for example, realm=value&parameter1=value1&parameter2=value2.

Examples

org.forgerock.agents.legacy.login.url.list[0]=example.com|https://am.example.com/openam/XUI/#login&realm=customers

org.forgerock.agents.legacy.login.url.list[1]=myapp.domain.com|https://login.example.com/apps/login.jsp?realm=sales

org.forgerock.agents.legacy.login.url.list[2]=sales.example.com/marketplace|?realm=marketplace

org.forgerock.agents.legacy.login.url.list[3]=|https://login.example.com/apps/login.jsp?realm=sales&isblue=true&carowner=true

org.forgerock.agents.legacy.login.url.list[4]=|?realm=sales

Property name

org.forgerock.agents.legacy.login.url.list

Aliases

org.forgerock.openam.agents.config.conditional.custom.login.url
  Introduced in Java Agent 5.6
  Recognized from AM 7

org.forgerock.agents.legacy.login.url.list
  Introduced in Java Agent 5.6

Function

Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default)

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Legacy Login URL List

Legacy title: Custom Conditional Login URL

Logout

Logout URI Map

A map of request URIs that trigger logout of the user session. Use the following key:value format:

web application name:logout URI

When a URL that includes the specified URI is invoked, the agent kills the current session. It invokes the AM REST logout endpoint or the endpoint configured by Conditional Logout URL List.

The agent must be able to access the context for the URL. When a web application is specified, it must exist and the agent must have access to it.

The URL is a dummy URL. Even if a resource exists at the URL, it is never accessed.

Although logout can be triggered within any web application by invoking a single, common, URI, you can taylor it for particular web applications:

  • To specify a single, common, URI, leave the key empty.

  • To specify a URI unique to a particular web application, specify the name of the web application as the key.

Property name

org.forgerock.agents.logout.endpoint.map

Aliases

com.sun.identity.agents.config.logout.uri
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.logout.endpoint.map
  Introduced in Java Agent 5.6

Function

Logout

Type

Map

  • Keys: web application

  • Values: URI of dummy endpoint which will trigger logout

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Logout URI Map

Legacy title: Application Logout URI

Logout Request Parameter Map

A map of request parameters that trigger logout of the user session. Use the following key:value format:

Logout Request Parameter Map[web application name] = parameter name to trigger logout

The agent searches every incoming request for the parameter. When the agent detects the parameter, it invokes AM to kill the current session for the specified web application or all web applications.

The request URL must contain the parameter but does not need to assign a value to the parameter.

Although logout can be triggered from any web application by invoking one common URI, you can adapt it for particular web applications:

  • To specify one parameter for all web applications, leave the key empty.

  • To specify a parameter for a particular web application, specify the name of the web application as the key.

Property name

org.forgerock.agents.logout.request.param.map

Aliases

org.forgerock.agents.logout.request.param.map
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.logout.request.param
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Logout

Type

Map

  • Keys: web application

  • Values: (single) HTTP query parameter to trigger logout

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Logout Request Parameter Map

Legacy title: Logout Request Parameter

Always invalidate sessions

When false, the agent does not invoke the AM REST logout endpoint to kill the user session.

If Conditional Logout URL List is configured with a URL that does not perform a REST logout to AM, set this property to true. The agent additionally invokes the AM REST logout endpoint to invalidate the session.

Property name

org.forgerock.agents.config.logout.session.invalidate.enabled

Aliases

org.forgerock.agents.config.logout.session.invalidate.enabled
  Introduced in Java Agent 5.10.1

org.forgerock.agents.config.logout.session.invalidate
  Introduced in Java Agent 5.10.1

Function

Logout

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Enable Logout Introspection

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

Property name

org.forgerock.agents.logout.introspection.enabled

Aliases

com.sun.identity.agents.config.logout.introspect.enabled
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.logout.introspection.enabled
  Introduced in Java Agent 5.6

Function

Logout

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Enable Logout Introspection

Legacy title: Logout Introspect Enabled

Conditional Logout URL List

Define URLs to which the agent can conditionally direct the user on logout. This property does not trigger logout.

Configure one or more conditions, using this format:

domain/path|url?param1=value1&param2=value2

The request URL is compared to each condition in the list until a match is found. Conditions are evaluated by order of length, starting with the longest, irrespective of their order in the list.

Depending on the value of the redirection URL, perform this additional configuration:

  • If the URL doesn’t perform a REST logout to AM, set Always invalidate sessions to true. The agent additionally invokes the AM REST logout endpoint to invalidate the session.

  • If the URL isn’t relative to an AM URL, or in the same scheme, FQDN, and port as an AM URL, add it to the AM validation service.

In the following example, example.com/path is evaluated before example.com; the default condition is the shortest, and is evaluated last:

org.forgerock.agents.conditional.logout.url.list[0]=example.com|?additional=value

org.forgerock.agents.conditional.logout.url.list[1]=example.com/path|?one=red&two=green&three=blue

org.forgerock.agents.conditional.logout.url.list[2]=mybank.com|http://mybank.com/myapp/logout?param=override

org.forgerock.agents.conditional.logout.url.list[3]=|?alpha=beta

For more information, refer to Conditionally log out to different URLs.

Property name

org.forgerock.agents.conditional.logout.url.list

Aliases

org.forgerock.openam.agents.config.conditional.logout.url
  Introduced in Java Agent 5.6
  Recognized from AM 6

org.forgerock.agents.conditional.logout.url.list
  Introduced in Java Agent 5.6

Function

Logout

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: Conditional Logout URL List

Legacy title: AM Conditional Logout URL

Logout Entry URI Map

A map of redirection resources to which the agent redirects the user after logout triggered by Logout URI Map or Logout Request Parameter Map. The resource can be an HTML page or JSP file. Use the following key:value format:

Logout Entry URI Map[web application name] = logout resource

To configure logout redirection for a specific web application, set the key to the name of the web application. To configure logout redirection for all web applications, leave the key empty (Logout Entry URI Map = default logout resource).

Specified resources are automatically added to the not-enforced list so that they can be accessed without authentication.

Depending on the type and value of the redirection resource, perform this additional configuration:

  • If the resource is a URL that doesn’t perform a REST logout to AM, set Always invalidate sessions to true. The agent additionally invokes the AM REST logout endpoint to invalidate the session.

  • If the resource is a URL that isn’t relative to an AM URL, or in the same scheme, FQDN, and port as an AM URL, add it to the AM validation service.

For more information, refer to Conditionally log out to different URLs.

Property name

org.forgerock.agents.logout.goto.map

Aliases

com.sun.identity.agents.config.logout.entry.uri
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.logout.goto.map
  Introduced in Java Agent 5.6

Function

Logout

Type

Map

  • Keys: web application

  • Values: URI of page explaining the user has been logged out

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Logout Entry URI Map

Legacy title: Logout Entry URI

Logs

Agent Debug Level

The agent log level.

Make sure your container captures messages written to the standard output. Some containers do not, and warnings or critical errors can disappear forever.

Property name

org.forgerock.agents.debug.level

Aliases

com.iplanet.services.debug.level
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.debug.level
  Introduced in Java Agent 5.6

Function

Logs

Supported settings

OFF

(Deprecated) Uses the same log level as ERROR. To disable logging, edit agent-logback.xml. Forgerock advises not to disable logging.

ERROR

Log only errors.

WARNING

Log errors and warnings.

MESSAGE

Log errors, warnings, and informative messages.

DEBUG

Log errors, warnings, informative messages, and some debugging messages.

TRACE

Log fine-grained information, when you need the full visibility of what is happening in your application. This log level can create big log files, so use only when necessary, and then reduce the log level.

ON

(Deprecated) Uses the same log level as TRACE. When the log level is ON, TRACE level logs are written to file. In previous releases, TRACE level logs were written to the standard output. Make sure your container captures messages written to the standard output.

Default

ERROR

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: Agent Debug Level

Miscellaneous

The cookie name to use to detect redirect loops while authenticating, which would indicate a cookie domain problem.

Property name

org.forgerock.agents.redirect.cookie.name

Aliases

org.forgerock.agents.redirect.cookie.name
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.redirect.cookie.name
  Introduced in Java Agent 5.0
  Recognized from AM 7

Function

Miscellaneous

Type

String

Default

amFilterRDParam

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global (from AM 7)

Title: Redirect Attempt Cookie Name

Encrypted Agent Password

The agent profile password, which must correspond to the value in AM.

Set this property to the encrypted value of the password, where the password is encrypted using the key in the property Encryption Key/Salt.

Use the following command to get the encrypted value of the password, where passwordFile contains only the password followed by a newline, and has the access permission 400:

$ ./agentadmin --encrypt agentInstance passwordFile

Default: Empty

Property name

org.forgerock.agents.encrypted.password

Aliases

com.iplanet.am.service.secret
  Introduced in Java Agent 5.0

org.forgerock.agents.encrypted.password
  Introduced in Java Agent 5.6

Function

Miscellaneous, Required

Type

String

Bootstrap property

No

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentPassword.properties

Enable Ignore Path Info

When true, when the request URL contains a wildcard '*' character, the path info and query are stripped from the URL before it is compared with the list of not-enforced URLs.

Property name

org.forgerock.agents.ignore.path.info.enabled

Aliases

com.sun.identity.agents.config.ignore.path.info
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.ignore.path.info.enabled
  Introduced in Java Agent 5.6

Function

Miscellaneous

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous

Title: Enable Ignore Path Info

Legacy title: Ignore Path Info for Not Enforced URLs

Custom Response Header Map

A key:value map of custom headers set by the agent for the client, where the key is the header name, and the value is the header value. For example, org.forgerock.agents.response.header.map[Cache-Control]=no-cache

Format org.forgerock.agents.response.header.map[HEADER-NAME]=HEADER-VALUE

Property name

org.forgerock.agents.response.header.map

Aliases

org.forgerock.agents.response.header.map
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.response.header
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Miscellaneous

Type

Map

  • Keys: from header

  • Values: to header

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: Custom Response Header Map

Legacy title: Custom Response Header

Idle Time Refresh Window

The interval in minutes at which the agent calls AM to refresh a session idle timeout.

AM sessions have an idle timeout after which they expire. In general, when users access protected resources through an agent, the agent requests a policy decision on behalf of that user, which resets the idle timeout.

When the agent does not need to contact AM frequently, for example, when policy evaluation is already cached, sessions may unexpectedly expire in AM before the user has finished accessing the application.

Agents make one call per active user session at the end of the time interval, provided that the user is actively accessing the web application or site. If the user does not access the application during the configured window interval time, the agent will not make the call to AM at the end of the interval. Eventually, if the user is inactive for enough time, AM will log them out when the session reaches its idle timeout.

Configuring the idle timeout window to a short value, such as one minute, achieves a good balance between making additional calls to AM and providing a good user experience.

Increase this value only if the performance impact of making an extra call to AM every minute is noticeable enough in your environment.

Property name

org.forgerock.agents.idle.time.window.minutes

Aliases

org.forgerock.agents.idle.time.window.minutes
  Introduced in Java Agent 5.6.2.1
  Recognized from AM 7

Function

Miscellaneous

Type

Integer

Default

1

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced (from AM 7)

Title: Idle Time Refresh Window

Service Resolver Class Name

The Java class name of the service resolver used to override the provided service resolver. Use this property to customize pre-handlers and post-handlers.

Property name

org.forgerock.agents.service.resolver.class.name

Aliases

org.forgerock.agents.service.resolver.class.name
  Introduced in Java Agent 5.6.2.1
  Recognized from AM 7

Function

Miscellaneous

Type

Classname

Default

com.sun.identity.agents.arch.ServiceResolver

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

HTTP Session Binding

When true, the agent invalidates the HTTP session in these circumstances:

  • Login failure

  • When the user has no SSO session

  • When the principal user name does not match the SSO user name

Property name

org.forgerock.agents.http.session.binding.enabled

Aliases

com.sun.identity.agents.config.httpsession.binding
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.http.session.binding.enabled
  Introduced in Java Agent 5.6

Function

Miscellaneous

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: HTTP Session Binding

Public AM URL

The assembled "public" URL of AM. This URL is used by the agent to redirect the user’s browser to AM for login (customised or not), or if necessary, exchange an SSO token for a JWT.

The following properties make up the URL:

The "private" URL is used by the agent for tasks such as establishing websockets, and obtaining authentication tokens or session information. The AM or load balancer instance can be behind a firewall to which the agent has access.

Define this property when public access to AM is restricted to a different URL from the private URL.

Property name

org.forgerock.agents.public.am.url

Aliases

com.forgerock.agents.public.am.url
  Introduced in Java Agent 5.6.3.0

org.forgerock.agents.public.am.url
  Introduced in Java Agent 5.6.3.0

Function

Miscellaneous, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Monitoring

Export Monitoring Metrics to CSV

When true, enables the export of agent performance monitoring metrics to comma-separated value (CSV) files.

Files are written the same directory as the agent instance debug files, for example in /path/to/java_agents/tomcat_agent/Agent_001/logs/debug/.

Property name

org.forgerock.agents.config.monitoring.to.csv

Aliases

org.forgerock.agents.config.monitoring.to.csv
  Introduced in Java Agent 5.6
  Recognized from AM 7

org.forgerock.agents.monitoring.to.csv.enabled
  Introduced in Java Agent 5.6

Function

Monitoring

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced (from AM 7)

Title: Export Monitoring Metrics to CSV

CSV Monitoring Directory

The full path to the directory where the agent writes CSV monitoring files, when CSV monitoring is enabled.

The default is set by the installer and written to the bootstrap properties file.

Default: /logs/debug directory relative to the definedBy of the agent installation

Property name

org.forgerock.agents.csv.monitoring.directory

Aliases

org.forgerock.agents.csv.monitoring.directory
  Introduced in Java Agent 5.7

Function

Monitoring

Type

String

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Not-enforced

Not-Enforced URIs

A space-delimited list of URIs. The agent applies the not-enforced rule for requests to the listed URIs. In the following example, the agent allows requests to the public and images directories of myapp.example.com:

org.forgerock.agents.notenforced.uri.list=https://myapp.example.com:8443/public/* https://myapp.example.com:8443/images/*

For more information and examples, see Conventions for not-enforced rules.

Property name

org.forgerock.agents.notenforced.uri.list

Aliases

org.forgerock.agents.notenforced.uri.list
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.notenforced.uri
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Not-enforced

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Not-Enforced Client IP List

A space-delimited list of IP addresses or network CIDR notation addresses. The agent applies the not-enforced rule to requests from the listed IP addresses.

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

Property name

org.forgerock.agents.notenforced.ip.list

Aliases

org.forgerock.agents.notenforced.ip.list
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.notenforced.ip
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Not-enforced

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Not-Enforced Favicon

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

Property name

org.forgerock.agents.auto.not.enforce.favicon

Aliases

org.forgerock.agents.auto.not.enforce.favicon
  Introduced in Java Agent 5.7
  Recognized from AM 7

org.forgerock.agents.auto.not.enforce.favicon.enabled
  Introduced in Java Agent 5.7

Function

Not-enforced

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Application (from AM 7)

Title: Not-Enforced Favicon

Legacy title: Not Enforced Favicon

Enable Not-Enforced URIs Cache

When true, the agent caches evaluations of the Not-Enforced URIs.

Enable this setting when configuring many rules.

Property name

org.forgerock.agents.notenforced.uri.cache.enabled

Aliases

org.forgerock.agents.notenforced.uri.cache.enabled
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.notenforced.uri.cache.enable
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Not-enforced

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Enable Not-Enforced URIs Cache

Legacy title: Not Enforced URIs Cache Enabled

Container Character Encoding

The character encoding used by the agent when encoding extended characters in the resource paths of not-enforced rules.

Property name

org.forgerock.agents.container.encoding

Aliases

org.forgerock.agents.container.encoding
  Introduced in Java Agent 5.9.1

Function

Container, Not-enforced

Type

String

Default

UTF-8

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Java Class for Matching Not Enforced Rules

The Java class used to match URIs and IP addresses embedded within not enforced rules.

The specified class must implement the interface com.sun.identity.agents.common.RulePatternMatcher.

If the class fails to instantiate, an error is logged and the default NotEnforcedRulePatternMatcher is created instead.

Property name

org.forgerock.agents.not.enforced.rule.pattern.matcher.classname

Aliases

org.forgerock.agents.not.enforced.rule.pattern.matcher.classname
  Introduced in Java Agent 5.9.0

Function

Not-enforced

Type

Classname

Default

com.sun.identity.agents.common.NotEnforcedRulePatternMatcher

Bootstrap property

Yes

Required property

No

Restart required

No

Local configuration file

AgentBootstrap.properties

Not-Enforced Compound Rule Separator

A delimiter for 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

Property name

org.forgerock.agents.notenforced.compound.separator

Aliases

org.forgerock.agents.notenforced.compound.separator
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.notenforced.rule.compound.separator
  Introduced in Java Agent 5.0
  Recognized from AM 7

Function

Not-enforced

Type

String

Default

|

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Not-Enforced Compound Rule Separator

Invert Not-Enforced URIs

The use of this property is NOT recommended.

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

For security considerations, do not enable this property. Instead, use the NOT keyword to invert specific rules in the Not-Enforced URIs.

Property name

org.forgerock.agents.notenforced.uri.invert.enabled

Aliases

com.sun.identity.agents.config.notenforced.uri.invert
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.notenforced.uri.invert.enabled
  Introduced in Java Agent 5.6

Function

Not-enforced

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Invert Not-Enforced URIs

Legacy title: Invert Not Enforced URIs

Max Entries in Not-Enforced URI Cache

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

Property name

org.forgerock.agents.notenforced.uri.cache.size

Aliases

com.sun.identity.agents.config.notenforced.uri.cache.size
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.notenforced.uri.cache.size
  Introduced in Java Agent 5.6

Function

Not-enforced

Type

Integer

Default

10000

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Max Entries in Not-Enforced URI Cache

Legacy title: Not Enforced URIs Cache Size

Enable Not-Enforced IP Cache

The use of this property is NOT recommended.

When true, the agent caches evaluations of the Not-Enforced Client IP List.

Enable this setting if you are configuring many rules.

Property name

org.forgerock.agents.notenforced.ip.cache.enabled

Aliases

org.forgerock.agents.notenforced.ip.cache.enabled
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.notenforced.ip.cache.enable
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Not-enforced

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Enable Not-Enforced IP Cache

Legacy title: Not Enforced IP Cache Flag

Invert Not-Enforced IPs

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

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

Property name

org.forgerock.agents.notenforced.ip.invert.enabled

Aliases

org.forgerock.agents.notenforced.ip.invert.enabled
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.notenforced.ip.invert
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Not-enforced

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Invert Not-Enforced IPs

Legacy title: Invert Not Enforced IPs

Max Entries in Not-Enforced IP Cache

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

Property name

org.forgerock.agents.notenforced.ip.cache.size

Aliases

org.forgerock.agents.notenforced.ip.cache.size
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.notenforced.ip.cache.size
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Not-enforced

Type

Integer

Default

1000

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Max Entries in Not-Enforced IP Cache

Legacy title: Not Enforced IP Cache Size

Container Parameter Encoding

The character encoding used by the agent when encoding extended characters in the HTTP query parameters of not-enforced rules.

Property name

org.forgerock.agents.container.param.encoding

Aliases

org.forgerock.agents.container.param.encoding
  Introduced in Java Agent 5.9.1

Function

Container, Not-enforced

Type

String

Default

ISO-8859-1

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Notifications

Enable Notifications of Agent Configuration Change

Flag to indicate whether the agent subscribes to WebSocket notifications from AM for configuration changes. This property applies only the agent profile is stored in AM’s configuration data store.

Property name

org.forgerock.agents.config.change.notifications.enabled

Aliases

org.forgerock.agents.config.change.notifications.enabled
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.change.notification.enable
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Notifications

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

Yes

Required property

No

Restart required

No

Local configuration file

AgentBootstrap.properties

AM console

Tab: Global

Title: Enable Notifications of Agent Configuration Change

Legacy title: Agent Configuration Change Notification

Enable Notification of Session Logout (deprecated)

Use Enable Notification of Session Logout instead of this property.

Flag to indicate whether the agent polls AM for session status updates.

Default: false

Property name

com.iplanet.am.session.client.polling.enabled

Deprecated in

5.6

Aliases

com.iplanet.am.session.client.polling.enabled
  Introduced in Java Agent 5.6

com.iplanet.am.session.client.polling.enable
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Notifications

Type

Boolean: true returns true; all other strings return false.

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Enable Notification of Policy Changes

Flag to indicate whether the agent subscribes to WebSocket notifications from AM for policy changes.

Property name

org.forgerock.agents.policy.change.notifications.enabled

Aliases

org.forgerock.agents.policy.change.notifications.enabled
  Introduced in Java Agent 5.6

com.sun.identity.agents.notification.enabled
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Notifications

Type

Boolean: true returns true; all other strings return false.

Default

true

Bootstrap property

Yes

Required property

No

Restart required

No

Local configuration file

AgentBootstrap.properties

AM console

Tab: AM Services

Title: Enable Notification of Policy Changes

Enable Notification of Session Logout

Flag to indicate whether the agent subscribes to WebSocket notifications from AM for session logout.

Default: true

Property name

org.forgerock.agents.session.change.notifications.enabled

Aliases

org.forgerock.agents.session.change.notifications.enabled
  Introduced in Java Agent 5.6
  Recognized from AM 7

Function

Notifications

Type

Boolean: true returns true; all other strings return false.

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global (from AM 7)

Title: Enable Notification of Session Logout

POST data preservation

POST Data Preservation Max HTML Form Size

The maximum size of all name/value pairs submitted in an HTML form during POST data preservation. Set to zero to remove the limit.

This property is valid only when Enable POST Data Preservation is true.

Property name

org.forgerock.agents.pdp.parameter.limit.bytes

Aliases

org.forgerock.agents.pdp.parameter.limit.bytes
  Introduced in Java Agent 2023.11
  Recognized from AM 7.1

Function

POST data preservation

Type

Integer

Default

104857600

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

POST Data Preservation Directory Sweep Interval

The interval in seconds at which the POST Data Preservation File Directory is swept for expired files. Files expire after the time defined by POST Data Preservation Cache TTL.

This property is valid only when Enable POST Data Preservation and POST Data Preservation in Files or Cache are true, and POST Data Preservation File Directory is a valid directory.

Property name

org.forgerock.agents.pdp.directory.sweep.seconds

Aliases

org.forgerock.agents.pdp.directory.sweep.seconds
  Introduced in Java Agent 5.10.0

Function

POST data preservation

Type

Integer

Default

10

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Missing POST Data Preservation Entry URI Map

A map of URLs to which the agent redirects when the POST data preservation cache entry is discarded due to a cache timeout. The URL is expected to be a page explaining what has happened.

Property name

org.forgerock.agents.pdp.noentry.url.map

Aliases

org.forgerock.agents.pdp.noentry.url.map
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.postdata.preserve.cache.noentry.url
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

POST data preservation

Type

Map

  • Keys: web application

  • Values: URL of page explaining the PDP entry was discarded

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: Missing POST Data Preservation Entry URI Map

Legacy title: Missing PDP entry URI

POST Data Preservation Cache TTL

The interval in minutes at which entries in the POST data preservation cache timeout and are purged.

Property name

org.forgerock.agents.pdp.cache.ttl.minutes

Aliases

org.forgerock.agents.pdp.cache.ttl.minutes
  Introduced in Java Agent 5.6
  Recognized from AM 7

Function

POST data preservation

Type

Integer

Default

5

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced (from AM 7)

Title: POST Data Preservation Cache TTL

Legacy title: PDP Cache TTL in Minutes

POST Data Preservation Sticky Session Key Value

A name/value pair separated by =, as follows:

When POST Data Preservation Sticky Session Mode is URL, this property sets the query parameter name and value.

When POST Data Preservation Sticky Session Mode is Cookie, this property sets the cookie name and value.

Property name

org.forgerock.agents.pdp.sticky.session.value

Aliases

com.sun.identity.agents.config.postdata.preserve.stickysession.value
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.pdp.sticky.session.value
  Introduced in Java Agent 5.6

Function

POST data preservation

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: POST Data Preservation Sticky Session Key Value

Legacy title: PDP Stickysession key-value

POST Data Preservation Sticky Session Mode

Property name

org.forgerock.agents.pdp.sticky.session.mode

Aliases

org.forgerock.agents.pdp.sticky.session.mode
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.postdata.preserve.stickysession.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

POST data preservation

Supported settings

COOKIE

The sticky session mode is sent as a cookie (name/value specified by "POST Data Preservation Sticky Session Key Value" (org.forgerock.agents.pdp.sticky.session.value)).

URL

The sticky session mode is sent as an HTTP parameter name/value pair (specified by "POST Data Preservation Sticky Session Key Value" (org.forgerock.agents.pdp.sticky.session.value)).

Default

URL

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: POST Data Preservation Sticky Session Mode

Legacy title: PDP Stickysession mode

Enable POST Data Preservation

When true, unauthenticated POST data is stored before redirecting to the login screen, then auto-submitted after successful authentication.

Property name

org.forgerock.agents.post.data.preservation.enabled

Aliases

org.forgerock.agents.post.data.preservation.enabled
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.postdata.preserve.enable
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

POST data preservation

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Advanced

Title: Enable POST Data Preservation

Legacy title: Post Data Preservation enabled

POST Data Preservation in Files or Cache

When Enable POST Data Preservation is true, this property determines how POST data is saved:

true: Save POST data to files

false (default): Save POST data to the in-memory cache

Files are stored in the POST Data Preservation File Directory. Expired files are removed at the interval given by POST Data Preservation Directory Sweep Interval.

Property name

org.forgerock.agents.pdp.use.filesystem.enabled

Aliases

org.forgerock.agents.pdp.use.filesystem.enabled
  Introduced in Java Agent 5.10.0

Function

POST data preservation

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Pre-Authn and Post Data Preservation Cookie Signing Value

The key to sign pre-authentication cookies and POST data preservation cookies.

The key is set during installation, when the agent requests the path to a file containing the cookie signing key, and then uses the key to set the cookie signing value in the AgentKey.properties file. For information about how to set or change the key after installation, see Rotate cookie signing keys.

For security, you are recommended to configure cookie signing. The agent does not sign cookies when:

  • The path to the signing key is left blank during installation.

  • The signing key in the AgentKey.properties file is less than 64-characters long.

Property name

org.forgerock.agents.cookie.signing.value

Aliases

org.forgerock.agents.cookie.signing.value
  Introduced in Java Agent 5.10.0

Function

Cookie, POST data preservation, Pre-authentication

Type

String

Bootstrap property

No

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentKey.properties

POST Data Preservation Storage Size

The maximum number of megabytes allocated to store POST data. When the maximum is reached, old entries are discarded.

Use this property to mitigate the risk of DDoS attacks.

This property takes precedence over Max Entries in POST Data Preservation Storage.

Property name

org.forgerock.agents.pdp.cache.total.size.mb

Aliases

org.forgerock.agents.pdp.cache.total.size.mb
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.postdata.preserve.cache.entry.max.total.size.mb
  Introduced in Java Agent 5.6
  Recognized from AM 6

Function

POST data preservation

Type

Integer

Default

``

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced

Title: POST Data Preservation Storage Size

Legacy title: PDP Maximum Cache Size

Max Entries in POST Data Preservation Storage

When POST Data Preservation in Files or Cache is false, the maximum number of entries in the POST data preservation storage cache.

When POST Data Preservation in Files or Cache is true, the maximum number of files in the POST Data Preservation File Directory.

When the maximum is reached, old entries are discarded.

Use this property to mitigate the risk of DoS attacks.

POST Data Preservation Storage Size takes precedence over this property.

Property name

org.forgerock.agents.pdp.cache.size

Aliases

org.forgerock.agents.pdp.cache.size
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.postdata.preserve.cache.entry.max.entries
  Introduced in Java Agent 5.6
  Recognized from AM 6

Function

POST data preservation

Type

Integer

Default

1000

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced

Title: Max Entries in POST Data Preservation Storage

Legacy title: PDP Maximum Number of Cache Entries

POST Data Preservation File Directory

When Enable POST Data Preservation and POST Data Preservation in Files or Cache are true, this property defines the directory in which POST data preservation data files are saved.

The agent must be able to access the directory. If the directory does not exist, or the agent cannot access it, Enable POST Data Preservation is set to false.

Default: /path/to/java_agents/agent_type/Agent_n/tmp/pdp.

Property name

org.forgerock.agents.pdp.directory

Aliases

org.forgerock.agents.pdp.directory
  Introduced in Java Agent 5.10.0

Function

POST data preservation

Type

String

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Post Data Preservation Cookie Name

The name of the Post Data Preservation cookie. This cookie maintains the security of the data in unauthenticated POST requests. It contains a unique one-time code which is cross-checked against the stored data making it extremely difficult for malicious actors to replay the stored data for other users.

Since Java Agent 5.10, there is the option of creating one cookie for all concurrent PDP requests, or alternatively to have one uniqely named cookie per request.

If you have tests in your environment that make multiple PDP requests to the agent, you may find intermittent failures as browsers can limit how many cookies they handle.

Configure the cookie name as follows:

  • To use one cookie for all concurrent PDP requests to AM, configure as a string. For example, org.forgerock.agents.pdp.cookie.name=cookie-name.

  • To use one cookie for each authentication request to AM, configure as %n before, in the middle, or after a string. When the agent creates the cookie, it substitutes %n for a unique identifier. For example:

    • org.forgerock.agents.pdp.cookie.name=%n

    • org.forgerock.agents.pdp.cookie.name=%n-cookie-name

    • org.forgerock.agents.pdp.cookie.name=cookie-%n-name

    • org.forgerock.agents.pdp.cookie.name=cookie-name-%n

The agent compresses and then signs the cookie.

Property name

org.forgerock.agents.pdp.cookie.name

Aliases

org.forgerock.agents.pdp.cookie.name
  Introduced in Java Agent 5.10.0
  Recognized from AM 7.1

Function

Cookie, POST data preservation

Type

String

Default

PDP_Nonce

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

POST Data Preservation Cache TTL in Milliseconds (deprecated)

Specifies the POST data preservation cache timeout in milliseconds.

Use POST Data Preservation Cache TTL instead of this property.

If this property and POST Data Preservation Cache TTL are set, this property takes precedence.

Property name

com.sun.identity.agents.config.postdata.preserve.cache.entry.ttl

Deprecated in

5.6

Aliases

com.sun.identity.agents.config.postdata.preserve.cache.entry.ttl
  Introduced in Java Agent 5.0

Function

POST data preservation

Type

Integer

Default

-2147483648

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Policy enforcement

POST Parameter List for URL Policy Env

The list of HTTP POST request parameters whose names and values the agent sets in the environment map for URL policy evaluation by the AM server.

Property name

org.forgerock.agents.continuous.security.post.list

Aliases

com.sun.identity.agents.config.policy.env.post.param
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.continuous.security.post.list
  Introduced in Java Agent 5.7

Function

Policy enforcement

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: POST Parameter List for URL Policy Env

Legacy title: URL Policy Env POST Parameters

Max Entries in Policy Cache per Session

The maximum number of policy evaluation entries allowed in the policy evaluation cache for each session.

The number of policy evaluation results that can be stored is this property multiplied by the value of Max Sessions in Policy Cache.

Property name

org.forgerock.agents.policy.cache.per.session.size

Aliases

com.sun.identity.policy.client.cacheResultsPerUserCap
  Introduced in Java Agent 5.0

org.forgerock.agents.policy.cache.per.session.size
  Introduced in Java Agent 5.6
  Recognized from AM 7

Function

Policy enforcement

Type

Integer

Default

50

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced (from AM 7)

Title: Max Entries in Policy Cache per Session

Legacy title: Policy Cache Per User

Restrict to Realm Map

A map to restrict access to the specified web application to users authenticated in the specified realm.

Property name

org.forgerock.agents.restrict.to.realm.map

Aliases

org.forgerock.agents.restrict.to.realm.map
  Introduced in Java Agent 5.6.2.1
  Recognized from AM 7

Function

Policy enforcement

Type

Map

  • Keys: web application

  • Values: allowed realms as CSV

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Restrict to Realm Map

Legacy title: Restrict To Realm

Enable Composite Advice Encoding

When true, composite advices are base64 URL-encoded before being sent to custom login endpoints. Use this property to increase security, and protect against cross-site scripting attacks.

Property name

org.forgerock.agents.advice.b64.url.encode.enabled

Aliases

com.forgerock.agents.advice.b64.url.encode
  Introduced in Java Agent 5.6.2.1
  Recognized from AM 7

org.forgerock.agents.advice.b64.url.encode.enabled
  Introduced in Java Agent 5.6.2.1

org.forgerock.agents.advice.b64.url.encode
  Introduced in Java Agent 5.6.2.1

Function

Policy enforcement

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7)

Title: Enable Composite Advice Encoding

Legacy title: Composite Advice Encode

Max Sessions in Policy Cache

The maximum number of sessions (distinct users) that can be stored in the policy evaluation cache at any time.

Property name

org.forgerock.agents.policy.cache.session.size

Aliases

org.forgerock.agents.policy.cache.session.size
  Introduced in Java Agent 5.6
  Recognized from AM 7

com.sun.identity.policy.client.cachedSessionCap
  Introduced in Java Agent 5.0

Function

Policy enforcement

Type

Integer

Default

5000

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced (from AM 7)

Title: Max Sessions in Policy Cache

Legacy title: Policy Cache Size

Enable Policy Evaluation in User Authentication Realm

When true, perform policy evaluation in the realm to which the user is authenticated, and ignore the value in Policy Evaluation Realm Map.

Use this property for web applications that dynamically set the realm for authentication.

Property name

org.forgerock.agents.user.realm.overrides.policy.evaluation.realm.enabled

Aliases

org.forgerock.agents.user.realm.overrides.policy.evaluation.realm.enabled
  Introduced in Java Agent 5.7.1
  Recognized from AM 7.1

Function

Policy enforcement

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services (from AM 7.1)

Title: Enable Policy Evaluation in User Authentication Realm

Legacy title: Perform Policy Evaluation in User Authenticated Realm

GET Parameter List for URL Policy Env

The list of HTTP GET request parameters whose names and values the agent sets in the environment map for URL policy evaluation by the AM server.

Property name

org.forgerock.agents.continuous.security.get.list

Aliases

com.sun.identity.agents.config.policy.env.get.param
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.continuous.security.get.list
  Introduced in Java Agent 5.7

Function

Policy enforcement

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: GET Parameter List for URL Policy Env

Legacy title: URL Policy Env GET Parameters

Policy Cache TTL

The interval in minutes at which entries in the policy cache time out and are purged.

Property name

org.forgerock.agents.policy.cache.ttl.minutes

Aliases

org.forgerock.agents.policy.cache.ttl.minutes
  Introduced in Java Agent 5.6

com.sun.identity.agents.polling.interval
  Introduced in Java Agent 5.0
  Recognized from AM 7

Function

Policy enforcement

Type

Integer

Default

3

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced

Title: Policy Cache TTL

JSession Parameter List for URL Policy Env

The list of HTTP session attributes whose names and values the agent sets in the environment map for URL policy evaluation by the AM server.

Property name

org.forgerock.agents.continuous.security.http.session.list

Aliases

org.forgerock.agents.continuous.security.http.session.list
  Introduced in Java Agent 5.7

com.sun.identity.agents.config.policy.env.jsession.param
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Policy enforcement

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: JSession Parameter List for URL Policy Env

Legacy title: URL Policy Env jsession Parameters

Policy Evaluation Realm Map

The name of an AM realm to use for policy evaluations. Different web applications can use different policy realms.

To prevent errors, use only characters in the standard ASCII set. The agent automatically percent-encodes characters in the extended ASCII set, however, the name must be manually encoded in AM.

Property name

org.forgerock.agents.policy.evaluation.realm.map

Aliases

org.forgerock.openam.agents.config.policy.evaluation.realm
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.policy.evaluation.realm.map
  Introduced in Java Agent 5.6.2.1

Function

Policy enforcement

Type

Map

  • Keys: web application

  • Values: realm

Default

/

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: Policy Evaluation Realm Map

Legacy title: Policy Evaluation Realm

Policy Set Map

The name of an AM policy set to use for policy evaluations. Different web applications can use a different policy set in their chosen realm.

To prevent errors, use only characters in the standard ASCII set. The agent automatically percent-encodes characters in the extended ASCII set, however, the name must be manually encoded in AM.

The following example causes AM to use mypolicyset to evaluate policies for all web applications:

org.forgerock.agents.policy.set.map=mypolicyset

The following example causes AM to use mypolicyset to evaluate policies for mywebapp. For all other web applications, AM uses iPlanetAMWebAgentService:

org.forgerock.agents.policy.set.map[mywebapp]=mypolicyset

Property name

org.forgerock.agents.policy.set.map

Aliases

org.forgerock.openam.agents.config.policy.evaluation.application
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.policy.set.map
  Introduced in Java Agent 5.6.2.1

Function

Policy enforcement

Type

Map

  • Keys: web application

  • Values: policy set

Default

iPlanetAMWebAgentService

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: AM Services

Title: Policy Set Map

Legacy title: Policy Set

Pre-authentication

Pre-Authn and Post Data Preservation Cookie Signing Value

The key to sign pre-authentication cookies and POST data preservation cookies.

The key is set during installation, when the agent requests the path to a file containing the cookie signing key, and then uses the key to set the cookie signing value in the AgentKey.properties file. For information about how to set or change the key after installation, see Rotate cookie signing keys.

For security, you are recommended to configure cookie signing. The agent does not sign cookies when:

  • The path to the signing key is left blank during installation.

  • The signing key in the AgentKey.properties file is less than 64-characters long.

Property name

org.forgerock.agents.cookie.signing.value

Aliases

org.forgerock.agents.cookie.signing.value
  Introduced in Java Agent 5.10.0

Function

Cookie, POST data preservation, Pre-authentication

Type

String

Bootstrap property

No

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentKey.properties

The maximum age in seconds of the pre-authentication cookie configured in Pre-Authentication Cookie Name.

Property name

org.forgerock.agents.authn.cookie.max.age.seconds

Aliases

org.forgerock.agents.authn.cookie.max.age.seconds
  Introduced in Java Agent 5.6.3.0
  Recognized from AM 7

Function

Cookie, Pre-authentication

Type

Integer

Default

600

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global (from AM 7)

Title: Max Age of Pre-Authentication Cookie

Legacy title: Pre-Authenticated Cookie Max Age

The name of the pre-authentication cookie. This cookie tracks the progress of authentication with AM, and protects requests from replay attacks. It contains the following information:

  • URL of the original request

  • HTTP mode

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

  • Relevant ACR information

  • Transaction ID

  • Expiry time configured by Max Age of Pre-Authentication Cookie

(Before Java Agent 5.7), The agent creates a single cookie containing records to identify all concurrent authentication requests to AM. In environments with lots of concurrent requests, or where the protected URLs are long, the cookie can reach the maximum size supported by the browser. When this happens, new authentication requests fail and the agent issues a 403 HTTP message to the user.

(Java Agent 5.7 and later versions) The agent can optionally create a cookie for each authentication request to AM. In some environments, this creates a large number of cookies. If you have tests in your environment that make multiple requests to AM from the same browser, you may find intermittent 403 HTTP messages; browsers can limit how many cookies they handle.

Configure the cookie name as follows:

  • To use one cookie for all concurrent authentication requests to AM, configure as a string. For example, org.forgerock.agents.authn.cookie.name=cookie-name.

  • To use one cookie for each authentication request to AM, configure as %n, or as %n before, in the middle of, or after a string. When the agent creates the cookie, it translates the string %n into a unique identifier. For example:

    • org.forgerock.agents.authn.cookie.name=%n

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

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

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

The agent compresses and then signs the cookie.

Property name

org.forgerock.agents.authn.cookie.name

Aliases

com.sun.identity.agents.config.cdsso.cookie.name
  Introduced in Java Agent 5.0
  Recognized from AM 7

org.forgerock.agents.authn.cookie.name
  Introduced in Java Agent 5.6

Function

Cookie, Pre-authentication

Type

String

Default

amFilterCDSSORequest

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global (from AM 7)

Title: Pre-Authentication Cookie Name

Legacy title: Pre-Authenticated Cookie Name

Profile

Location of Agent Configuration Repository

The location of the agent configuration.

Property name

org.forgerock.agents.config.location

Aliases

com.sun.identity.agents.config.repository.location
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.config.location
  Introduced in Java Agent 5.6

Function

Profile, Required

Supported settings

LOCAL

The agent configuration is read from AgentConfiguration.properties (only).

REMOTE

The agent configuration is downloaded from AM.

Default

REMOTE

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Global

Title: Location of Agent Configuration Repository

A list of domains in which the agent attempts to creates JWT cookies:

  • If the list is empty, the agent creates cookies only in its own domain.

  • If the agent is running behind a browser, it can create cookies only in its own domain.

  • If the agent is running behind a proxy, it should be able to create cookies in any required domains.

Default: Empty

Property name

org.forgerock.agents.jwt.cookie.domain.list

Aliases

com.sun.identity.agents.config.cdsso.domain
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.jwt.cookie.domain.list
  Introduced in Java Agent 5.6

Function

Profile

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7.1)

Title: JWT Cookie Domain List

Legacy title: CDSSO Domain List

JWT Cache TTL

The interval in minutes at which entries in the JWT cache timeout and are purged.

Parsing JWTs is a CPU intensive process. As all JWTs in the cache have already been parsed, consider using a long timeout for this cache.

Property name

org.forgerock.agents.jwt.cache.ttl.minutes

Aliases

org.forgerock.openam.agents.config.jwt.cache.ttl.minutes
  Introduced in Java Agent 5.0
  Recognized from AM 7

org.forgerock.agents.jwt.cache.ttl.minutes
  Introduced in Java Agent 5.6

Function

Profile

Type

Integer

Default

30

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced (from AM 7)

Title: JWT Cache TTL

Max Entries in JWT Cache

The maximum number of entries in the JWT cache.

Property name

org.forgerock.agents.jwt.cache.size

Aliases

org.forgerock.agents.jwt.cache.size
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.jwt.cache.size
  Introduced in Java Agent 5.0
  Recognized from AM 7

Function

Profile

Type

Integer

Default

5000

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced (from AM 7)

Title: Max Entries in JWT Cache

Legacy title: JWT Cache Size

The name of the cookie that holds the OIDC JWT on the user’s browser.

Before changing the name of this cookie, consider the following points:

  • This cookie is only used by the agent and is never presented to AM.

  • The cookie name must be unique in the cookies the user’s browser receives. For example, do not set the JWT cookie name to iPlanetDirectoryPro, which is the default name of the AM session cookie.

If the agent does not find the cookie named by JWT Cookie Name, authentication fails. The user can only access resources that are available through not-enforced rules.

Property name

org.forgerock.agents.jwt.cookie.name

Aliases

org.forgerock.openam.agents.config.jwt.name
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.jwt.cookie.name
  Introduced in Java Agent 5.6

Function

Profile

Type

String

Default

am-auth-jwt

Bootstrap property

Yes

Required property

No

Restart required

No

Local configuration file

AgentBootstrap.properties

AM console

Tab: Global

Title: JWT Cookie Name

Agent Profile Realm

The realm in which the agent profile is defined.

When Enable Policy Evaluation in User Authentication Realm is true, AM uses this realm to evaluate polices for policy decision requests from the agent.

Property name

org.forgerock.agents.agent.profile.realm

Aliases

org.forgerock.agents.agent.profile.realm
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.organization.name
  Introduced in Java Agent 5.0

Function

Profile, Required

Type

String

Default

/

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Exchanged SSO Token Cache TTL

The interval in minutes at which entries in the SSO token exchange cache timeout and are purged.

The exchanged JWT is cached against the relevant SSO token. If the same SSO token is presented again, before the cache entry expires, the agent does not need to exchange the token again, but retrieves the one stored in its cache.

Because exchanging SSO tokens for JWTs is an expensive process, previously exchanged SSO tokens are cached. When an entity is unable to permanently store its JWT in a cookie, calls to AM can be avoided.

Property name

org.forgerock.agents.sso.exchange.cache.ttl.minutes

Aliases

org.forgerock.agents.sso.exchange.cache.ttl.minutes
  Introduced in Java Agent 5.6.2.1
  Recognized from AM 7

Function

Profile

Type

Integer

Default

5

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced (from AM 7)

Title: Exchanged SSO Token Cache TTL

Legacy title: Exchanged SSO Token Cache Time to Live

Configuration Reload Interval

When the Location of Agent Configuration Repository is LOCAL, this is the number of seconds after which the agent reloads its configuration if it has been changed since it was last read.

Property name

org.forgerock.agents.config.reload.seconds

Aliases

com.sun.identity.agents.config.load.interval
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.config.reload.seconds
  Introduced in Java Agent 5.6

Function

Profile

Type

Integer

Default

0

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: Configuration Reload Interval

Agent Profile Name

The profile name used to fetch agent configuration data from AM, to evaluate policies for users, retrieve session info, and so on.

Default: Empty

Property name

org.forgerock.agents.profile.name

Aliases

com.sun.identity.agents.app.username
  Introduced in Java Agent 5.0

com.sun.identity.agents.config.profilename
  Introduced in Java Agent 5.0

org.forgerock.agents.profile.name
  Introduced in Java Agent 5.6

Function

Profile, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Enable Configuration Lock

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

Property name

org.forgerock.agents.lock.config.enabled

Aliases

com.sun.identity.agents.config.lock.enable
  Introduced in Java Agent 5.0

org.forgerock.agents.lock.config.enabled
  Introduced in Java Agent 5.6

Function

Profile

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

Yes

Required property

No

Restart required

No

Local configuration file

AgentBootstrap.properties

Profile Attribute Map

Map the value of an AM profile attribute to one or more HTTP headers, HTTP cookies, or request attributes, depending on the value of Profile Attribute Fetch Mode.

  • Map key: The name of an AM profile attribute

  • Map value: The name of one or more HTTP headers, HTTP cookies, or request attributes

The user profile can be stored in LDAP or any other arbitrary data store

Consider the following points for HTTP cookies:

  • If an HTTP cookie with the mapped name does not exist, the agent creates it.

  • If an HTTP cookie with the mapped name already exists and the cookie value is different from the mapped value, the agent overwrites the cookie.

  • If an HTTP cookie with the mapped name already exists and the cookie value is the same as the mapped value, the agent does nothing.

  • If the profile attribute name (key) does not exist, the agent does not create the HTTP cookie.

  • The agent does not automatically clear cookies. To prevent a build up of cookies, consider adding them to the Reset Cookie List.

Consider the following points for HTTP headers:

  • If an HTTP header with the mapped name does not exist, the agent creates it.

  • If an HTTP header with the mapped name already exists, the agent does not overwrite it but simply appends information to the header.

  • If the profile attribute name (key) does not exist, the agent does not create the HTTP header.

  • When an HTTP header name is used in a request header, it is prefixed by HTTP_. The agent automatically changes lower case letters to upper case, and hyphens (-) to underscores (_). For example, CUSTOM-userid becomes HTTP_CUSTOM_USERID.

Format: profile attribute = HEADER-NAME(S), profile attribute = COOKIE-NAME(S), profile attribute = REQUEST-ATTRIBUTE(S)

Default: Empty

Examples:

In the following example, the AM response attribute uid is mapped to CUSTOM-User-Name: com.sun.identity.agents.config.response.attribute.mapping[uid]=Custom-User-Name

Example: [cn]=HEADER-1|HEADER-2

Property name

org.forgerock.agents.profile.attribute.map

Aliases

com.sun.identity.agents.config.profile.attribute.mapping
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.profile.attribute.map
  Introduced in Java Agent 5.6

Function

Profile

Type

Map

  • Keys: source response profile name

  • Values: one or more target response profile names

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Profile Attribute Map

Legacy title: Profile Attribute Mapping

Max Entries in SSO Exchange Cache

The maximum number of entries in the SSO exchange cache, used when SSO tokens are exchanged for JWTs.

When the maximum is reached, the oldest records are overwritten.

Property name

org.forgerock.agents.sso.exchange.cache.size

Aliases

org.forgerock.agents.sso.exchange.cache.size
  Introduced in Java Agent 5.6.2.1
  Recognized from AM 7

Function

Profile

Type

Integer

Default

100

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced (from AM 7)

Title: Max Entries in SSO Exchange Cache

Legacy title: Exchanged SSO Token Cache Size

Profile Attribute Fetch Mode

Map the name of an AM profile attribute specified in Profile Attribute Map as follows:

  • NONE: Do not map

  • HTTP_HEADER: Map the to the name of an HTTP profile header

  • HTTP_COOKIE: Map to the name of an HTTP cookie

  • REQUEST_ATTRIBUTE: Map to the name of an HTTP profile attribute

Property name

org.forgerock.agents.profile.attribute.fetch.mode

Aliases

com.sun.identity.agents.config.profile.attribute.fetch.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.profile.attribute.fetch.mode
  Introduced in Java Agent 5.6

Function

Attributes, Cookie reset, Profile

Supported settings

NONE

No AM attributes are mapped.

HTTP_HEADER

The named AM attributes are mapped to headers in the outgoing HTTP response.

REQUEST_ATTRIBUTE

The named AM attributes are mapped to request attributes in the outgoing HTTP response.

HTTP_COOKIE

The named AM attributes are mapped to cookies in the outgoing HTTP response.

Default

NONE

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Profile Attribute Fetch Mode

WebSocket Connection Interval

The interval in minutes at which WebSockets to AM are killed and reopened. This property helps ensure a balanced distribution of connections across the AM servers on the site.

Property name

org.forgerock.agents.balance.websocket.interval.minutes

Aliases

org.forgerock.openam.agents.config.balance.websocket.connection.interval.in.minutes
  Introduced in Java Agent 5.6
  Recognized from AM 6

org.forgerock.agents.balance.websocket.interval.minutes
  Introduced in Java Agent 5.6

Function

Profile

Type

Integer

Default

30

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: WebSocket Connection Interval

Query parameter

Regex Remove Query Parameters List for Policy Evaluation

A list of regular expressions the agent uses to match query parameters to be removed from the incoming URL for policy evaluation and caching purposes. The property has the following format, with no spaces between values:

[Domain[/path]]|parameter[,parameter…​]

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.regex.list[0]=myapp.example.com|b.*,gp(a|p|s),

org.forgerock.agents.unwanted.http.url.params.regex.list[1]=|.*

The following incoming URL request that matches a rule such as myapp.example.com/customers|,coun.*?:

http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456

It is 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.

Property name

org.forgerock.agents.unwanted.http.url.params.regex.list

Aliases

org.forgerock.agents.unwanted.http.url.params.regex.list
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.conditional.unwanted.http.url.params.regexp
  Introduced in Java Agent 5.6
  Recognized from AM 7

org.forgerock.agents.unwanted.http.url.params.regexp.list
  Introduced in Java Agent 5.6

Function

Query parameter

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Regex Remove Query Parameters List for Policy Evaluation

Legacy title: Regular Expression Remove Query Parameters

Remove Query Parameters List for Policy Evaluation

A list of query parameters to be removed from the incoming URL for policy evaluation and caching.

The property has the following format, with no spaces between values:

[Domain[/path]]|parameter[,parameter…​]

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. The following example would match both lang and any unnamed parameters: myapp.example.com/customers|,lang

  • 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|*

The following incoming URL request matches a rule such as myapp.example.com/customers|,lang:

http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456

It is 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.

Property name

org.forgerock.agents.unwanted.http.url.param.list

Aliases

org.forgerock.agents.unwanted.http.url.param.list
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.conditional.unwanted.http.url.params
  Introduced in Java Agent 5.6
  Recognized from AM 7

Function

Query parameter

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Remove Query Parameters List for Policy Evaluation

Legacy title: Remove Query Parameters

Regex Query Parameters List for Policy Evaluation

A list of regular expressions the agent uses to match query parameters, for policy evaluation and caching.

The property has the following format, with no spaces between values:

[Domain[/path]]|regexp[,regexp,…​]

Property name

org.forgerock.agents.wanted.http.url.params.regexp.list

Aliases

org.forgerock.agents.wanted.http.url.params.regexp.list
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.conditional.wanted.http.url.params.regexp
  Introduced in Java Agent 5.6
  Recognized from AM 7

org.forgerock.agents.wanted.http.url.params.regex.list
  Introduced in Java Agent 5.6

Function

Query parameter

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Regex Query Parameters List for Policy Evaluation

Query Parameter List for Policy Evaluation

A list of query parameters to be retained for policy evaluation and caching purposes. The property has the following format, with no spaces between values:

[Domain[/path]]|parameter[,parameter…​]

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 matches 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,

The following incoming URL request matches a rule such as myapp.example.com/customers|,lang:

http://myapp.example.com/customers?country=uk&=bristol&lang=en_GB&area=1343456

It is 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.

Property name

org.forgerock.agents.wanted.http.url.param.list

Aliases

org.forgerock.openam.agents.config.conditional.wanted.http.url.params
  Introduced in Java Agent 5.6
  Recognized from AM 7

org.forgerock.agents.wanted.http.url.param.list
  Introduced in Java Agent 5.6

Function

Query parameter

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Miscellaneous (from AM 7)

Title: Query Parameter List for Policy Evaluation

Legacy title: Retain Query Parameters

Required

AM Authentication Service Path

The path to the AM server.

Property name

org.forgerock.agents.am.path

Aliases

com.iplanet.am.services.deploymentDescriptor
  Introduced in Java Agent 5.0

org.forgerock.agents.am.path
  Introduced in Java Agent 5.6

Function

Authentication service, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Authentication Redirect URI

The URI the agent uses to process authentication requests.

When this property is not defined, the redirect URI is provided by AM.

When this property is defined and Location of Agent Configuration Repository is REMOTE, AM overwrites this property.

If OIDC authentication is being used, changing the value of this property while the agent is running prevents it from functioning. Restart the agent immediately after the value in AM is altered and the properties saved.

Property name

org.forgerock.agents.authn.redirect.uri

Aliases

org.forgerock.agents.authn.redirect.uri
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.cdsso.redirect.uri
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Cross-domain single sign-on, Required

Type

String

Bootstrap property

No

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentConfig.properties

AM console

Tab: SSO

Title: Authentication Redirect URI

Legacy title: CDSSO Redirect URI

Encryption Class

The name of the class used by the agent to implement encryption and decryption. The class must implement both com.iplanet.services.util.AMEncryption and com.iplanet.services.util.ConfigurableKey.

After changing this property, you must re-encrypt the agent profile password. For more information, refer to Encrypted Agent Password.

Property name

org.forgerock.agents.encryptor.classname

Aliases

org.forgerock.agents.encryptor.classname
  Introduced in Java Agent 5.0

com.iplanet.security.encryptor
  Introduced in Java Agent 5.0

Function

Encryption, Required

Type

Classname

Default

org.forgerock.openam.shared.security.crypto.AESWrapEncryption

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

No

Local configuration file

AgentBootstrap.properties

AM Authentication Service Protocol

The protocol used by the AM server. Set to one of the following values:

  • HTTP

  • HTTPS

Property name

org.forgerock.agents.am.protocol

Aliases

org.forgerock.agents.am.protocol
  Introduced in Java Agent 5.6

com.iplanet.am.server.protocol
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Authentication service, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: AM Services

Title: AM Authentication Service Protocol

Agent Profile Realm

The realm in which the agent profile is defined.

When Enable Policy Evaluation in User Authentication Realm is true, AM uses this realm to evaluate polices for policy decision requests from the agent.

Property name

org.forgerock.agents.agent.profile.realm

Aliases

org.forgerock.agents.agent.profile.realm
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.organization.name
  Introduced in Java Agent 5.0

Function

Profile, Required

Type

String

Default

/

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Encrypted Agent Password

The agent profile password, which must correspond to the value in AM.

Set this property to the encrypted value of the password, where the password is encrypted using the key in the property Encryption Key/Salt.

Use the following command to get the encrypted value of the password, where passwordFile contains only the password followed by a newline, and has the access permission 400:

$ ./agentadmin --encrypt agentInstance passwordFile

Default: Empty

Property name

org.forgerock.agents.encrypted.password

Aliases

com.iplanet.am.service.secret
  Introduced in Java Agent 5.0

org.forgerock.agents.encrypted.password
  Introduced in Java Agent 5.6

Function

Miscellaneous, Required

Type

String

Bootstrap property

No

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentPassword.properties

Location of Agent Configuration Repository

The location of the agent configuration.

Property name

org.forgerock.agents.config.location

Aliases

com.sun.identity.agents.config.repository.location
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.config.location
  Introduced in Java Agent 5.6

Function

Profile, Required

Supported settings

LOCAL

The agent configuration is read from AgentConfiguration.properties (only).

REMOTE

The agent configuration is downloaded from AM.

Default

REMOTE

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Global

Title: Location of Agent Configuration Repository

Agent Profile Name

The profile name used to fetch agent configuration data from AM, to evaluate policies for users, retrieve session info, and so on.

Default: Empty

Property name

org.forgerock.agents.profile.name

Aliases

com.sun.identity.agents.app.username
  Introduced in Java Agent 5.0

com.sun.identity.agents.config.profilename
  Introduced in Java Agent 5.0

org.forgerock.agents.profile.name
  Introduced in Java Agent 5.6

Function

Profile, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Autonomous mode

When true 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.

Property name

org.forgerock.agents.fallback.mode.enabled

Aliases

com.forgerock.agents.config.fallback.mode
  Introduced in Java Agent 5.9.0

org.forgerock.agents.fallback.mode.enabled
  Introduced in Java Agent 5.9.0

org.forgerock.agents.autonomous.mode.enabled
  Introduced in Java Agent 5.9.0

Function

Agent, Required

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM Authentication Service Host Name

The AM server host name.

Property name

org.forgerock.agents.am.hostname

Aliases

com.iplanet.am.server.host
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.am.hostname
  Introduced in Java Agent 5.6

Function

Authentication service, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: AM Services

Title: AM Authentication Service Host Name

AM Authentication Service Port

The AM server port number.

Property name

org.forgerock.agents.am.port

Aliases

com.iplanet.am.server.port
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.am.port
  Introduced in Java Agent 5.6

Function

Authentication service, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: AM Services

Title: AM Authentication Service Port

Public AM URL

The assembled "public" URL of AM. This URL is used by the agent to redirect the user’s browser to AM for login (customised or not), or if necessary, exchange an SSO token for a JWT.

The following properties make up the URL:

The "private" URL is used by the agent for tasks such as establishing websockets, and obtaining authentication tokens or session information. The AM or load balancer instance can be behind a firewall to which the agent has access.

Define this property when public access to AM is restricted to a different URL from the private URL.

Property name

org.forgerock.agents.public.am.url

Aliases

com.forgerock.agents.public.am.url
  Introduced in Java Agent 5.6.3.0

org.forgerock.agents.public.am.url
  Introduced in Java Agent 5.6.3.0

Function

Miscellaneous, Required

Type

String

Bootstrap property

Yes

Required property

Yes - If this property is missing, the agent fails to start

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

Response

Response Attribute Map

Map the value of a response attribute specified in AM to one or more HTTP headers, HTTP cookies, or request attributes, depending on the value of Response Attribute Fetch Mode.

  • Map key: The name of a response attribute returned by AM with a policy decision

  • Map value: The name of one or more HTTP headers, HTTP cookies, or request attributes

Consider the following points for response cookies:

  • If an HTTP cookie with the mapped name does not exist, the agent creates it.

  • If an HTTP cookie with the mapped name already exists and the cookie value is different from the mapped value, the agent overwrites the cookie.

  • If an HTTP cookie with the mapped name already exists and the cookie value is the same as the mapped value, the agent does nothing.

  • If the profile attribute name (key) does not exist, the agent does not create the HTTP cookie.

  • The agent does not automatically clear cookies. To prevent a build up of cookies, consider adding them to the Reset Cookie List.

Consider the following points for response headers:

  • If an HTTP header with the mapped name does not exist, the agent creates it.

  • If an HTTP header with the mapped name already exists, the agent does not overwrite it but simply appends information to the HTTP header.

  • If the profile attribute name (key) does not exist, the agent does not create the HTTP header.

  • When an HTTP header name is used in a request header, it is prefixed by HTTP_. The agent automatically changes lower case letters to upper case, and hyphens (-) to underscores (_). For example, CUSTOM-userid becomes HTTP_CUSTOM_USERID.

Format: response attribute = HEADER-NAME(S), response attribute = COOKIE-NAME(S), response attribute = REQUEST-ATTRIBUTE(S)

Default: Empty

Examples:

In the following example, the AM response attribute uid is mapped to CUSTOM-User-Name: com.sun.identity.agents.config.response.attribute.mapping[uid]=Custom-User-Name

Example: [uid]=HEADER1|HEADER2

Property name

org.forgerock.agents.response.attribute.map

Aliases

org.forgerock.agents.response.attribute.map
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.response.attribute.mapping
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Response

Type

Map

  • Keys: source response attribute name

  • Values: one or more target response attribute names

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Response Attribute Map

Legacy title: Response Attribute Mapping

Response Attribute Fetch Mode

Map the name of an AM policy response attribute specified in Response Attribute Map as follows:

  • NONE: Do not map

  • HTTP_HEADER: Map the to the name of an HTTP response header

  • HTTP_COOKIE: Map to the name of an HTTP cookie

  • REQUEST_ATTRIBUTE: Map to the name of an HTTP request attribute

Property name

org.forgerock.agents.response.attribute.fetch.mode

Aliases

com.sun.identity.agents.config.response.attribute.fetch.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.response.attribute.fetch.mode
  Introduced in Java Agent 5.6

Function

Attributes, Response

Supported settings

NONE

No AM attributes are mapped.

HTTP_HEADER

The named AM attributes are mapped to headers in the outgoing HTTP response.

REQUEST_ATTRIBUTE

The named AM attributes are mapped to request attributes in the outgoing HTTP response.

HTTP_COOKIE

The named AM attributes are mapped to cookies in the outgoing HTTP response.

Default

NONE

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Response Attribute Fetch Mode

Enable SSO Token Acceptance

Set this property as follows:

  • true: Accept SSO tokens. Use this option when the agent and the token issuer are in the same domain, and for web applications and APIs where the backend accepts user information from SSO tokens.

  • false: Do not accept SSO tokens; require OIDC JWTs for authentication.

During session upgrade the format of the composite advice is as follows:

  • When both this property and Enable Custom Login Mode are true, the composite advice has the following format: ?authIndexType=composite_advice&authIndexValue=<Advices Value>

  • When either property is false, the composite advice has the following format: ?composite_advice=<Advices Value>

Property name

org.forgerock.agents.accept.sso.tokens.enabled

Aliases

org.forgerock.agents.accept.sso.tokens.enabled
  Introduced in Java Agent 5.7.1
  Recognized from AM 7.1

org.forgerock.agents.accept.sso.tokens
  Introduced in Java Agent 5.7.1

com.forgerock.agents.accept.sso.tokens
  Introduced in Java Agent 5.7.1

Function

Custom login redirect, Login redirect, SSO cookie handling

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7.1)

Title: Enable SSO Token Acceptance

Legacy title: Accept SSO Tokens

Convert SSO Tokens Into OIDC JWTs

For each incoming request, the agent looks for an OIDC JWT in the cookie named by JWT Cookie Name. Set this property as follows:

  • true: Use this value to allow users to access resources protected with systems that continue to use SSO tokens, and to use the default login redirection mode.

    • If the agent does not find a JWT in the cookie, the agent looks for an SSO token in the iPDP cookie defined during AM installation. During agent startup, the agent retrieves the name of this cookie from AM.

    • If the agent finds an SSO token in the iPDP cookie, it makes a request to AM to convert the SSO token into an OIDC JWT.

    • The agent caches the SSO token, so that if it is presented in another incoming request, the agent substitutes the JWT without making a request to AM.

    • If the agent does not find either token, authentication fails. The user can only access resources that are available through not-enforced rules.

  • false: Do not convert SSO tokens into OIDC JWTs.

Property name

org.forgerock.agents.accept.ipdp.cookie

Aliases

com.forgerock.agents.accept.ipdp.cookie
  Introduced in Java Agent 5.6
  Recognized from AM 7

org.forgerock.agents.accept.ipdp.cookie.enabled
  Introduced in Java Agent 5.7

org.forgerock.agents.exchange.ipdp.cookie.enabled
  Introduced in Java Agent 2024.9

Function

SSO cookie handling

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7)

Title: Convert SSO Tokens Into OIDC JWTs

Legacy title: Convert SSO Tokens into OpenID Connect JWTs

When the property Enable SSO Token Acceptance is true, a list of domains in which the agent attempts to create SSO cookies:

  • If the list is empty, the agent creates cookies only in its own domain.

  • If the agent is running behind a browser, it can create cookies only in its own domain.

  • If the agent is running behind a proxy, it should be able to create cookies in any required domains.

Default: Empty

Property name

org.forgerock.agents.ipdp.cookie.domain.list

Aliases

org.forgerock.agents.ipdp.cookie.domain.list
  Introduced in Java Agent 5.7.1
  Recognized from AM 7.1

Function

SSO cookie handling

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7.1)

Title: SSO Cookie Domain List

SameSite

When creating internal cookies, such as am-auth-jwt and the pre-authentication cookies, this property sets additional attributes by adding text into the Set-Cookie header.

Specify a key:value map, where the key is the cookie name, and the value is the string to add to the Set-Cookie header. If the key is omitted, the value becomes the default for all cookies.

Separate multiple values with a semicolon.

Examples:

  • Set the SameSite attribute of the am-auth-jwt cookie: org.forgerock.agents.set.cookie.internal.map[am-auth-jwt]=samesite=strict

  • Set the SameSite attribute of all cookies: org.forgerock.agents.set.cookie.internal.map=samesite=strict

  • Set several attributes of mycookie: org.forgerock.agents.set.cookie.internal.map[myCookie]=Max-Age=10000; Domain=.my.default.fqdn

Property name

org.forgerock.agents.set.cookie.internal.map

Aliases

org.forgerock.agents.set.cookie.internal.map
  Introduced in Java Agent 5.6.3.0
  Recognized from AM 7

Function

SameSite

Type

Map

  • Keys: Agent internal cookie name

  • Values: (samesite) text to be added to the Set-Cookie header

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7)

Title: Set-Cookie Internal Map

List of user agents excluded from receiving SameSite cookie attributes.

To specify different user agent patterns, add them in AM as custom properties, When user agent patterns are specified, the default list of user agents is ignored.

Property name

org.forgerock.agents.samesite.excluded.user.agents.list

Aliases

org.forgerock.agents.samesite.excluded.user.agents.list
  Introduced in Java Agent 5.6.3.0
  Recognized from AM 7

Function

SameSite

Type

List

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7)

Title: Exclude Agents From Samesite Cookie Attributes

Legacy title: Samesite Cookie Attributes Excluded User Agents Pattern List

When creating cookies with the AttributeTaskHandler, this property sets additional attributes by adding text into the Set-Cookie header.

Specify a key:value map, where the key is the cookie name, and the value the string to add to the the Set-Cookie header.

Separate multiple values with a semicolon.

Property name

org.forgerock.agents.set.cookie.attribute.map

Aliases

org.forgerock.agents.set.cookie.attribute.map
  Introduced in Java Agent 5.6.3.0
  Recognized from AM 7

Function

SameSite

Type

Map

  • Keys: Cookie name

  • Values: (samesite) text to be added to the Set-Cookie header

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: SSO (from AM 7)

Title: Set-Cookie Attribute Map

Session

Session Attribute Fetch Mode

Map the name of an AM session attribute specified in Session Attribute Map as follows:

  • NONE: Do not map

  • HTTP_HEADER: Map the to the name of an HTTP session header

  • HTTP_COOKIE: Map to the name of an HTTP cookie

  • REQUEST_ATTRIBUTE: Map to the name of an HTTP session attribute

When the value is HTTP_COOKIE, Cookie Reset is automatically set to true. Before redirecting the client for login, and when the client logs out, the agent resets profile and session attributes cookies, and cookies in the Reset Cookie List.

Property name

org.forgerock.agents.session.attribute.fetch.mode

Aliases

org.forgerock.agents.session.attribute.fetch.mode
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.session.attribute.fetch.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Attributes, Cookie reset, Session

Supported settings

NONE

No AM attributes are mapped.

HTTP_HEADER

The named AM attributes are mapped to headers in the outgoing HTTP response.

REQUEST_ATTRIBUTE

The named AM attributes are mapped to request attributes in the outgoing HTTP response.

HTTP_COOKIE

The named AM attributes are mapped to cookies in the outgoing HTTP response.

Default

NONE

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Session Attribute Fetch Mode

Session Attribute Map

Map the value of an AM session attribute to one or more HTTP headers, HTTP cookies, or request attributes, depending on the value of Session Attribute Fetch Mode. The session attribute is the attribute in the session to be fetched.

  • Map key: The name of an AM session attribute

  • Map value: The name of one or more HTTP headers, HTTP cookies, or request attributes

Consider the following points for HTTP cookies:

  • If an HTTP cookie with the mapped name does not exist, the agent creates it.

  • If an HTTP cookie with the mapped name already exists and the cookie value is different from the mapped value, the agent overwrites the cookie.

  • If an HTTP cookie with the mapped name already exists and the cookie value is the same as the mapped value, the agent does nothing.

  • If the profile attribute name (key) does not exist, the agent does not create the HTTP cookie.

  • The agent does not automatically clear cookies. To prevent a build up of cookies, consider adding them to the Reset Cookie List.

Consider the following points for HTTP headers:

  • If an HTTP header with the mapped name does not exist, the agent creates it.

  • If an HTTP header with the mapped name already exists, the agent does not overwrite it but simply appends information to the header.

  • If the profile attribute name (key) does not exist, the agent does not create the response header.

  • When an HTTP header name is used in a request header, it is prefixed by HTTP_. The agent automatically changes lower case letters to upper case, and hyphens (-) to underscores (_). For example, CUSTOM-userid becomes HTTP_CUSTOM_USERID.

Format: session attribute = HEADER-NAME(S), session attribute = COOKIE-NAME(S), session attribute = REQUEST-ATTRIBUTE(S)

Default: Empty

Examples:

In the following example, the AM response attribute uid is mapped to CUSTOM-User-Name: com.sun.identity.agents.config.response.attribute.mapping[uid]=Custom-User-Name

Example: [UserToken]=HEADER-1|HEADER-2

Property name

org.forgerock.agents.session.attribute.map

Aliases

org.forgerock.agents.session.attribute.map
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.session.attribute.mapping
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

Session

Type

Map

  • Keys: source session attribute name

  • Values: one or more target session attribute names

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Application

Title: Session Attribute Map

Legacy title: Session Attribute Mapping

Session Cache TTL

The interval in minutes at which entries in the session cache timeout and are purged.

If an entry is not cached, the agent must retrieve session information from AM. Therefore, by default the timeout is much longer than for the policy cache.

Property name

org.forgerock.agents.session.cache.ttl.minutes

Aliases

org.forgerock.agents.session.cache.ttl.minutes
  Introduced in Java Agent 5.6

org.forgerock.openam.agents.config.active.session.cache.ttl.minutes
  Introduced in Java Agent 5.0
  Recognized from AM 7

Function

Session

Type

Integer

Default

3

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced (from AM 7)

Title: Session Cache TTL

Max Entries in Expired Session Cache

The maximum number of entries in the expired session cache. When the maximum is reached, the oldest records are overwritten.

Property name

org.forgerock.agents.expired.session.cache.size

Aliases

org.forgerock.agents.expired.session.cache.size
  Introduced in Java Agent 5.7.1
  Recognized from AM 7.1

Function

Session

Type

Integer

Default

500

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced (from AM 7.1)

Title: Max Entries in Expired Session Cache

Legacy title: Expired Session Cache Max Records

Expired Session Cache Timeout

The interval in minutes at which entries in the expired session cache timeout and are purged.

The expired session cache records sessions that have been killed by AM. Use the cache to reduce network traffic and load on AM. When the agent receives a request using an invalidated token, it rejects the request without requesting session information from AM.

Property name

org.forgerock.agents.sso.expired.session.cache.ttl.minutes

Aliases

org.forgerock.agents.sso.expired.session.cache.ttl.minutes
  Introduced in Java Agent 5.7.1
  Recognized from AM 7.1

Function

Session

Type

Integer

Default

20

Bootstrap property

Yes

Required property

No

Restart required

Yes - Restart the container after changing the property

Local configuration file

AgentBootstrap.properties

AM console

Tab: Advanced (from AM 7.1)

Title: Expired Session Cache Timeout

Timeout

Websocket Idle Timeout

The idle timeout in milliseconds for WebSockets. If the connection is not active for this time, the agent pings AM to keep the WebSocket alive.

Property name

org.forgerock.agents.ping.websocket.after.inactive.milliseconds

Aliases

org.forgerock.agents.ping.websocket.after.inactive.milliseconds
  Introduced in Java Agent 5.8

Function

Timeout

Type

Integer

Default

20000

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

Websocket Expired Timeout

The allowed ping response time in milliseconds for WebSockets. If the WebSocket does not respond to a ping within this time, the agent closes the connection.

Property name

org.forgerock.agents.declare.websocket.dead.after.milliseconds

Aliases

org.forgerock.agents.declare.websocket.dead.after.milliseconds
  Introduced in Java Agent 5.8

Function

Timeout

Type

Integer

Default

40000

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

User mapping

User Attribute Name

When the property User Mapping Mode is HTTP_HEADER, this property is the name of the HTTP header attribute to identify the user. The named header must be present in the incoming headers.

Property name

org.forgerock.agents.user.mapping.mode.attribute.name

Aliases

com.sun.identity.agents.config.user.attribute.name
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.user.mapping.mode.attribute.name
  Introduced in Java Agent 5.6

Function

User mapping

Type

String

Default

employeenumber

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: User Attribute Name

User Mapping Mode

Specifies where to obtain the user ID

Property name

org.forgerock.agents.user.mapping.mode

Aliases

org.forgerock.agents.user.mapping.mode
  Introduced in Java Agent 5.6

com.sun.identity.agents.config.user.mapping.mode
  Introduced in Java Agent 5.0
  Recognized from AM 6

Function

User mapping

Supported settings

USER_ID

If "Enable User Principal Flag" (org.forgerock.agents.userid.mapping.mode.use.dn.enabled) is true, the user ID is set from the User Principal. Otherwise, the user ID is set from the user’s session property nominated by "User Session Name" (org.forgerock.agents.userid.mapping.mode.use.session.property.name).

PROFILE_ATTRIBUTE

The user ID is set to the value of a named profile attribute specified by "User Attribute Name" (org.forgerock.agents.user.mapping.mode.attribute.name).

HTTP_HEADER

The user ID is set to the value of the HTTP header specified by the "User Attribute Name" (org.forgerock.agents.user.mapping.mode.attribute.name).

SESSION_PROPERTY

The user ID is set to the value of the session property specified by the "User Attribute Name" (org.forgerock.agents.user.mapping.mode.attribute.name).

Default

USER_ID

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: User Mapping Mode

User Session Name

The user is identified by the value of this property when User Mapping Mode is USER_ID, and Enable User Principal Flag is false.

Property name

org.forgerock.agents.userid.mapping.mode.use.session.property.name

Aliases

com.sun.identity.agents.config.user.token
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.userid.mapping.mode.use.session.property.name
  Introduced in Java Agent 5.6

Function

User mapping

Type

String

Default

UserToken

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: User Session Name

Legacy title: User Token Name

Enable User Principal Flag

When the property User Mapping Mode is USER_ID, this flag indicates whether to identify the user through the user DN, as follows:

  • If true, the DN is taken from universalId, retrieved from the AM user session info.

  • If false, the user is identified by the the property User Session Name.

Property name

org.forgerock.agents.userid.mapping.mode.use.dn.enabled

Aliases

com.sun.identity.agents.config.user.principal
  Introduced in Java Agent 5.0
  Recognized from AM 6

org.forgerock.agents.userid.mapping.mode.use.dn.enabled
  Introduced in Java Agent 5.6

Function

User mapping

Type

Boolean: true returns true; all other strings return false.

Default

false

Bootstrap property

No

Required property

No

Restart required

No

Local configuration file

AgentConfig.properties

AM console

Tab: Global

Title: Enable User Principal Flag

Legacy title: User Principal Flag