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=threeThe 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
ssoadmcommand (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
2000in the Application tab of the AM console. -
When you use an unrecognized alias in an
ssoadmcommand (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=4000is 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]=threeproperty=one
property=two
property=threeWhen 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[]=threeproperty[10]=one
property[1]=two
property[42]=threeThe 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,threeThe 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[]=threeThe 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 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 |
|
Aliases |
|
Function |
Access denied |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Agent |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Agent, Required |
Type |
Boolean: |
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 |
|
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 |
|
Aliases |
|
Function |
Agent |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Agent |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Agent |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Agent |
Supported settings |
|
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Agent |
Supported settings |
|
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Attributes, Cookie reset, Session |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Cookie Separator Character
The separator for multiple values of the same attribute when it is set as a cookie.
Property name |
|
Aliases |
|
Function |
Attributes |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Fetch Attribute Date Format
The java.text.SimpleDateFormat of date attribute values used when an attribute is set in an HTTP header.
Property name |
|
Aliases |
|
Function |
Attributes |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Attributes, Response |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Attributes, Cookie reset, Profile |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Enable Attribute Encoding
When true, attribute values are URL-encoded before being set as a cookie.
Property name |
|
Aliases |
|
Function |
Attributes |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Audit |
Type |
String |
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Audit |
Type |
Boolean: |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Audit |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Audit |
Type |
List |
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Audit |
Type |
List |
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Audit |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: |
Audit Access Types
The type of messages to audit.
Property name |
|
Aliases |
|
Function |
Audit |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Audit |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Authentication failure |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Authentication failure |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Authentication failure |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Authentication failure |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
AM Authentication Service Path
The path to the AM server.
Property name |
|
Aliases |
|
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 |
|
AM Authentication Service Protocol
The protocol used by the AM server. Set to one of the following values:
-
HTTP
-
HTTPS
Property name |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Authentication service, Encryption |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM Authentication Service Host Name
The AM server host name.
Property name |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: |
AM Authentication Service Port
The AM server port number.
Property name |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Bad configuration detection |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Bad configuration detection |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Bad configuration detection |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Client identification, Continuous security |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Client identification |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Client identification |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Client identification, Continuous security |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Configure behaviour |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Configure behaviour |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Connection pooling |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: |
HTTP Connection Timeout
When Enable Connection Pooling is true, this property defines the connection timeout in seconds.
Property name |
|
Aliases |
|
Function |
Connection pooling |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: |
Enable HTTP Connection Reuse
When Enable Connection Pooling is true, this property enables connection reuse.
Property name |
|
Aliases |
|
Function |
Connection pooling |
Type |
Boolean: |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Connection pooling |
Type |
Boolean: |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Connection pooling |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
HTTP Socket Timeout
When Enable Connection Pooling is true, this property defines the socket timeout in seconds.
Property name |
|
Aliases |
|
Function |
Connection pooling |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
Enable HTTP Retry
When Enable Connection Pooling is true, this property enables retries after failed requests.
Property name |
|
Aliases |
|
Function |
Connection pooling |
Type |
Boolean: |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
Container Character Encoding
The character encoding used by the agent when encoding extended characters in the resource paths of not-enforced rules.
Property name |
|
Aliases |
|
Function |
Container, Not-enforced |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Container, Not-enforced |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
Continuous Security Cookie Map
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 |
|
Aliases |
|
Function |
Continuous security |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Continuous security |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Client identification, Continuous security |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Client identification, Continuous security |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Maximum Decompression Size
The maximum size, in bytes, a compressed cookie is allowed to expand to when decompressed.
Property name |
|
Aliases |
|
Function |
Cookie |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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.propertiesfile is less than 64-characters long.
Property name |
|
Aliases |
|
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 |
|
Max Age of Pre-Authentication Cookie
The maximum age in seconds of the pre-authentication cookie configured in Pre-Authentication Cookie Name.
Property name |
|
Aliases |
|
Function |
Cookie, Pre-authentication |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Load Balancer Cookie Name
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 |
|
Aliases |
|
Function |
Cookie |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Enable Encoded Cookies
When true, cookies are base64-encoded.
Property name |
|
Aliases |
|
Function |
Cookie |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Cookie |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Pre-Authentication Cookie Name
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%nbefore, in the middle of, or after a string. When the agent creates the cookie, it translates the string%ninto 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 |
|
Aliases |
|
Function |
Cookie, Pre-authentication |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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
%nbefore, in the middle, or after a string. When the agent creates the cookie, it substitutes%nfor 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 |
|
Aliases |
|
Function |
Cookie, POST data preservation |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Cookie |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Reset Cookie List
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 |
|
Aliases |
|
Function |
Cookie reset |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Attributes, Cookie reset, Session |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Cookie Reset
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 |
|
Aliases |
|
Function |
Cookie reset |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Reset Cookie Domain Map
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 |
|
Aliases |
|
Function |
Cookie reset |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Reset Cookie Path Map
Maps cookie name specified in Reset Cookie List to a path. After cookie reset, the cookie is used in the path.
Property name |
|
Aliases |
|
Function |
Cookie reset |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Attributes, Cookie reset, Profile |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Transmit Cookies Securely
When true, all cookies written by the agent are secure. For backward compatibility, the default is false.
Property name |
|
Aliases |
|
Function |
Cross-domain single sign-on |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
XSS Code Element List
Strings that, when found in the request, cause the agent to redirect the client to an error page.
Property name |
|
Aliases |
|
Function |
Cross-site scripting |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Cross-site scripting |
Type |
Map
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Custom login redirect, Login redirect, SSO cookie handling |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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¶m=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:
-
Header specification - a rule with a header specification is applied before other rules
-
Longest domain
-
Longest path
-
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.commatchesmydomain.example.comandwww.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.commatchestrue.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-localwith the valueprovidedare redirected to the default URL:org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|Requests containing a header called
X-localwith 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
sitewith the valueshoppingare redirected to the default URL:org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping|Requests containing a parameter called
target`with the value `cookingAND a parameter calledpricewith the valueloware 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.jsphttps://am.example.com:8443/openam/XUI/#login/https://am.example.com:8443/openam/customlogin/login.jspIf
[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¶m=value]-
One or more parameters to add to the login URL. Chain multiple parameters with an ampersand (&), for example,
realm=value¶meter1=value1¶meter2=value2.When the parameter is
?realm=valueit 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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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/authorizeendpoint. By default, this is the AM instance that is specified during installation. -
The
/oauth2/authorizeendpoint 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 |
|
Aliases |
|
Function |
Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default) |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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:
-
The goto parameter configured in Goto Parameter Name
-
A nonce parameter
Use the format URL[?realm=realm_name?parameter1=value1&…], where:
-
URL: URL of the login page to use for authentication -
[?realm=realm_name¶meter1=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.comlogs in the marketplace realm if the realm alias is set tomarketplace.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¶m1=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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Custom login redirect, Login redirect |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Legacy Login URL List
Adds parameters conditionally to legacy login URLs.
Format, with no spaces between values:
domain/path|url?param1=value1¶m2=value2
- Domain/path
-
The incoming request URL:
-
Domain: For example,
example.com. The agent must match the domain and its subdomains. For example,example.commatchesmydomain.example.comandwww.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.commatchestrue.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.jsphttps://am.example.com:8443/openam/XUI/#login/https://am.example.com:8443/openam/customlogin/login.jspIf 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 - ¶meter1=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¶meter1=value1¶meter2=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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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¶m=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:
-
Header specification - a rule with a header specification is applied before other rules
-
Longest domain
-
Longest path
-
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.commatchesmydomain.example.comandwww.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.commatchestrue.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-localwith the valueprovidedare redirected to the default URL:org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|Requests containing a header called
X-localwith 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
sitewith the valueshoppingare redirected to the default URL:org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping|Requests containing a parameter called
target`with the value `cookingAND a parameter calledpricewith the valueloware 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.jsphttps://am.example.com:8443/openam/XUI/#login/https://am.example.com:8443/openam/customlogin/login.jspIf
[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¶m=value]-
One or more parameters to add to the login URL. Chain multiple parameters with an ampersand (&), for example,
realm=value¶meter1=value1¶meter2=value2.When the parameter is
?realm=valueit 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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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/authorizeendpoint. By default, this is the AM instance that is specified during installation. -
The
/oauth2/authorizeendpoint 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 |
|
Aliases |
|
Function |
Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default) |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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:
-
The goto parameter configured in Goto Parameter Name
-
A nonce parameter
Use the format URL[?realm=realm_name?parameter1=value1&…], where:
-
URL: URL of the login page to use for authentication -
[?realm=realm_name¶meter1=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.comlogs in the marketplace realm if the realm alias is set tomarketplace.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¶m1=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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
Legacy Login URL List
Adds parameters conditionally to legacy login URLs.
Format, with no spaces between values:
domain/path|url?param1=value1¶m2=value2
- Domain/path
-
The incoming request URL:
-
Domain: For example,
example.com. The agent must match the domain and its subdomains. For example,example.commatchesmydomain.example.comandwww.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.commatchestrue.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.jsphttps://am.example.com:8443/openam/XUI/#login/https://am.example.com:8443/openam/customlogin/login.jspIf 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 - ¶meter1=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¶meter1=value1¶meter2=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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Deprecated |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Login Attempt Limit Cookie Name (deprecated)
The name of the cookie used to record the number of login attempts.
Property name |
|
Aliases |
|
Function |
Deprecated |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Deprecated |
Type |
String |
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Encryption, Required |
Type |
Classname |
Default |
|
Bootstrap property |
Yes |
Required property |
Yes - If this property is missing, the agent fails to start |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Authentication service, Encryption |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Fragment |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Fully qualified domain name |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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:
-
Searches map 1 for the incoming hostname. If there is a match, the agent redirects the request to the mapped value.
-
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.
-
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 |
|
Aliases |
|
Function |
Fully qualified domain name |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Fully qualified domain name |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Enable Prometheus Monitoring
When true, the agent will produce Prometheus monitoring output. When false, the agent will not produce any output.
Property name |
|
Aliases |
|
Function |
Global |
Type |
Boolean: |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
HTTP 302 Redirect Data
When Enable HTTP 302 Redirects, this property specifies the data to return instead of an HTTP 302 Redirect.
Property name |
|
Aliases |
|
Function |
Global |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Global |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Global |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Global |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Global |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Global |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Global |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Locale Country
The agent country. Changing this has no effect.
Property name |
|
Aliases |
|
Function |
Locale |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Locale Language
The agent language. Changing this has no effect.
Property name |
|
Aliases |
|
Function |
Locale |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Login |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Authentication Exchange Cookie Name
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 |
|
Aliases |
|
Function |
Login |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Login |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Login |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Login |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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¶m=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:
-
Header specification - a rule with a header specification is applied before other rules
-
Longest domain
-
Longest path
-
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.commatchesmydomain.example.comandwww.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.commatchestrue.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-localwith the valueprovidedare redirected to the default URL:org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|Requests containing a header called
X-localwith 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
sitewith the valueshoppingare redirected to the default URL:org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping|Requests containing a parameter called
target`with the value `cookingAND a parameter calledpricewith the valueloware 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.jsphttps://am.example.com:8443/openam/XUI/#login/https://am.example.com:8443/openam/customlogin/login.jspIf
[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¶m=value]-
One or more parameters to add to the login URL. Chain multiple parameters with an ampersand (&), for example,
realm=value¶meter1=value1¶meter2=value2.When the parameter is
?realm=valueit 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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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/authorizeendpoint. By default, this is the AM instance that is specified during installation. -
The
/oauth2/authorizeendpoint 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 |
|
Aliases |
|
Function |
Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default) |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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:
-
The goto parameter configured in Goto Parameter Name
-
A nonce parameter
Use the format URL[?realm=realm_name?parameter1=value1&…], where:
-
URL: URL of the login page to use for authentication -
[?realm=realm_name¶meter1=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.comlogs in the marketplace realm if the realm alias is set tomarketplace.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¶m1=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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
Legacy Login URL List
Adds parameters conditionally to legacy login URLs.
Format, with no spaces between values:
domain/path|url?param1=value1¶m2=value2
- Domain/path
-
The incoming request URL:
-
Domain: For example,
example.com. The agent must match the domain and its subdomains. For example,example.commatchesmydomain.example.comandwww.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.commatchestrue.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.jsphttps://am.example.com:8443/openam/XUI/#login/https://am.example.com:8443/openam/customlogin/login.jspIf 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 - ¶meter1=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¶meter1=value1¶meter2=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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Custom login redirect, Login redirect, SSO cookie handling |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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¶m=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:
-
Header specification - a rule with a header specification is applied before other rules
-
Longest domain
-
Longest path
-
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.commatchesmydomain.example.comandwww.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.commatchestrue.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-localwith the valueprovidedare redirected to the default URL:org.forgerock.agents.oauth.login.url.list[0]= X-local:provided|Requests containing a header called
X-localwith 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
sitewith the valueshoppingare redirected to the default URL:org.forgerock.agents.oauth.login.url.list[2]= ?site=shopping|Requests containing a parameter called
target`with the value `cookingAND a parameter calledpricewith the valueloware 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.jsphttps://am.example.com:8443/openam/XUI/#login/https://am.example.com:8443/openam/customlogin/login.jspIf
[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¶m=value]-
One or more parameters to add to the login URL. Chain multiple parameters with an ampersand (&), for example,
realm=value¶meter1=value1¶meter2=value2.When the parameter is
?realm=valueit 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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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/authorizeendpoint. By default, this is the AM instance that is specified during installation. -
The
/oauth2/authorizeendpoint 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 |
|
Aliases |
|
Function |
Custom login redirect, Default Login Redirect, Login redirect, Login Redirect (Default) |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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:
-
The goto parameter configured in Goto Parameter Name
-
A nonce parameter
Use the format URL[?realm=realm_name?parameter1=value1&…], where:
-
URL: URL of the login page to use for authentication -
[?realm=realm_name¶meter1=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.comlogs in the marketplace realm if the realm alias is set tomarketplace.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¶m1=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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Custom login redirect, Login redirect |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Legacy Login URL List
Adds parameters conditionally to legacy login URLs.
Format, with no spaces between values:
domain/path|url?param1=value1¶m2=value2
- Domain/path
-
The incoming request URL:
-
Domain: For example,
example.com. The agent must match the domain and its subdomains. For example,example.commatchesmydomain.example.comandwww.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.commatchestrue.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.jsphttps://am.example.com:8443/openam/XUI/#login/https://am.example.com:8443/openam/customlogin/login.jspIf 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 - ¶meter1=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¶meter1=value1¶meter2=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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Logout |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Logout |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Logout |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
Enable Logout Introspection
When true, the agent checks the HTTP request body to locate the value of Logout Request Parameter Map.
Property name |
|
Aliases |
|
Function |
Logout |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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¶m2=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 |
|
Aliases |
|
Function |
Logout |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Logout |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Logs |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Redirect Attempt Cookie Name
The cookie name to use to detect redirect loops while authenticating, which would indicate a cookie domain problem.
Property name |
|
Aliases |
|
Function |
Miscellaneous |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
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 |
|
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 |
|
Aliases |
|
Function |
Miscellaneous |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Miscellaneous |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Miscellaneous |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Miscellaneous |
Type |
Classname |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Miscellaneous |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
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 |
|
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 |
|
Aliases |
|
Function |
Monitoring |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Monitoring |
Type |
String |
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
Boolean: |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Container Character Encoding
The character encoding used by the agent when encoding extended characters in the resource paths of not-enforced rules.
Property name |
|
Aliases |
|
Function |
Container, Not-enforced |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
Classname |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Not-enforced |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Container, Not-enforced |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Notifications |
Type |
Boolean: |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Deprecated in |
|
Aliases |
|
Function |
Notifications |
Type |
Boolean: |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
Enable Notification of Policy Changes
Flag to indicate whether the agent subscribes to WebSocket notifications from AM for policy changes.
Property name |
|
Aliases |
|
Function |
Notifications |
Type |
Boolean: |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Enable Notification of Session Logout
Flag to indicate whether the agent subscribes to WebSocket notifications from AM for session logout.
Default: true
Property name |
|
Aliases |
|
Function |
Notifications |
Type |
Boolean: |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
POST data preservation |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
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 |
|
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 |
|
Aliases |
|
Function |
POST data preservation |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
POST Data Preservation Cache TTL
The interval in minutes at which entries in the POST data preservation cache timeout and are purged.
If this property and POST Data Preservation Cache TTL in Milliseconds (deprecated) are set, POST Data Preservation Cache TTL in Milliseconds (deprecated) takes precedence.
Property name |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
POST data preservation |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
POST Data Preservation Sticky Session Mode
Property name |
|
Aliases |
|
Function |
POST data preservation |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
POST data preservation |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
POST data preservation |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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.propertiesfile is less than 64-characters long.
Property name |
|
Aliases |
|
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 |
|
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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
POST data preservation |
Type |
String |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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
%nbefore, in the middle, or after a string. When the agent creates the cookie, it substitutes%nfor 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 |
|
Aliases |
|
Function |
Cookie, POST data preservation |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Deprecated in |
|
Aliases |
|
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 |
|
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 |
|
Aliases |
|
Function |
Policy enforcement |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Policy enforcement |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Restrict to Realm Map
A map to restrict access to the specified web application to users authenticated in the specified realm.
Property name |
|
Aliases |
|
Function |
Policy enforcement |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Policy enforcement |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Policy enforcement |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Policy enforcement |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Policy enforcement |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Policy Cache TTL
The interval in minutes at which entries in the policy cache time out and are purged.
Property name |
|
Aliases |
|
Function |
Policy enforcement |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Policy enforcement |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Policy enforcement |
Type |
Map
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Policy enforcement |
Type |
Map
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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.propertiesfile is less than 64-characters long.
Property name |
|
Aliases |
|
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 |
|
Max Age of Pre-Authentication Cookie
The maximum age in seconds of the pre-authentication cookie configured in Pre-Authentication Cookie Name.
Property name |
|
Aliases |
|
Function |
Cookie, Pre-authentication |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Pre-Authentication Cookie Name
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%nbefore, in the middle of, or after a string. When the agent creates the cookie, it translates the string%ninto 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 |
|
Aliases |
|
Function |
Cookie, Pre-authentication |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Location of Agent Configuration Repository
The location of the agent configuration.
Property name |
|
Aliases |
|
Function |
Profile, Required |
Supported settings |
|
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 |
|
AM console |
Tab: Title: |
JWT Cookie Domain List
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 |
|
Aliases |
|
Function |
Profile |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Profile |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: |
Max Entries in JWT Cache
The maximum number of entries in the JWT cache.
Property name |
|
Aliases |
|
Function |
Profile |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
JWT Cookie Name
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 |
|
Aliases |
|
Function |
Profile |
Type |
String |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
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 |
|
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 |
|
Aliases |
|
Function |
Profile |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Profile |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
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 |
|
Enable Configuration Lock
When true, an agent restart is required to allow configuration changes, even for hot-swappable parameters.
Property name |
|
Aliases |
|
Function |
Profile |
Type |
Boolean: |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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-useridbecomesHTTP_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 |
|
Aliases |
|
Function |
Profile |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Profile |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Attributes, Cookie reset, Profile |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Profile |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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|,langwould match bothlangand 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 |
|
Aliases |
|
Function |
Query parameter |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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
langand 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 |
|
Aliases |
|
Function |
Query parameter |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Query parameter |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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|,langmatches bothlangand 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 |
|
Aliases |
|
Function |
Query parameter |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
AM Authentication Service Path
The path to the AM server.
Property name |
|
Aliases |
|
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 |
|
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 |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Encryption, Required |
Type |
Classname |
Default |
|
Bootstrap property |
Yes |
Required property |
Yes - If this property is missing, the agent fails to start |
Restart required |
No |
Local configuration file |
|
AM Authentication Service Protocol
The protocol used by the AM server. Set to one of the following values:
-
HTTP
-
HTTPS
Property name |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
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 |
|
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 |
|
Aliases |
|
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 |
|
Location of Agent Configuration Repository
The location of the agent configuration.
Property name |
|
Aliases |
|
Function |
Profile, Required |
Supported settings |
|
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 |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
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 |
|
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 |
|
Aliases |
|
Function |
Agent, Required |
Type |
Boolean: |
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 |
|
AM Authentication Service Host Name
The AM server host name.
Property name |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: |
AM Authentication Service Port
The AM server port number.
Property name |
|
Aliases |
|
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 |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
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 |
|
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-useridbecomesHTTP_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 |
|
Aliases |
|
Function |
Response |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Attributes, Response |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Custom login redirect, Login redirect, SSO cookie handling |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
SSO cookie handling |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
SSO Cookie Domain List
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 |
|
Aliases |
|
Function |
SSO cookie handling |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Set-Cookie Internal Map
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
SameSiteattribute of theam-auth-jwtcookie:org.forgerock.agents.set.cookie.internal.map[am-auth-jwt]=samesite=strict -
Set the
SameSiteattribute 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 |
|
Aliases |
|
Function |
SameSite |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
Exclude Agents From Samesite Cookie Attributes
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 |
|
Aliases |
|
Function |
SameSite |
Type |
List |
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
Set-Cookie Attribute Map
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 |
|
Aliases |
|
Function |
SameSite |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Attributes, Cookie reset, Session |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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-useridbecomesHTTP_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 |
|
Aliases |
|
Function |
Session |
Type |
Map
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Session |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Session |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
Session |
Type |
Integer |
Default |
|
Bootstrap property |
Yes |
Required property |
No |
Restart required |
Yes - Restart the container after changing the property |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
Timeout |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
Timeout |
Type |
Integer |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
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 |
|
Aliases |
|
Function |
User mapping |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
User Mapping Mode
Specifies where to obtain the user ID
Property name |
|
Aliases |
|
Function |
User mapping |
Supported settings |
|
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: |
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 |
|
Aliases |
|
Function |
User mapping |
Type |
String |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |
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 |
|
Aliases |
|
Function |
User mapping |
Type |
Boolean: |
Default |
|
Bootstrap property |
No |
Required property |
No |
Restart required |
No |
Local configuration file |
|
AM console |
Tab: Title: Legacy title: |