This reference covers agent configuration properties.

When you create the 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 of a standard Java properties file.

A flag for whether to based64 URL-encode composite advices before sending them to custom login endpoints:

true: Advices are encoded to increase the security, and protect against cross-site scripting attacks.

false: Advices are not encoded

This property requires AM 6.0.1, 6.5.3, and later versions

Not available in the console for AM 6.0.x.

Default: false

When true, the agent sends composite advice in the query (GET request) instead of sending it through a POST request.

Not available in the console for AM 6.0.x.

Default: false

Enable or disable REMOTE_USER processing for anonymous users.

Default: false

Separator for multiple values. Applies to all types of attributes, such as profile, session, and response attributes.

Default: |

When set to HTTP_COOKIE or HTTP_HEADER, profile attributes are introduced into the cookie or the headers, respectively.

Default: NONE

Map of session attribute to HTTP headers:

To map the value of the session attribute UserToken to the HTTP header CUSTOM-userid, configure com.sun.identity.agents.config.session.attribute.mapping[UserToken]=CUSTOM-userid.

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

Format: session attribute = HEADER_NAME(S)

Example: [UserToken]=HEADER1|HEADER2

Default: Empty

Maps a policy response attribute to one or more HTTP headers for the authenticated user:

To populate the value of response attribute uid under CUSTOM-User-Name, enter uid in the key field, and CUSTOM-User-Name in the corresponding value field, com.sun.identity.agents.config.response.attribute.mapping[uid]=Custom-User-Name.

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

Format: response attribute = HEADER_NAME(S)

Example: [uid]=HEADER1|HEADER2

Default: Empty

When set to HTTP_COOKIE or HTTP_HEADER, response attributes are introduced into the cookie or the headers, respectively.

Default: NONE

When set to HTTP_COOKIE or HTTP_HEADER, session attributes are introduced into the cookie or the headers, respectively.

Default: NONE

Maps a profile attribute to one or more HTTP headers for the authenticated user:

To populate the value of profile attribute CN under CUSTOM-Common-Name, configure com.sun.identity.agents.config.profile.attribute.mapping[CN]=CUSTOM-Common-Name.

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

Format: profile attribute = HEADER_NAME(S)

Example: [CN]=HEADER1|HEADER2

Default: Empty

The maximum size in bytes of the local audit log files. The agent rotates audit log files when they reach this size, and stores rotated files with a timestamp.

Default: 52428800

The type of audit events to log:

Default: LOG_NONE

When true, enable rotation of local audit log files.

Use Local Audit Log Rotation Size as an alternative to this deprecated property.

Default: true

The location where the agent logs audit messages:

Default: REMOTE

If log location is LOCAL or ALL, this property gives the name of the local file that contains agent audit messages.

Default: /web_agents/agent_type/instances/agent_nnn/logs/audit/audit.log

Name of the HTTP header that holds the hostname of the client.

Default: Empty

Name of the HTTP header that holds the IP address of the client.

Default: Empty

Map of cookie values to entries in the environmental conditions map, used during policy evaluation:

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

Example:

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

Default: Empty

Map of header values to entries in the environmental conditions map, used during policy evaluation:

Example:

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

Default: Empty

A flag for whether the agent accepts SSO tokens and ID tokens as session cookies:

The SSO token name is given by Cookie Name.

If the agent receives a request with both an SSO token and an ID token, it checks the ID token first. If invalid, it checks the SSO token. If both are invalid, the agent redirects the user for authentication.

The agent caches session information for SSO tokens.

Configure this property with Enable Custom Login Mode, as described in Login Redirect Configuration Options.

This property requires AM 6 or later versions.

Default: 0

A flag to persist JWT cookies. If true the JWT cookie is not set as a Session Cookie.

Default: false

When true, the agent marks cookies as secure, sending them only if the communication channel is secure. Set to true when agent connections are over SSL.

Default: false

Sets the SameSite attribute on all the cookies that it creates. The value of the SameSite attribute is what you configure in this property.

For example, to add the SameSite attribute with the value of Lax to the cookies, set this property to Lax.

The attribute is not set for some browsers and circumstances, as described in https://www.chromium.org/updates/same-site/incompatible-clients.

