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.

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

Default: false

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

Default: false

The password required by the agent profile and encrypted with the key specified in Agent Profile Password Encryption Key.

This property is provided in the agent-password.conf file.

To encrypt an agent profile password, run the agentadmin command with the --p option.

When the agent can’t decrypt the password it writes a message to the logs.

Default: Empty

The AM realm where the agent profile is located. For example, /Customers.

Realm names are case-sensitive. Failure to set the realm name exactly as configured in AM causes the agent to fail to recognize the realm.

Default: /

The key used to encrypt the agent profile password in Agent Profile Password

This property is provided in the agent-key.conf file.

To create a encryption key, run the agentadmin command with the --k option.

Default: Empty

The name of the agent profile in AM.

The separator between values in a multi-valued attribute. The separator applies to all attributes, such as profile, session, and response attributes.

In this example, the attribute HTTP_CUSTOM_TEL has two values separated by a pipe ('|')':

HTTP_CUSTOM_TEL = 45354345|1234

Note: If you use custom code to construct a multi-valued attribute, make sure that the attribute is a string containing the individual values separated by this parameter.

Default: |

Map profile attributes to HTTP headers or HTTP cookies:

HTTP_COOKIE: Map to HTTP cookies

HTTP_HEADER: Map to HTTP headers

Default: NONE

Map the value of a specified session attribute to one or more HTTP headers or HTTP cookies, depending on the value of Session Attribute Fetch Mode.

If the HTTP header or HTTP cookie name does not exist, the agent creates it. If the session attribute name (key) does not exist, the agent does not create the HTTP header or HTTP cookie.

When an HTTP header name is used in a request header, it is prefixed by HTTP_. The agents automatically changes lower case letters to upper case, and hyphens (-) to underscores (_). For example, CUSTOM-userid becomes HTTP_CUSTOM-USERID.

Format:

com.sun.identity.agents.config.session.attribute.mapping[session_attribute]=ATTR1|ATTR2

Examples:

The following example maps the value of the session attribute UserToken to the HTTP header CUSTOM-userid:

com.sun.identity.agents.config.session.attribute.mapping[UserToken]=CUSTOM-userid.

The following example maps the value of the session attribute UserId to two HTTP headers:

com.sun.identity.agents.config.session.attribute.mapping[UserId]=HEADER1|HEADER2`.

Default: Empty

Map the value of a specified response attribute to one or more HTTP headers or HTTP cookies, depending on the value of Response Attribute Fetch Mode.

Consider the following points for cookies:

Consider the following points for response headers:

Format: response attribute = HEADER-NAME(S)

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

Default: Empty

Map response attributes to HTTP headers or HTTP cookies:

HTTP_COOKIE: Map to HTTP cookies

HTTP_HEADER: Map to HTTP headers

Default: NONE

Map session attributes to HTTP headers or HTTP cookies:

HTTP_COOKIE: Map to HTTP cookies

HTTP_HEADER: Map to HTTP headers

Default: NONE

Map the value of a specified profile attribute to one or more HTTP headers or HTTP cookies, depending on the value of Profile Attribute Fetch Mode.

If the HTTP header or HTTP cookie name does not exist, the agent creates it. If the profile attribute name (key) does not exist, the agent does not create the HTTP header or HTTP cookie.

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 type of audit events to log:

Default: LOG_NONE

The location where the agent logs audit messages:

Default: REMOTE

If Audit 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

Enable or disable REMOTE_USER processing for anonymous users.

Default: false

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

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.

Default: true

Map of cookie name to entry 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 name to entry 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 in the User Guide.

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.

Debug level. Set to one of the constrained values.

Default: Error

File size in bytes at which the debug log file is rotated.

Default: 0, debug log file is never rotated

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

By default, the encryption key for the agent profile password is cached. Set this property to true to disable caching and require the agent to read the encryption key every time it is needed.

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/am_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 encrypted password.

This property is provided in the agent-password.conf file.

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

$ /web_agents/agent-type/bin> ./agentadmin --p "key" $(< /tmp/pwd.txt)

Encrypted password value: zck…​tc=

Where key is the value of Agent Profile Password Encryption Key and /tmp/pwd.txt is a text file containing the certificate password.

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 certificates are validated (Server Certificate Trust is false).

Default: 9

Key:Value maps of incoming hostname to outgoing domain. The map key must be set; the map value can contain one or more * wildcards. Map keys and values are case insensitive.

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

Examples:

com.sun.identity.agents.config.fqdn.mapping[agent.localtest.me]=agent.example.com

com.sun.identity.agents.config.fqdn.mapping[agent.localtest.me]=agent-*

com.sun.identity.agents.config.fqdn.mapping[agent.localtest.me]=agent--other-

com.sun.identity.agents.config.fqdn.mapping[agent.othertest.me]=other.example.com

For more information, refer to FQDN checking in the User Guide.

When true, the agent checks whether request URLs match values in FQDN Default and FQDN Virtual Host Map.

Use this property to prevent the redirect of requests in the following scenarios:

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

Default: false

For more information, refer to FQDN checking in the User Guide.

The default FQDN to access resources. Set this property during agent installation, and change it only if necessary. Without this value, the web server can fail to start.

This property requires Enable FQDN Check to be true.

For more information, refer to FQDN checking in the User Guide.

The password to use 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.

The password is provided in the agent-password.conf file.

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