Default: Empty

List of cookies to reset. For example:

com.sun.identity.agents.config.cookie.reset[0]=myCookie

com.sun.identity.agents.config.cookie.reset[1]=nextCookie

Default: Empty

When true, use URL encoding for special characters in cookies. This is useful when profile, session, and response attributes contain special characters, and the attributes fetch mode is set to HTTP_COOKIE.

Default: false

Web agent uses the pre-authentication cookie agent-authn-tx to track the progress of authentication with AM and protect the request from replay attacks.

When this property is true, 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.

When this property is false, the agent creates a pre-authentication cookie for each authentication request to AM, with the name of agent-authn-tx-string.

In some environments, this will create 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 and have a limit of how many cookies they can handle.

Something similar happens to web servers; they have a limit of how many headers (cookies) they can manage at one time. Set the property to true if you find that creating too many cookies is having an impact on your environment.

Default: false

A prefix for the cookie attributes headers.

Default: HTTP_

Name of the SSO token cookie used for authentication with AM. If empty, the agent retrieves the cookie name from the AM server.

Default: iPlanetDirectoryPro

Number of seconds before expiration of custom cookies or the pre-authentication cookie, agent-authn-tx.

Pre-authentication cookies expire when the first of the following events occurs:

If POST data preservation is enabled, the request expires after the time specified in POST Data Entries Cache Period, which is by default 10 minutes. In this case, consider increasing the value of this property to at least 600 seconds.

Default: 300

When true, mark cookies as HttpOnly to prevent scripts and third-party software from accessing them.

Default: true

When true, the agent resets (blanks) cookies in the response before redirecting to authentication by issuing a Set-Cookie header to the client. An example header could be similar to this:

Set-Cookie myCookie= ; Max-Age=0; Expires=Thu, 01-Jan-1970 00:00:00 GMT; Domain=.my.default.fqdn

If FQDN Default is set, the agent sets the cookie domain to the domain specified by the property. Otherwise, the agent leaves the cookie domain blank.

Default: false

Flag to reset the session cookie after an authentication redirect:

true: The agent does not reset the session cookie if a policy advice is present.

false: The agent resets the session cookie in all configured domains on every authentication redirect when a policy advice is present.

Default: false

Renames the endpoint the agent uses to process CDSSO requests. The name you choose for a production environment should not give away its purpose to end users.

The agent uses this endpoint during the default login redirection flow, but not during the custom login redirection flow.

Default: agent/cdsso-oauth2

List of domains, such as .example.com, in which cookies have to be set in CDSSO. If this property empty, then the fully qualified domain name of the cookie for the agent server is used to set the cookie domain, meaning that a host cookie rather than a domain cookie is set.

To set the list to .example.com, and .example.net using the configuration file property, include the following:

com.sun.identity.agents.config.cdsso.cookie.domain[0]=.example.com

com.sun.identity.agents.config.cdsso.cookie.domain[1]=.example.net

Default: Empty

Additional properties to augment the set of properties supported by agent. Custom properties can be specified as follows:

Add any property that is not yet in the AM console as a custom property.

A flag to validate the certificate presented during SSL handshakes by the container where AM runs:

Default: true

When AM is configured for client-side certificate verification, set this property to the file that contains the client certificate private key.

Agents using OpenSSL must specify the private key as a PEM file. For example: com.forgerock.agents.config.cert.key = /opt/certificates/client_key.pem

Agents using the Windows built-in Secure Channel API should not configure this property.

Default: Empty

A colon separated list of one or more ciphers to support, as defined in http://www.openssl.org/docs/apps/ciphers.html.

A flag to accept secure cookies.

When true, the agent accepts secure cookies from AM over HTTP. When false, the agent rejects them.

For requests that arrive over a secure channel, by default, AM upgrades cookies to secure. However, during internal communication with the agent, AM can send these secure cookies over HTTP.

Default: false

When AM is configured to perform client certificate validation, set this property to the name of the file that contains the client certificate chain.

Agents using OpenSSL libraries must specify the certificate chain as a PEM file. For example: com.forgerock.agents.config.cert.file = /opt/certificates/pub_client.pem

Agents using the Windows built-in Secure Channel API must choose one of the following options:

Default: Empty

When the agent is configured to validate server certificates (Server Certificate Trust is false), set this property to the file name that contains a certificate or chain of certificates.

The file should be PEM encoded. For example:

com.forgerock.agents.config.cert.ca.file = /opt/certificates/openam_ca.pem

com.sun.identity.agents.config.trust.server.certs = false

Set this property only when the agent is using OpenSSL libraries. For agent using the Windows built-in Secure Channel API, add the appropriate certificates to the Windows certificate store.

Default: Empty

When AM is configured for client-side certificate verification, and the PEM file containing the client certificate private key is password-protected, set this property to the obfuscated password.

Obfuscate the password by using agentadmin --p command. For example:

$ /web_agents/agent-type/bin> ./agentadmin --p "Encryption Key" "cat cert_password.file"

Encrypted password value: zck+6RKqjtc=

Where Encryption Key is the value of Agent Profile Password Encryption Key.

Default: Empty

Flag for whether Windows-based agents use the Windows built-in Secure Channel API or OpenSSL to secure internal communication with AM:

Default: false

(OpenSSL only) Specifies how deeply the agent verifies AM’s server certificate before deciding the certificate is not valid.

The depth is the maximum number of CA certificates that are followed while verifying the server certificate. If the certificate chain is longer than allowed, the certificates above the limit are ignored.

The property accepts the following values:

This property is relevant only when server certificate validation is enabled (Server Certificate Trust is false).

Default: 9

Map of invalid or virtual name keys to valid FQDN values:

This property enables virtual hosts, partial hostname, and IP address to access protected resources. Use this property so the agent can properly redirect users, and the agents receive cookies belonging to the domain.

To map a virtual server virtual.example.com to real.mydomain.example, enter the following:

This corresponds to com.sun.identity.agents.config.fqdn.mapping[valid1]=virtual.example.com.

To map myserver to myserver.mydomain.example, enter the following:

This corresponds to com.sun.identity.agents.config.fqdn.mapping[myserver]=myserver.mydomain.example.

When true, enable checking of FQDN default value and FQDN map values.

The FQDN that the users should use in order to access resources. Without this value, the web server can fail to start. Set this property on agent installation, and change it only if absolutely necessary.

This property ensures that when users access protected resources on the web server without specifying the FQDN, the agent can redirect the users to URLs containing the correct FQDN.

When AM and the agent communicate through a web proxy server configured in forward proxy mode, and the proxy server has the agent authenticate using Basic Authentication, set this property to the agent’s password.

Default: Empty

When AM and the agent communicate through a web proxy server configured in forward proxy mode, set this property to the proxy server port number.

Default: Empty

When AM and the agent communicate through a web proxy server configured in forward proxy mode, and the proxy server has the agent authenticate using Basic Authentication, set this property to the agent’s user name.

Default: Empty

When AM and the agent communicate through a web proxy server configured in forward proxy mode, set this property to the proxy server host name.

Default: Empty

A flag to manage the browser’s URL fragment during authentication, as follows:

An extra redirect is incurred for all unauthenticated requests, to capture and process the URL fragment.

Fragment redirect is not possible for request URLs marked for JSON responses, usually for non-browser clients, such as JavaScript or other coded clients.

Default: false

Debug level. Set to one of:

Default: Error

The local file in which the agent writes debug log messages after startup.

During agent startup the location of the logs can be based on the container which is being used, or defined in the site configuration file for the server. For example, bootstrap logs for NGINX Plus Web Agent can be written to /var/log/nginx/error.log.

Default: /web_agents/agent_type/instances/agent_nnn/logs/debug/debug.log

A flag to enable SSO only mode:

Default: false

File size in bytes at which the debug log file is rotated. The minimum is 5242880 bytes (5 MB), and lower values are reset to 5 MB. AM sets a default of 10000000 bytes (approximately 10 MB).

Default: 10000000

A flag for whether an agent configured in SSO-only mode should refresh the user’s session idle time when the user accesses a protected resource.

AM sessions have an idle timeout after which they expire. When users access protected resources through an agent, the agent requests a policy decision on behalf of that user, which resets the idle timeout.

If the agent is configured in SSO-only mode, the session may unexpectedly expire in AM due to idle timeout before the user has finished accessing the application.

Set this property to true to refresh the timeout when the user performs an action.

When set to true, the agent makes an additional call to AM; this may cause a performance impact. Configure this property only if:

Default: false

The URL of the customized access denied page. If empty, the agent returns an HTTP status of 403 (Forbidden). The URL can be absolute or relative.

The following values are not permitted:

Default: Empty

Renames the goto parameter. The agent appends the requested URL to the renamed parameter during redirection, after logout or after reaching an access denied page. Rename the parameter when your application requires a parameter other than goto.

Consider the following example: com.sun.identity.agents.config.redirect.param=goto2

A valid redirection URL using the goto2 parameter may look similar to the following: 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. Note that you configure the access denied page using Resources Access Denied URL.

This property also affects AM Logout URL.

Default: goto

When true, strip path info from the request URL while doing the Not-Enforced List check, and URL policy evaluation. This is designed to prevent a user from accessing a URI by appending the matching pattern in the policy or not-enforced list.

For example, if the not-enforced list includes http://host/*.gif, then stripping path info from the request URI prevents access to http://host/index.html by using http://host/index.html?hack.gif.

However, when a web server is configured as a reverse proxy for a Java application server, the path info is interpreted to map a resource on the proxy server rather than the application server. This prevents the not-enforced list or the policy from being applied to the part of the URI below the application server path if a wildcard character is used.

For example, if the not-enforced list includes http://host/webapp/servcontext/* and the request URL is http://host/webapp/servcontext/example.jsp, the path info is /servcontext/example.jsp and the resulting request URL with path info stripped is http://host/webapp/, which does not match the not-enforced list. Thus when this property is enabled, path info is not stripped from the request URL even if there is a wildcard in the not-enforced list or policy.

When this property is true, make sure that nothing follows the wildcard in the not-enforced list or policy.

Default: false

A list of resource URLs that trigger a JSON-formatted response from the agent, and, optionally, override the default HTTP status code.

Use this property for non-browser-based, or AJAX applications, that do not want to redirect users to the AM user interface for authentication.

Example:

org.forgerock.agents.config.json.url[0]=http*://.example.com:/api/*

org.forgerock.agents.config.json.response.code=202

Performing a GET operation that matches the example triggers an HTTP result code 202 Accepted, and a JSON response containing 302 Found.

Default: Empty

When true, the values specified in the following properties do not trigger JSON-formatted responses:

Only non-specified values trigger JSON-formatted responses.

Default: false

Specify HTTP headers and associated values that trigger JSON-formatted errors to be returned.

Use with HTTP Return Code for JSON-Formatted Responses, as follows:

org.forgerock.agents.config.json.header[enableJsonResponse]=true

org.forgerock.agents.config.json.response.code=202

Performing a GET operation that matches the example triggers an HTTP result code 202 Accepted, and a JSON response containing 302 Found.

Default: Empty

An HTTP response code to return when a JSON-formatted error is triggered.

Example:

org.forgerock.agents.config.json.url[0]=http*://.example.com:/api/*

org.forgerock.agents.config.json.response.code=202

Performing a GET operation that matches the example triggers an HTTP result code 202 Accepted, and a JSON response containing 302 Found.

Default: Empty

Enable if the agent is behind a SSL/TLS off-loader, load balancer, or proxy, where the users and the agent use a different host. When true, the host is overridden with the value from Agent Deployment URI Prefix.

When the following headers are defined on the proxy or load-balancer, they override the value of Agent Deployment URI Prefix:

If you are using these headers, do not configure the agent to override its hostname, port, or protocol.

Default: false

Enable if the agent is behind a SSL/TLS off-loader, load balancer, or proxy, where the users and the agent use a different port. When true, the port is overridden with the value from Agent Deployment URI Prefix.

When the following headers are defined on the proxy or load-balancer, they override the value of Agent Deployment URI Prefix:

If you are using these headers, do not configure the agent to override its hostname, port, or protocol.

Default: false

Enable if the agent is behind a SSL/TLS off-loader, load balancer, or proxy, where the users and the agent use a different protocol. When true, the protocol is overridden with the value from Agent Deployment URI Prefix.

When the following headers are defined on the proxy or load-balancer, they override the value of Agent Deployment URI Prefix:

If you are using these headers, do not configure the agent to override its hostname, port, or protocol.

Default: false

A key-value pair separated by the equals (=) character that the agent creates when evaluating POST Data Sticky Load Balancing Mode.

For example, a setting of lb=myserver either sets an lb cookie with myserver value, or adds lb=myserver to the URL query string.

Default: Empty

When true, the agent passes the hardcoded amlbcookie to AM.

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

Default: false

Whether to create a cookie, or to append a query string to the URL to assist with sticky load balancing:

Default: Empty

This property is not used by the agent. Use POST Data Sticky Load Balancing Value instead.

Conditionally redirect users based on the incoming request URL.

If the incoming request URL matches a domain name in this list, the agent redirects the unauthenticated request to the specified URL for login. The URL can be an AM instance, site, or a different website.

Format, with no spaces between values:

[String]|[URL, URL…​][?realm=value&module=value2&service=value3]

Examples:

com.forgerock.agents.conditional.login.url[0]=example.com|https://openam.example.com/openam/oauth2/authorize

com.forgerock.agents.conditional.login.url[1]=myapp.domain.com|https://openam2.example.com/openam/oauth2/authorize?realm=/sales

com.forgerock.agents.conditional.login.url[3]=sales.example.com/marketplace|https://openam1.example.com/openam/oauth2/authorize?realm=/sales, https://openam2.example.com/openam/oauth2/authorize?realm=/marketplace

com.forgerock.agents.conditional.login.url[4]=myapp.domain.com|http://mylogin.example.com?realm=/customers

com.forgerock.agents.conditional.login.url[5]=|https://openam3.example.com/openam/oauth2/authorize?realm=/customers&module=myAuthModule

For more information, see Login Redirects.

Conditionally redirect users based on the incoming request URL. If the incoming request URL matches a regular expression, the agent redirects the request to a specific URL. That specific URL can be an AM instance, site, or a different website.

This property specifies the redirection URL and its parameters. Configure this property in the same way as for AM Conditional Login URL, except do not specify the string or pipe (|) character.

This property relies on Regular Expression Conditional Login Pattern to specify the regular expression that the domain name must match.

Example:

org.forgerock.agents.config.conditional.login.pattern[0] = .*shop

org.forgerock.agents.config.conditional.login.url[0] = http://openam.example.com/openam/oauth2/authorize?realm=sales

Default: Empty

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

Use this property when both of the following points are true:

Consider an example where the traffic between AM and the agent happens through the example-internal.com domain, but the custom login pages are on the example-external.com domain. The traffic between the custom pages and AM translates am.example-internal.com into am.example-external.com. You would configure https://am.example-external.com:8443/openam as the public AM URL.

Not available in the console for AM 6.0.x.

Default: Empty

The URL of a custom login page to which the agent redirects users for authentication.

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

Specify as many parameters as your custom login pages require: https://login.example.com/login.jsp?realm=marketplace&param1=value1

You do not need to specify the realm in the login URL if any of the following conditions is true:

Even if you specify the realm by default, this parameter can be overwritten by the custom login page if, for example, the user can chose the realm for authentication.

Default: AMURL/openam/UI/Login

See Regular Expression Conditional Login URL.

Sets the login redirection mode, as follows:

Requires AM 6 or later.

Default: 0

During the logout flow and after logging out the user, this property specifies whether the agent should redirect the end user to another page. For example, to the landing page of the application, or to a login page:

true: Logout redirection is disabled - the agent does not perform the last redirection, and the web client is left on the logout page.

false: Logout redirection is enabled - the agent appends a goto parameter to the logout URL with the value of the Logout Redirect URL.

Default: true

One or more of application logout URLs, such as http://www.example.com/logout.html. The agent triggers a logout flow when the end user accesses one of these pages. Therefore, these pages must be handled by your web server.

Configure with the Logout Redirect URL or Agent Logout URL Regular Expression properties.

Default: Empty

A flag to allow regular expressions in Logout URL List.

Default: false