Guide to installing ForgeRock® Access Management web agents. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.

Configuration Cache

The configuration cache stores web agent configuration properties.

When a web agent starts up, it either makes a call to AM to retrieve a copy of the agent profile (centralized configuration) or reads the agent profile from the local configuration file (local configuration). Then, the agent stores the configuration in its cache. The information stored in the cache is valid until one of the following events occur:

• AM notifies the agent of changes to hot-swappable web agent configuration properties. This only applies to deployments that use centralized configuration.

• The information in cache reaches the expiration time specified by the com.sun.identity.agents.config.polling.interval property.

When a configuration property in the cache is invalid, the web agent clears the cached property value and rereads it from the agent profile.

Session and Policy Decision Cache

Stored in the shared memory pool defined by the AM_MAX_SESSION_CACHE_SIZE environment variable, the session and policy decision cache stores session information, and the results of previous policy decisions.

The default size of the cache is 16 MB, but you may need to increase its size if you plan to hold many active sessions in the cache at any given time. For more information about the environment variable, see "Configuring Web Agent Environment Variables".

After authentication, AM presents the client with an ID token containing session information. The web agent stores part of that session information in the cache. When a client attempts to access a protected resource, the web agent checks whether there is a policy decision cached for the resource:

• If there is a cached policy decision, the agent reuses it without contacting AM.

• If there is no cached policy decision, the validity of the client's session determines the agent's behavior:

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

  • If the client's session is not valid, the agent redirects the client to AM for authentication regardless of why the session is invalid. The web agent does not specify the reason why the client needs to authenticate.

    Once the client authenticates and the session is cached, the web agent requests a policy decision from AM, caches it, and then enforces it.

Session and policy decisions are valid in the cache until one of the following events occur:

Session and Policy Decision Validity in Cache

Event	What is invalidated?
Session contained in the ID token expires	Session and policy decisions related to the session
Client logs out from AM (and session notifications are enabled)	Session and policy decisions related to the session
Session reaches the expiration time specified by the com.sun.identity.agents.config.sso.cache.polling.interval property	Session
Policy decision reaches the expiration time specified by the com.sun.identity.agents.config.policy.cache.polling.interval property	Policy decision
Administrator makes a change to policy configuration (and policy notifications are enabled)	All sessions and all policy decisions

Important

A web agent that loses connectivity with AM cannot request policy decisions. Therefore, the web agent denies access to inbound requests that do not have a policy decision cached until the connection is restored(*).

For more information about properties related to the session and policy decision cache, see Policy Client Service Properties.

Policy Cache

The policy cache builds upon the policy decision cache. It downloads and stores details about policies from AM, and uses the downloaded policies to make authorization decisions, without contacting AM each time.

Web agents use the policy cache without contacting AM in the following situations:

• A requested resource matches the resource pattern of a policy that has been cached due to a previous evaluation.

• A requested resource does not match any cached policy patterns. In this case, the agent denies access immediately.

• A requested resource matches the resource pattern of a simple policy that applies to the All Authenticated Users virtual group.

If the resource matches the policy used for a previous policy decision, the agent does not request policy evaluation from AM. Therefore, policy conditions based on scripts, LDAP filter conditions, or session properties, which rely on attributes that can vary during a session, may not be enforced.

To reduce this risk, you should:

• Enable the session property change notification feature. See "Notification System".

• Reduce the amount of time that sessions can remain in the agent session cache. See Policy Client Service Properties.

Caveats

The following caveats apply when using the policy cache:

• If you have a large number of policies, for example more than one million in an UMA deployment, the time to download the policies and the memory consumption of the agent may affect performance.

• The agent downloads the policy rules, and uses them to evaluate policies locally. If a policy is customized in AM in a way that changes the way it is evaluated (for example, a wildcard or delimiter is changed), the policy decision made by the agent might not match the policy defined in AM.

• Even though delimiters and wildcards are configurable in AM (Configure > Global Services > Policy Configuration > Global Attributes > Resource Comparator), the policy cache only supports the default configuration.

  Do not enable the agent's policy cache if your policies use custom delimiters and/or wildcards.

Enable the policy cache by creating an environment variable named AM_POLICY_CACHE_MODE.

Change the location of the policy cache by creating an environment variable named AM_POLICY_CACHE_DIR.

For more information about properties related to the policy cache, see "Configuring Web Agent Environment Variables".

POST Data Preservation Cache

Stored in files saved in the agent installation directory, the POST data preservation cache stores short-lived POST data.

When POST data preservation is enabled (com.sun.identity.agents.config.postdata.preserve.enable), the web agent caches HTML form data submitted as an HTTP POST by unauthenticated clients. By default, this data is stored in the directory specified by the org.forgerock.agents.config.postdata.preserve.dir property.

POST data information is cached for the amount of time specified by the POST Data Entries Cache Period (com.sun.identity.agents.config.postcache.entry.lifetime) property.

For more information about POST data preservation, see "POST Data Preservation" and Post Data Preservation.

Web server configuration file

Enter the full path to the Apache configuration file. The installer modifies this file to include the web agent configuration and module.

OpenAM URL

Enter the full URL of the AM instance the web agents will be using. Ensure the deployment URI is specified.

To balance agent connections to an AM site, enter the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

Agent URL

Enter the full URL of the server the agent is running on.

Realm

Enter the AM realm containing the agent profile. Realms are case-sensitive.

Agent profile name

Enter the name given to the agent profile created in AM.

Agent profile password

Enter the full path to the file containing the agent profile password.

--changeOwner

On Unix systems, use this option to set the ownership of created directories to the user and group as specified in the Apache configuration file.

Note that this option will only change the ownership of the files and directories if you run the agentadmin command as the root user or using the sudo command.

If you cannot run the agentadmin as the root user or using the sudo command, you must change the ownership manually. Refer to the next steps for more information.

--acceptLicence

You can suppress the license agreement prompt during a silent, non-interactive install by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open /path/to/web_agents/agent_type/legal/Forgerock_License.txt.

--forceInstall

Optionally have the installer proceed with a silent installation even if it cannot connect to the specified AM server during installation, rather than exiting.

Web server configuration file

Enter the ID number of the IIS site in which to install the web web agent. For a description of the supported IDs, see "To Install the IIS Web Agent".

Tip

To list the sites in an IIS server, run agentadmin.exe --n

OpenAM URL

Enter the full URL of the AM instance the web agents will be using. Ensure the deployment URI is specified.

To balance agent connections to an AM site, enter the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

Agent URL

Enter the full URL of the IIS site the agent will be running on.

Realm

Enter the AM realm containing the agent profile. Realms are case-sensitive.

Agent profile name

Enter the name given to the agent profile created in AM.

Agent profile password

Enter the full path to the file containing the agent profile password.

--acceptLicence

You can suppress the license agreement prompt during a silent, non-interactive install by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open /path/to/web_agents/agent_type/legal/Forgerock_License.txt.

--forceInstall

Add this optional switch to have the installer proceed with a silent installation even if it cannot connect to the specified AM server during installation, rather than exiting.

You must also apply workarounds as described for the following Microsoft issues.

Microsoft Support Issue: 841215

Link: http://support.microsoft.com/kb/841215

Description: Error message when you try to connect to a Windows SharePoint document library: "System error 5 has occurred".

Summary: Enable Basic Authentication on the client computer.

Microsoft Support Issue: 870853

Link: http://support.microsoft.com/kb/870853

Description: Office 2003 and 2007 Office documents open read-only in Internet Explorer.

Summary: Add registry keys as described in Microsoft's support document.

Microsoft Support Issue: 928692

Link: http://support.microsoft.com/kb/928692

Description: Error message when you open a Web site by using Basic authentication in Expression Web on a computer that is running Windows Vista: "The folder name is not valid".

Summary: Edit the registry as described in Microsoft's support document.

Microsoft Support Issue: 932118

Link: http://support.microsoft.com/kb/932118

Description: Persistent cookies are not shared between Internet Explorer and Office applications.

Summary: Add the web site the list of trusted sites.

Microsoft Support Issue: 943280

Link: http://support.microsoft.com/kb/943280

Description: Prompt for Credentials When Accessing FQDN Sites From a Windows Vista or Windows 7 Computer.

Summary: Edit the registry as described in Microsoft's support document.

Microsoft Support Issue: 968851

Link: http://support.microsoft.com/kb/968851

Description: SharePoint Server 2007 Cumulative Update Server Hotfix Package (MOSS server-package): April 30, 2009.

Summary: Apply the fix from Microsoft if you use SharePoint.

Microsoft Support Issue: 2123563

Link: http://support.microsoft.com/kb/2123563

Description: You cannot open Office file types directly from a server that supports only Basic authentication over a non-SSL connection.

Summary: Enable SSL encryption on the web server.

Web server configuration file

Enter the full path to the NGINX Plus server configuration file. The installer modifies this file to include the web agent configuration and module.

OpenAM URL

Enter the full URL of the AM instance the web agents should connect to. Ensure the deployment URI is specified.

To balance agent connections to an AM site, enter the URL of the load balancer in front of the AM site.

Note

If your environment has a reverse proxy configured between AM and the agent, set the AM URL to the proxy URL instead. For example, https://proxy.example.com:443/openam. For more information about setting up the environment for reverse proxies, see "Configuring Apache HTTP Server as a Reverse Proxy Example".

Agent URL

Enter the full URL of the server the agent is running on.

Realm

Enter the AM realm containing the agent profile. Realms are case-sensitive.

Agent profile name

Enter the name of the agent profile created in AM.

Agent profile password

Enter the full path to the file containing the agent profile password.

--acceptLicence

You can suppress the license agreement prompt during a silent, non-interactive install by including the --acceptLicence parameter. The inclusion of the option indicates that you have read and accepted the terms stated in the license. To view the license agreement, open /path/to/web_agents/agent_type/legal/Forgerock_License.txt.

--forceInstall

Optionally have the installer proceed with a silent installation even if it cannot connect to the specified AM server during installation, rather than exiting.

AmAgentID (Apache only)

The following is an example of a httpd.conf file with the AmAgentID directive configured:

<VirtualHost *:80>
ServerName www.site1.com
DocumentRoot /home/www/site1.com
AssignUserID site1 www-data
LoadModule amagent_module /web_agents/apache24_agent/lib/mod_openam.so
AmAgent On
AmAgentConf /web_agents/apache24_agent/bin/../instances/agent_1/config/agent.conf
AmAgentID 1
...
</VirtualHost>

<VirtualHost *:8080>
ServerName www.site2.com
DocumentRoot /home/www/site3.com
AssignUserID site2 www-data
LoadModule amagent_module /web_agents/apache24_agent/lib/mod_openam.so
AmAgent On
AmAgentConf /web_agents/apache24_agent/bin/../instances/agent_2/config/agent.conf
AmAgentID 1
...
</VirtualHost>

In this example, each virtual host is protected by a different instance of the agent, yet both agent instances belong to the agent group 1. They share runtime resources and shared memory.

openam_agent_instance (NGINX Plus only)

The following is an example of the nginx.conf file with the openam_agent_instance directive configured:

server {
listen       80 default_server;
server_name  localhost;
openam_agent on;
openam_agent_configuration /web_agents/nginx17_agent/bin/../instances/agent_3/config/agent.conf;
openam_agent_instance 2
...
   location /customers {
   openam_agent on;
   openam_agent_configuration /web_agents/nginx17_agent/bin/../instances/agent_4/config/agent.conf;
   openam_agent_instance 2
   root   /www/customers
   index  index.html
}
...

In this example, agent_1 protects the server context while agent_2 protects a location. Both instances belong to the agent group 1 and share runtime resources and shared memory.

Miscellaneous Bootstrap Properties

com.sun.identity.agents.config.organization.name

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 will cause the agent to fail to recognize the realm.

Default: /

com.sun.identity.agents.config.username

The name of the agent profile in AM.

Default: not set

com.sun.identity.agents.config.password

The password required by the agent profile, encrypted with the key specified in com.sun.identity.agents.config.key.

To encrypt an agent profile password, run the agentadmin command with the --p option. For an example, see "Command-Line Tool Reference".

Default: not set

com.sun.identity.agents.config.key

The encryption key used to encrypt the agent profile password, which should be provided in com.sun.identity.agents.config.password.

To create a encryption key, run the agentadmin command with the --k option. For an example, see "Command-Line Tool Reference".

Default: not set

org.forgerock.agents.config.tls

A space-separated list of security protocols preceded by a dash - that are not used when connecting to AM.

The following protocols are supported:

• SSLv3

• TLSv1

• TLSv1.1

• TLSv1.2 (Enabled)

• TLSv1.3 (Enabled)

This property is relevant to all web agents using OpenSSL libraries.

Default: -SSLv3 -TLSv1 -TLSv1.1

To change the default value, set an environment variable, AM_SSL_OPTIONS. For more information, see "Configuring Web Agent Environment Variables".

Note

SSLv2 is always disabled, regardless of setting.

org.forgerock.agents.init.retry.max

The maximum number of consecutive agent initialization retries.

Default: 0 (when not set)

org.forgerock.agents.init.retry.wait

The number of seconds to wait between retries.

Default: 0 (when not set)

com.sun.identity.agents.config.connect.timeout

The number of seconds to wait for a connection to AM before timing out and cancelling the connection. Applies to TCP connect operations.

Default: 4

com.sun.identity.agents.config.receive.timeout

The number of seconds to wait for a response from AM before timing out and dropping the connection. Applies to TCP receive operations.

Default: 4

sun.identity.agents.config.naming.url

A space-separated list of AM URLs to which the agent connects. Set this property to the URL of the load balancer in front of the AM instances (or load balancers, in case of disaster-recovery configurations).

When the web agent cannot connect to the first URL in the list, it automatically connects to the next available URL. The agent stays connected to the new URL until the URL fails, or the agent is restarted.

Default: AM_URL/openam/

org.forgerock.agents.config.connection.pool.enable

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.

Type: Boolean

Default: true

Hot-swap: No

Property: org.forgerock.agents.config.connection.pool.enable, introduced in Web Agents 5.8

Forward Proxy Bootstrap Properties

com.sun.identity.agents.config.forward.proxy.host

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: not set

com.sun.identity.agents.config.forward.proxy.port

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: not set

com.sun.identity.agents.config.forward.proxy.user

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: not set

com.sun.identity.agents.config.forward.proxy.password

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: not set

Encryption Bootstrap Properties

For more information, see "Configuring Web Agents to Secure Communication with AM".

CA Certificate File Name

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

The file should be Privacy-Enhanced Mail (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 Web Agents using the Windows built-in Secure Channel API, add the appropriate certificates to the Windows certificate store.

Default: Empty

Property: com.forgerock.agents.config.cert.ca.file

OpenSSL Certificate Verification Depth

(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 will be 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:

• 0: Only self-signed certificates are accepted.

• 1: Client certificates can be self-signed or must be signed by a CA which is directly known to the agent container.

• 2 or more: A chain of the specified number of certificates, including the previous ones. For example, the value 5 allows certificates from level 0 to level 5.

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

Default: 9

Property: org.forgerock.agents.config.cert.verify.depth

Public Client Certificate File Name

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:

• Store the certificate chain and its private key as a Personal Information Exchange Format (PFX) file, then configure it in the agent property. For example:

  com.forgerock.agents.config.cert.file = C:\Certificates\client.pfx

  In this case, you must also configure the com.forgerock.agents.config.cert.key.password property.

• Store the certificate locally in the Windows certificate store and configure the friendly name of the client certificate as it shows in Windows, in the agent property:

  Friendly Name in the Windows Certificates Snap-in

  
  
  

  For example:

  com.forgerock.agents.config.cert = client-private-friendly-name

Default: not set

Property: com.forgerock.agents.config.cert.file

Private Client Certificate File Name

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

Web 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

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

Default: not set

Property: com.forgerock.agents.config.cert.key

Private Key Password

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, as follows:

$ cd /web_agents/agent-type/bin
$ /web_agents/agent-type/bin> ./agentadmin --p "Encryption Key" "`cat cert_password.file`"
Encrypted password value: zck+6RKqjtc=

C:\>cd C:\web_agents\agent-type\bin
C:\path\to\web_agents\bin\> agentadmin.exe --p "Encryption Key" "certpassword"
Encrypted password value: zck+6RKqjtc=

Encryption Key is the value of the com.sun.identity.agents.config.key bootstrap property.

Default: not set

Property: com.forgerock.agents.config.cert.key.password

Trust Server Certificates

Whether the agent should validate the certificate presented during SSL handshakes by the container where AM runs:

• true. The agent trusts any server certificate. By default, and to facilitate integration and testing, agent is configured to trust any server certificate.

• false. The agent trusts AM's certificate only if found to be correct and valid.

Important

If the agent cannot connect to AM, it does not allow access to any protected resource. Ensure the agent is properly configured before setting this property to false. For more information, see "Configuring Web Agents to Secure Communication with AM".

Default: true

Property: com.sun.identity.agents.config.trust.server.certs

Use OpenSSL to Secure Internal Communications

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

• true. The agent uses OpenSSL.

• false. The agent uses the Windows built-in Secure Channel API.

Default: false

Property: org.forgerock.agents.config.secure.channel.disable

Accept Secure Cookies From AM Over HTTP

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.

The property can take the following values:

• true: The agent accepts secure cookies from AM over HTTP.

• false: The agent rejects secure cookies from AM over HTTP.

Note

It is best practice to use HTTPS for all connections to AM.

Default: false

Property: com.forgerock.agents.plain.channels.insecure

Profile Global Properties

Group (agentgroup)

Assign the agent to a previously configured agent group in order to inherit selected properties from the group. Select Unassigned to remove the agent from an agent group.

Password

Web Agents password used when creating the password file and when installing the agent.

If you change the password, manually update the password in the bootstrap property com.sun.identity.agents.config.password.

Status

Status of the agent configuration.

Location of Agent Configuration Repository

How to manage the agent configuration:

• centralized: Through AM.

• local: Locally in the agent configuration file.

  If you change this to a local configuration, you can no longer manage the agent configuration through the AM console.

Default: centralized

Property: com.sun.identity.agents.config.repository.location

Agent Configuration Change Notification

Whether AM sends a notification to the web agent to reread the agent profile after a change to a hot-swappable property. This property applies only when you store the agent profile in AM's configuration data store.

Default: true

Property: com.sun.identity.agents.config.change.notification.enable

Hot-swap: yes

Web Socket Connection Interval

The time in minutes after which web agents reopen their WebSocket connection to AM. This property helps ensure a balanced distribution of connections across the AM servers on the site.

Default: 30

Property: org.forgerock.openam.agents.config.balance.websocket.connection.interval.in.minutes

Hot-swap: yes

JWT Cookie Name

The name of the cookie that holds the OpenID Connect ID token on the user's browser.

Before changing the name of this cookie, consider the following points:

• The cookie is only used by the web agent and is never presented to AM.

• The cookie name must be unique across the set of cookies the user's browser receives, since some browsers behave in unexpected ways when receiving several cookies with the same name. For example, you should not set the session ID token cookie name to iPlanetDirectoryPro, which is the default name of AM's session cookie.

Default: am-auth-jwt

Property: org.forgerock.openam.agents.config.jwt.name

Hot-swap: yes

Exchange SSO Token for JWT

This property is marked as deprecated and will be removed in a later version.

Use Accept SSO Token instead.

Property: com.forgerock.agents.accept.ipdp.cookie

Disable validation of the audience claim

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

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

To set for local configurations, add the property to the agent.conf file.

The claims to validate in the ID token containing the end user's session:

• 0: Validate the aud and nonce claim.

• 1: Validate the nonce claim; don't validate the aud claim.

During an authentication request, AM creates an ID token that contains, among others, the end user's session, and the aud claim. The aud claim is set to the agent profile of the agent that made the request. When AM returns the ID token to the end user's user-agent, it appends a nonce parameter to the request, which is a one-time-usable random string that is understood by both AM and the agent that made the authentication request.

When the agent receives a request to access a protected resource, the agent checks that the audience (the aud claim) of the ID token and the value of the nonce are appropriate. For example, it checks that the value of the aud claim is the name of its own agent profile.

In environments where several agents protect the same application, this validation poses a problem; even if the ID token is valid and contains a valid session, an agent cannot validate a ID token created for a different agent because the audience would not match. Therefore, the agent redirects the end user to authenticate again.

Tip

For security reasons, agents should validate as many claims in the ID token as possible.

Default: 0

Hot-swap: Yes

Property: com.forgerock.agents.jwt.aud.disable

Agent Profile ID Whitelist

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

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

To set for local configurations, add the property to the agent.conf file.

A comma-separated list of profile IDs that the agent considers as valid values for the aud claim. This claim is represented in the ID token containing the end user's session.

When several agents are configured with different agent profiles to protect the same application, set this property to a list of the agent profiles that are protecting the same application.

With the following setting, the Agent considers agentprofile1 and agentprofile2 to be valid, and does not validate them:

com.forgerock.agents.jwt.aud.whitelist=agentprofile1,agentprofile2

Default: Empty

Hot-swap: Yes

Property: com.forgerock.agents.jwt.aud.whitelist

Enable Notifications

Whether AM sends notifications to the agent to:

• Refresh the session cache when a session times out or a client logs out from AM.

• Refresh the policy cache when the administrator changes a policy.

Default: true

Hot-swap: No

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

Agent Notification URL (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

When creating a web agent profile, the AM console configures a default value for this property to maintain compatibility with earlier versions of the web agent. The default value should be removed. For more information, see the Release Notes.

Property: com.sun.identity.client.notification.url

Agent Deployment URI Prefix

Overrides the request URL given by the agent when it is configured behind a load balancer or proxy. Use this property when the protocol, hostname, or port of the load balancer or proxy differ from those of the web agent.

For the agent to honor this property, at least one of the following properties must be enabled:

• Override Request URL Port

• Override Request URL Protocol

• Override Request URL Host

Use these properties olny if you are not using x-forwarded headers from the load balancer or proxy to override the agent's protocol, hostname, and port values.

For more information, see "Regarding Communication Between Clients and Agents".

Default: agent-root-URL

Property: com.sun.identity.agents.config.agenturi.prefix

Hot-swap: yes

Configuration Reload Interval

Time in minutes after which to fetch the agent configuration from AM. Used if notifications are disabled.

Default: 60

Property: com.sun.identity.agents.config.polling.interval

Hot-swap: no

Configuration Cleanup Interval (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

Property: com.sun.identity.agents.config.cleanup.interval

Agent Root URL for CDSSO

The agent root URLs for CDSSO. The valid value is in the format protocol://hostname:port/ where protocol represents the protocol used, such as http or https, hostname represents the host name of the system where the agent resides, and port represents the port number on which the agent is installed. The slash following the port number is required.

If your agent system also has virtual host names, add URLs with the virtual host names to this list as well. AM checks that the goto URLs match one of the agent root URLs for CDSSO.

Default: agent-root-URL

Property: sunIdentityServerDeviceKeyValue[n]

General Global Properties

SSO Only Mode

When true, the agent manages only user authentication. The filter invokes the AM Authentication Service to verify the identity of the user. If the user's identity is verified, the user is issued a session token through AM's Session Service.

When false, the agent manages user authorization, by using the policy engine in AM.

Tip

Consider configuring the Reset Idle Timeout (com.forgerock.agents.call.session.refresh) property when configuring the agent in SSO-only mode.

Type: Boolean

Default: false

Property: com.sun.identity.agents.config.sso.only

Reset Idle Timeout

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

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

To set for local configurations, add the property to the agent.conf file.

Specifies whether an agent configured in SSO-only mode should refresh the user's session idle time when the user accesses a protected resource.

Sessions in AM 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.

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:

• The agent is configured in SSO-only mode.

• User's sessions are timing out in AM because they are unexpectedly reaching the maximum idle timeout value.

Default: Not set

Property: com.forgerock.agents.call.session.refresh

Resources Access Denied URL

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

The following are not permitted:

• Wildcards

• The . directory specifier

• The .. directory specifier

Default: not set

Property: com.sun.identity.agents.config.access.denied.url

Agent Debug Level

Valid values for the property are:

• All

• Error

• Info

• Message

• Warning

Default: Error

Property: com.sun.identity.agents.config.debug.level

Agent Debug File Rotation (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

When true, rotate the debug file when the specified file size is reached.

Default: true

Property: com.sun.identity.agents.config.debug.file.rotate

Agent Debug File Size

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

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

To set for local configurations, add the property to the agent.conf file.

File size in bytes beyond 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).

This is a bootstrap property. Configure it in the agent.conf file, even when the agent is configured in centralized mode.

Default: 10000000

Hot-swap: No

Property: com.sun.identity.agents.config.debug.file.size

Local Agent Debug File Name

Name of a file stored locally on the agent that contains agent debug messages.

This is a bootstrap property. Configure it in the agent.conf file, even when the agent is configured in centralized mode.

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

Property: com.sun.identity.agents.config.local.logfile

Audit Global Properties

Audit Access Types

The type of audit events to log:

• LOG_NONE: Disable audit logging.

• LOG_ALLOW: Log access allowed events.

• LOG_DENY: Log access denied events.

• LOG_BOTH: Log access allowed and access denied events.

Default: LOG_NONE

Hot-swap: yes

Property: com.sun.identity.agents.config.audit.accesstype

Audit Log Location

The location where the web agent logs audit messages:

• REMOTE. Log audit event messages to the audit event handler configured in the AM realm where the web agent is configured.

• LOCAL. Log audit event messages locally to the agent installation.

• ALL. Log audit event messages to the audit event handler configured in the AM realm and locally to the agent installation.

Default: REMOTE

Hot-swap: yes

Property: com.sun.identity.agents.config.log.disposition

Remote Log Filename (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

Property: com.sun.identity.agents.config.remote.logfile

Remote Audit Log Interval (depreacated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

Interval in minutes after which audit log messages are periodically sent to the remote log file.

Default: 5

Hot-swap: no

Property: com.sun.identity.agents.config.remote.log.interval

Rotate Local Audit Log

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

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

To set for local configurations, add the property to the agent.conf file.

This is a bootstrap property. Configure it in the agent.conf file, even when the agent is configured in centralized mode.

Hot-swap: No

Property: com.sun.identity.agents.config.local.log.rotate

Local Audit Log Rotation Size

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

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

To set for local configurations, add the property to the agent.conf file.

This is a bootstrap property. Configure it in the agent.conf file, even when the agent is configured in centralized mode.

The maximum size in bytes of the local audit log files. Web Agents rotate audit log files when they reach this size.

Default: 52428800

Property: com.sun.identity.agents.config.local.log.size

Hot-swap: No

Local Agent Audit File Name

Name of file stored locally on the agent that contains agent audit messages if log location is LOCAL or ALL.

This is a bootstrap property. Configure it in the agent.conf file, even when the agent is configured in centralized mode.

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

Property: com.sun.identity.agents.config.local.audit.logfile

Fully Qualified Domain Name Checking Properties

FQDN Check

Enables checking of FQDN default value and FQDN map values.

Property: com.sun.identity.agents.config.fqdn.check.enable

FQDN Default

The FQDN that the users should use in order to access resources. Without this value, the web server can fail to start, thus you set the property on agent installation, and only change it when 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.

Note

If you specify an FQDN in this property, you must also add it to the Agent Root URL for CDSSO property.

Property: com.sun.identity.agents.config.fqdn.default

FQDN Virtual Host Map

Enables virtual hosts, partial hostname, and IP address to access protected resources. Maps invalid or virtual name keys to valid FQDN values 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 keyword validn, where n is an incrementing integer starting at 1, in the Map Key field. Enter virtual.example.com in the Corresponding Map Value field.

In the configuration file, this corresponds to com.sun.identity.agents.config.fqdn.mapping[valid1]=virtual.example.com.

To map myserver to myserver.mydomain.example, enter myserver in the Map Key field, and enter myserver.mydomain.example in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.fqdn.mapping[myserver]=myserver.mydomain.example.

Invalid FQDN values can cause the web server to become unusable or render resources inaccessible.

Property: com.sun.identity.agents.config.fqdn.mapping[Source hostname / IP address]=Target FQDN

Load Balancing Properties

AM Load Balancer Cookie Enabled

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

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

To set for local configurations, add the property to the agent.conf file.

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

Type: Boolean

Hot-swap: Yes

Property: com.forgerock.agents.config.add.amlbcookie, introduced in Web Agents 5.8

Not-Enforced URL Properties

Ignore Path Info for Not-Enforced URLs

When true, the path info and query are stripped from the request URL before being compared with the URLs of the not-enforced list for those URLs containing a wildcard character. This prevents a user from accessing http://host/index.html by requesting http://host/index.html/hack.gif when the not-enforced list includes http://host/*.gif.

For more information, see Ignore Path Info.

Note

The NGINX Plus web agent does not support this setting.

Default: true

Property: com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list

Regular Expressions for Not-Enforced URLs

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

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

To set for local configurations, add the property to the agent.conf file.

When true, enables use of Perl-compatible regular expressions in Not-enforced URL settings.

Default: false

Property: com.forgerock.agents.notenforced.url.regex.enable

Not-Enforced URLs

List of URLs allowed to bypass authentication and grant immediate access to resources, such as images, stylesheets, or static HTML pages.

Tip

You can also limit not-enforced URL rules to specific HTTP methods. For more information, see "Not-Enforced URL and Client IP Lists".

You can use wildcards to define a pattern for a URL. The * wildcard matches all characters except question mark (?), cannot be escaped, and spans multiple levels in a URL. Multiple forward slashes do not match a single forward slash, so * matches mult/iple/dirs, yet mult/*/dirs does not match mult/dirs.

The -*- wildcard matches all characters except forward slash (/) or question mark (?), and cannot be escaped. As it does not match /, -*- does not span multiple levels in a URL. The -*- wildcard can only be used in the path sections of a URL, not within the host, port, or protocol sections.

AM does not let you mix * and -*- in the same URL.

Examples include http://www.example.com/logout.html, http://www.example.com/images/*, http://www.example.com/css/-*-, and http://www.example.com/*.jsp?locale=*.

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

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

com.sun.identity.agents.config.notenforced.url[n]=/forst%C3%A5/*

Trailing forward slashes are not recognized as part of a resource name. Therefore http://www.example.com/images// and http://www.example.com/images are equivalent.

Default: Not set

Property: com.sun.identity.agents.config.notenforced.url[n]

If you enabled use of Perl-compatible regular expressions to match not-enforced URLs, then all your settings must be done using regular expressions. (Do not mix settings; use either the mechanism described above or Perl-compatible regular expressions, but not both.)

The following example shows settings where no authentication is required for URLs whose path ends /PublicServletA or /PublicServletB (with or without query string parameters), and no authentication is required to access .png, .jpg, .gif, .js, or .css files under URLs that do not contain /protectedA/ or /protectedB/.

com.sun.identity.agents.config.notenforced.url[0]=.*/(PublicServletA|PublicServletB)(\?.*|$)
   com.sun.identity.agents.config.notenforced.url[1]=^(?!.*(/protectedA/|/protectedB/)).*\.(png|jpg|gif|js|css)(\?.*|$)

Invert Not-Enforced URLs

When true, enforce policy for the URLS and patterns specified in the Not-Enforced URLs property instead of allowing access to them without authentication. Consider the following points when configuring this property:

• An empty Not-Enforced URL property results in all URLs being enforced

• At least one URL must be enforced. To allow access to any URL without authentication, consider disabling the web agent

Default: false

Property: com.sun.identity.agents.config.notenforced.url.invert

Fetch Attributes for Not-Enforced URLs

When true, the agent fetches profile, response, and session attributes that are mapped by doing policy evaluation, and forwards these attributes to not-enforced URLs.

Default: false

Property: com.sun.identity.agents.config.notenforced.url.attributes.enable

Not-Enforced IP Properties

Not-Enforced Client IP List

The IP addresses or network CIDR notation for which no authentication is required. Supported values are:

• IPV4 and IPV6 addresses.

• IPV4 and IPV6 addresses specified in CIDR notation.

• IPV4 and IPV6 ranges of addresses delimited by the - character.

• Network ranges specified in CIDR notation.

For example:

  com.sun.identity.agents.config.notenforced.ip[0]= 192.18.145.128
  com.sun.identity.agents.config.notenforced.ip[2]= 192.168.145.128/24
  com.sun.identity.agents.config.notenforced.ip[1]= 2001:5c0:9168:0:0:0:0:2/128
  com.sun.identity.agents.config.notenforced.ip[3]= 192.168.1.0/24
  com.sun.identity.agents.config.notenforced.ip[4]= 192.18.145.128-192.168.145.133
  com.sun.identity.agents.config.notenforced.ip[5]= 2001:5c0:9168:0:0:0:0:1-2001:5c0:9168:0:0:0:0:2
 

Web Agents stop evaluating not-enforced properties after reaching an invalid netmask in the list.

Note

Loopback addresses are not considered valid IPs on the Not-Enforced IP list. If specified, the web agent ignores the loopback address.

Default: not set

Property: com.sun.identity.agents.config.notenforced.ip[n]

Client IP Validation

When true, validate that the subsequent browser requests come from the same IP address that the SSO token is initially issued against.

Default: false

Property: com.sun.identity.agents.config.client.ip.validation.enable

Not-Enforced URL from IP Processing Properties

Not-Enforced URL from IP Processing List

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

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

To set for local configurations, add the property to the agent.conf file.

A list of client IP addresses that do not require authentication when requesting the indicated URLs.

The supported format requires a list of IP addresses separated by spaces, the horizontal bar (|) character, and a list of URLs separated by spaces. For example:

org.forgerock.agents.config.notenforced.ipurl[0]=10.1.2.1 192.168.0.2|/public/*

In the preceding example, the IP addresses 10.1.2.1 and 192.168.0.2 can access any resource inside /public without authenticating.

The list of IP addresses supports IPv4 and IPv6 addresses specified by either CIDR or IP range notation:

• IP range notation

  Supported values are IPv4 and IPv6 ranges of addresses. For example:

  org.forgerock.agents.config.notenforced.ipurl[1]=192.168.1.1-192.168.1.10|/public/*
      org.forgerock.agents.config.notenforced.ipurl[2]=2001:5c0:9168:0:0:0:0:1-2001:5c0:9168:0:0:0:0:2|/public/*

  In the preceding IPv4 example, clients with IP addresses in the range 192.168.1.1-192.168.1.10 need not to authenticate to access the list of URLs included in /public/*.

• CIDR notation

  Supported values are specified in CIDR notation. For example:

  org.forgerock.agents.config.notenforced.ipurl[3]=192.168.1.0/24 192.168.100.0/24|/public/*
      org.forgerock.agents.config.notenforced.ipurl[4]=2001:5c0:9168:0:0:0:0:2/128|/public/*

  In the preceding IPv4 example, the IP addresses defined on the network 192.168.1 with netmask 255.255.255.0 and the network 192.168.100 with netmask 255.255.255.0 need not to authenticate to access the list of URLs included in /public/*.

The list of URLs can be specified by using the following methods:

• Wildcards

  The wildcard * matches all characters, except the question mark ? character, cannot be escaped, and spans multiple levels in a URL. Multiple forward slashes do not match a single forward slash, so * matches mult/iple/dirs, yet mult/*/dirs does not match mult/dirs. For example:

  org.forgerock.agents.config.notenforced.ipurl[5]=192.6.8.0/24|/public/* /free_access/login*

  In the preceding example, the IP addresses specified in 192.6.8.0/24 do not need authenticating to access any resource inside the /public URI, or any resource (files or directories) that starts with login inside the /free_access URI.

• Regular Expressions

  To use regular expressions in the URL list, set the org.forgerock.agents.config.notenforced.ext.regex.enable property to true and use Perl-compatible regular expressions. For example:

  org.forgerock.agents.config.notenforced.ipurl[6]=192.6.8.0/24|.*\/private\/.*(png|jpg|gif)

  In the preceding example, the IP addresses specified in 192.6.8.0/24 do not need to authenticate to access any png, jpg, or gif images that are inside the /private URI.

• Internationalized Resource Identifiers (IRIs)

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

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

  com.sun.identity.agents.config.notenforced.ipurl[7]=192.6.8.0/24|/forst%C3%A5/*

Default: not set

Property: org.forgerock.agents.config.notenforced.ipurl[n]

Regular Expressions for Not-Enforced IPs

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

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

To set for local configurations, add the property to the agent.conf file.

Enable use of Perl-compatible regular expressions in Not-Enforced URL from IP settings.

Default: false

Property: org.forgerock.agents.config.notenforced.ext.regex.enable

Not-Enforced Fallback Mode Properties

Not-Enforced Fallback Mode

Specifies whether the web agent should allow traffic to resources specified in the not-enforced lists when AM is not available. The property accepts two values:

• true: While AM is unavailable, the web agent:

  1. Reads the cached agent profile configuration until it expires. If you are not familiar with the web agent's caches, see "Caching Capabilities".

  2. After the cache expires, reads the local configuration file webagents/agent_type/instances/agent_1/config/agent.conf.

  If not-enforced properties are configured in the local configuration file, the web agent allows access to the not-enforced resources. However, response attributes for not-enforced resources are not available until AM is accessible.

• false: When AM is unavailable, the web agent prevents access to all resources, including any not-enforced resources.

Configuring this property requires setting up several properties in the the local configuration file webagents/agent_type/instances/agent_1/config/agent.conf even if the agent profile is in centralized configuration.

In the Bootstrap section, configure the fallback property:

com.forgerock.agents.config.fallback.mode = true

In the Configuration section, configure the not-enforced properties required for your environment. For example:

com.sun.identity.agents.config.notenforced.url.attributes.enable = true
  com.sun.identity.agents.config.notenforced.url.invert = false
  com.sun.identity.agents.config.notenforced.url[0] = http://agenttest.example.com/index.html

This is a bootstrap property. Configure it in the agent.conf file, even when the agent is configured in centralized mode.

Default: false

Property: com.forgerock.agents.config.fallback.mode

Profile Attributes Processing Properties

Profile Attribute Fetch Mode

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

Default: NONE

Property: com.sun.identity.agents.config.profile.attribute.fetch.mode

Profile Attribute Map

Maps the profile attributes to HTTP headers for the currently authenticated user. Map keys are LDAP attribute names, the case of which must exactly match the identity store schema, and map values are HTTP header names.

To populate the value of profile attribute CN under CUSTOM-Common-Name, enter CN in the Map Key field, and enter CUSTOM-Common-Name in the Corresponding Map Value field. This corresponds to com.sun.identity.agents.config.profile.attribute.mapping[CN]=CUSTOM-Common-Name.

Tip

Make sure the case of your LDAP attribute name matches the case of the LDAP schema, otherwise you may see an error similar to the following:

do_header_set(): SM_LOGIN (UiD) is not available in profile attributes

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

Property: com.sun.identity.agents.config.profile.attribute.mapping[LDAP_NAME]=[HTTP_HEADER]

Response Attributes Processing Properties

Response Attribute Fetch Mode

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

Default: NONE

Property: com.sun.identity.agents.config.response.attribute.fetch.mode

Response Attribute Map

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

To populate the value of response attribute uid under CUSTOM-User-Name: enter uid in the Map Key field, and enter CUSTOM-User-Name in the Corresponding Map Value field. This corresponds to 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, response-attr-one becomes HTTP_RESPONSE_ATTR_ONE.

Default: not set

Property: com.sun.identity.agents.config.response.attribute.mapping[RESPONSE_ATTR]=HTTP_HEADER

Session Attributes Processing Properties

Session Attribute Fetch Mode

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

Default: NONE

Property: com.sun.identity.agents.config.session.attribute.fetch.mode

Session Attribute Map

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

To populate the value of session attribute UserToken under CUSTOM-userid: enter UserToken in the Map Key field, and enter CUSTOM-userid in the Corresponding Map Value field. This corresponds to 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, success-url becomes HTTP_SUCCESS_URL.

Default: Not set

Property: com.sun.identity.agents.config.session.attribute.mapping[SESSION_ATTR]=HTTP_HEADER

Common Attributes Fetching Processing Properties

Attribute Multi-Value Separator

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

Default: |

Property: com.sun.identity.agents.config.attribute.multi.value.separator

Continuous Security Properties

Continuous Security Cookies

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

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

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

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

Example:

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

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

Use server-side authorization scripts to:

• Access the map's contents

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

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

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

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

Consider the following example:

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

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

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

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

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

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

Default: not set

Property: org.forgerock.openam.agents.config.continuous.security.cookies[cookie_name]=map_entry_name

Continuous Security Headers

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

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

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

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

Example:

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

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

Use server-side authorization scripts to:

• Access the map's contents

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

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

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

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

Consider the following example:

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

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

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

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

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

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

Default: not set

Property: org.forgerock.openam.agents.config.continuous.security.headers[header_name]=map_entry_name

Cookie Properties

Cookie Name

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

Hot-swap: No

Property: com.sun.identity.agents.config.cookie.name

Persistent JWT Cookie

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

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

To set for local configurations, add the property to the agent.conf file.

Enable persistence for JWT cookies. If true the JWT cookie is not set as a Session Cookie.

Default: false

Property:

Hot-swap: yes

Cookie Security

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

Property: com.sun.identity.agents.config.cookie.secure

Hot-swap: yes

Accept SSO Token

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

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

To set for local configurations, add the property to the agent.conf file.

Specifies whether the agent accepts SSO tokens and ID tokens as session cookies. The SSO token name is given by Cookie Name.

This property requires AM 6 or later.

Possible values are:

• 0. The agent does not accept SSO tokens as session cookies.

• 1. The agent accepts both SSO tokens and ID tokens as session tokens during the login flow, and afterwards. SSO tokens are not converted to ID tokens.

  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.

  In the same way the agent caches session information when using ID tokens, (see "Caching Capabilities"), the agent also caches session information for SSO tokens.

Set this property to 1 in the following cases:

• (Migration only) Your custom login pages use SSO tokens as session tokens, and the Custom Login property is set to 2.

  Custom Login Mode and Accept SSO Token Matrix

  Custom Login Mode	Accept SSO Token [a]
  	0	1
  0	"Default Login Redirection Mode".	"Default Login Redirection Mode". SSO tokens are accepted - used for REST clients.
  1	Custom Login Mode, redirecting to the resource requested originally. Same domain and different domain. SSO token to session ID token conversion.	Not supported
  2 [b]	Not supported	Custom Login Mode, redirecting with a goto query parameter to the originally requested resource. Same domain only. SSO token accepted.
  [a] Requires AM 6 or later [b] This is not a standard flow, and the feature is evolving. It poses limitations, and it is meant only for environments migrating from earlier versions of the agent.

• (Migration only) Your applications, for example, REST or JavaScript clients, can only set SSO tokens.

Default: 0

Hot-swap: Yes

Property: com.forgerock.agents.accept.sso.token

HTTP Only Mode

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

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

To set for local configurations, add the property to the agent.conf file.

Agents with this property set to true mark cookies as HttpOnly to prevent scripts and third-party software from accessing them.

Default: true

Property: com.sun.identity.cookie.httponly

Multivalue for Pre-Authn Cookie

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

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

To set for local configurations, add the property to the agent.conf file.

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

When this property is set to 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 set to false, the agent creates a pre-authentication cookie for each authentication request to AM, with the name of agent-authn-tx-string. This is the default.

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

Property: org.forgerock.openam.agents.config.multivalue.pre.authn.cookies

Hot-swap: yes

SameSite Cookie Attribute

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

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

To set for local configurations, add the property to the agent.conf file.

When configured, the agent 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.

See the Same-Site Cookies Internet Draft for more information about the SameSite attribute and the possible values it can take.

Note

The attribute will not be set on certain browsers and circumstances, as per recommendation of The Chromium Project.

Default: Not set

Property: com.forgerock.agents.cdsso.cookie.samesite

Hot-swap: yes

Cross Domain SSO Properties

CDSSO Redirect URI

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.

For more information, see "Login Redirection and Login Conditional Redirection".

Default: agent/cdsso-oauth2

Hot-swap: yes

Property: com.sun.identity.agents.config.cdsso.redirect.uri

Cross Domain SSO (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

CDSSO is always enabled.

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

CDSSO Servlet URL (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

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

Cookie Domain List

List of domains, such as .example.com, in which cookies have to be set in CDSSO. If this property is left blank, 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

Property: com.sun.identity.agents.config.cdsso.cookie.domain[n]

Session Cookie Reset on Authentication Redirect

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

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

To set for local configurations, add the property to the agent.conf file.

When true, the agent does not reset the session cookie on an authentication redirect if there is a policy advice present.

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

Default: false

Property: org.forgerock.agents.config.cdsso.advice.cleanup.disable

Cookie Reset

Cookie Reset

When enabled, the web agent resets (blanks) cookies in the response before redirecting to authentication by issuing a Set-Cookie header to the client. An example of the header would be similar to the following:

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

If the com.sun.identity.agents.config.fqdn.default property is set, the web agent sets the cookie domain to the domain specified by the property. If it is not set, the web agent leaves the cookie domain blank.

Default: false

Property: com.sun.identity.agents.config.cookie.reset.enable

Cookie Reset Name List

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: not set

Property: com.sun.identity.agents.config.cookie.reset[n]

Login URL Properties

Custom Login Mode

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

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

To set for local configurations, add the property to the agent.conf file.

Specifies whether the agent uses a custom login mode to redirect unauthenticated users.

The custom login redirection mode requires AM 6 or later.

Possible values are:

• 0. Disabled. Default login redirection mode enabled.

• 1. Custom login redirection mode is enabled (Non-OIDC compliant login flow, standard flow). The agent tracks the user's authentication, converts the SSO token into an ID token at the end of the authentication flow, and then redirects the user to the originally requested resource. The SSO token name is given by Cookie Name.

• 2. Custom login redirection mode enabled (Non-OIDC compliant login flow, non-standard flow). The agent does not track the user's authentication, and redirects the user with a goto query parameter to the originally requested resource.

  This mode is used with the Accept SSO Token (com.forgerock.agents.accept.sso.token) property.

  Caution

  This feature is marked as evolving. Use it only when migrating from earlier versions of the agents. Contact ForgeRock if you suspect your environment has a similar use case.

For examples, related properties, and information on how to configure this property, see "Login Redirection and Login Conditional Redirection".

Note that if the Custom Login Mode property is set to a value other than 0, but the redirection URL contains the oauth2/authorize endpoint, the agent will use the default login redirection mode.

Default: 0

Property: org.forgerock.openam.agents.config.allow.custom.login

Hot-swap: yes

Public AM URL

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

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

To set for local configurations, add the property to the agent.conf file.

Specifies 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 both of the following points are true:

• Your environment uses custom login pages (non-OIDC-compliant flows), and the custom login pages are in a different domain than the agent.

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

Consider an example where the traffic between AM and the agent happens through the example-internal.com 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.

Default: not set

Property: com.forgerock.agents.public.am.url

Hot-swap: yes

AM Login URL

When configured, specifies the URL of a custom login page to which the agent redirects incoming users without sufficient credentials so that they can authenticate.

Important

When redirecting incoming login requests to a custom login page, you must add it to either the not-enforced URL or IP lists.

Before configuring this property, read "Login Redirection and Login Conditional Redirection".

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

• URL is the custom SSO-token-compliant login page to where the agent redirects the unauthenticated users.

• [?realm=realm_name?parameter1=/value1&...] specifies optional parameters that the agent will pass to the custom login page, for example, the AM realm which the user should log into.

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

  • The custom login page itself sets the realm parameter, for example, because it lets the user chose it. In this case, you must ensure the custom login page always appends a realm parameter to the goto URL.

  • The realm where the agent must log the user to has DNS aliases configured in AM.

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

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

  Even if you decide to 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.

  You can specify as many parameters your custom login pages require.

Example:

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

When the agent redirects the user to the custom login page, it appends a goto parameter (as configured in the Goto Parameter Name property) with the agent's CDSSO endpoint and a state parameter.

The example redirects from the agent to a custom login page:

http://login.example.com/login.jsp?realm=marketplace&goto=http%3A%2F%2Fagent.example.com%2Fcustom-login-response%3Fstate%3D3Df2fc384a07b7668e05fc6c26c01edf1bac8a3b55%26realm%3Dmarketplace

Note that the goto parameter is URL encoded. If the realm parameter is configured in the redirection rule, it is also appended to the goto parameter.

After the user has logged in, the custom login page must redirect back to the agent. To avoid redirection loops and login failures, consider the following constraints:

• Ensure that the custom login page redirects back to the agent using the URL contained in the goto parameter, and that the request contains the state parameter.

• Set the realm parameter in the redirection request to the agent if the users should not log in to AM's Top Level Realm.

  For example, you could use the realm specified in the redirection request from the agent to the custom login pages (if configured in the redirection property), or the custom login page can let the user chose to which realm authenticate to and add the realm parameter when redirecting to the agent.

  The example redirects from a custom login page to the agent with the realm added to it:

  http://agent.example.com/custom-login-response?state=3Df2fc384a07b7668e05fc6c26c01edf1bac8a3b55&realm=marketplace

  There is one exception; if the realm where the agent should log the user in to has a DNS alias configured, AM will log in the user to the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL will be logged in to the marketplace realm if the realm alias is set to marketplace.example.com, whether there is a realm parameter or not.

Default: AMURL/openam/UI/Login

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

Hot-swap: yes

AM Conditional Login URL

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

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

  To set for local configurations, add the property to the agent.conf file.

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

  Important

  When redirecting incoming login requests to a custom login page, you must add it to either the not-enforced URL or IP lists.

  Before configuring this property, read "Login Redirection and Login Conditional Redirection".

  If the FQDN Check property is enabled, the web agent iterates through the list of URLs until it finds an appropriate redirect URL that matches the FQDN check values. Otherwise, the web agent redirects the user to the URL configured in the conditional redirect rules.

  Conditional redirects have the following format, with no spaces between values:

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

  String

  Incoming login request URLs, with the following values:

  • Domain: Web agents match both the domain and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

    When you combine domain and path, you must provide the port number. For example, www.example.com:8080/market.

  • Subdomain: For example, example.com.

    When you combine subdomain and path, you must provide the port number. For example, example.com:8080/market.

  • Path: For example, /myapp.

  • Anything in the request URL: For example, a port, such as 8080.

  • No value: Nothing is specified before the | character. Conditional rules that do not specify the incoming request's domain apply to every incoming request.

  Note

  To specify the string as a regular expression, configure the following properties instead: Regular Expression Conditional Login Pattern and Regular Expression Conditional Login URL.

  URL, URL...

  The URL to which to redirect incoming login requests. The URL can be one of the following:

  • AM instance or site.

    Specify the URL of an AM instance or site in the format protocol://FQDN[:port]/URI/oauth2/authorize, where the port is optional if it is 80 or 443. For example, https://openam.example.com/openam/oauth2/authorize.

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

  • List of AM instances or sites, or websites other than AM

    If the redirection URL is not specified, the web agent redirects the request to the AM instance or site specified by the com.sun.identity.agents.config.naming.url bootstrap property.

  Important

  When using the default redirection login mode, ensure the Custom Login Mode property is set to 0.

  When using the custom redirection login mode, consider the following points:

  • The Custom Login Mode property must not be set to 0.

  • When the agent redirects the user to the custom login page, it appends a goto parameter (as configured in the Goto Parameter Name property) with the agent's CDSSO endpoint and a state parameter.

    The example redirects from the agent to a custom login page:

    http://login.example.com/login.jsp?realm=marketplace&goto=http%3A%2F%2Fagent.example.com%2Fcustom-login-response%3Fstate%3D3Df2fc384a07b7668e05fc6c26c01edf1bac8a3b55%26realm%3Dmarketplace

    Note that the goto parameter is URL encoded. If the realm parameter is configured in the redirection rule, it is also appended to the goto parameter.

    After the user has logged in, the custom login page must redirect back to the agent. To avoid redirection loops and login failures, consider the following constraints:

    • Ensure that the custom login page redirects back to the agent using the URL contained in the goto parameter, and that the request contains the state parameter.

    • Set the realm parameter in the redirection request to the agent if the users should not log in to AM's Top Level Realm.

      For example, you could use the realm specified in the redirection request from the agent to the custom login pages (if configured in the redirection property), or the custom login page can let the user chose to which realm authenticate to and add the realm parameter when redirecting to the agent.

      The example redirects from a custom login page to the agent with the realm added to it:

      http://agent.example.com/custom-login-response?state=3Df2fc384a07b7668e05fc6c26c01edf1bac8a3b55&realm=marketplace

      There is one exception; if the realm where the agent should log the user in to has a DNS alias configured, AM will log in the user to the realm whose DNS alias matches the incoming request URL. For example, an inbound request from the http://marketplace.example.com URL will be logged in to the marketplace realm if the realm alias is set to marketplace.example.com, whether there is a realm parameter or not.

  ?realm=/value

  The AM realm to where the agent should log the users. For example, ?realm=/marketplace.

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

  • The custom login page itself sets the realm parameter, for example, because it lets the user chose it. In this case, you must ensure the custom login page always appends a realm parameter to the goto URL.

  • The realm where the agent must log the user to has DNS aliases configured in AM.

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

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

  Even if you decide to 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.

  &module=value2&service=value3

  Parameters that can be added to the URL(s), such as:

  • module, which specifies the authentication module the user authenticates against. For example, ?module=myAuthModule.

  • service, which specifies an authentication chain or tree the user authenticates against. For example, ?service=myAuthChain.

  • Any other parameters your custom login pages require.

  Chain parameters with an & character, for example, realm=value&service=value.

  When configuring conditional login with multiple URLs, set up the parameters for each of the URLs.

  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

  Property: com.forgerock.agents.conditional.login.url[n]

  Hot-swap: Yes

Regular Expression Conditional Login URL

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

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

To set for local configurations, add the property to the agent.conf file.

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

Before configuring this property, read "Login Redirection and Login Conditional Redirection".

Regular expression conditional login URLs require two properties:

• Regular Expression Conditional Login Pattern: Specifies the regular expression that the domain name must match.

• org.forgerock.agents.config.conditional.login.url. Specifies the redirection URL and its parameters. Configure this property in the same way you would configure the AM Conditional Login URL property, except you do not specify the string or pipe | character.

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: not set

Properties:

org.forgerock.agents.config.conditional.login.pattern[n]

org.forgerock.agents.config.conditional.login.url[n]

Hot-swap: yes

Regular Expression Conditional Login Pattern

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

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

To set for local configurations, add the property to the agent.conf file.

See Regular Expression Conditional Login URL.

Agent Connection Timeout (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

Property: com.sun.identity.agents.config.auth.connection.timeout

Polling Period for Primary Server (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

Interval in minutes, agent polls to check the primary server is up and running.

Default: 5

Property: com.sun.identity.agents.config.poll.primary.server

Hot-swap: no

Logout URL Properties

Before configuring these properties, read "Logout Redirection".

AM Logout URL

Specifies the page the agent will redirect the end user to for log out. It can be a page in AM, such as https://openam.example.com:8443/openam/UI/Logout, or a page in the application.

The AM logout page will invalidate the user session in AM, but the page in the application may not be able to. See the Invalidate Logout Session property for configuration options.

Default: AM_URL/openam/UI/Logout

Property: com.sun.identity.agents.config.logout.url[n]

Hot-swap: yes

Disabled Logout Redirection

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

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

To set for local configurations, add the property to the agent.conf file.

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

Property: com.forgerock.agents.config.logout.redirect.disable

Hot-swap: yes

Agent Logout URL Properties

Before configuring these properties, read "Logout Redirection".

Logout URL List

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

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

Default: not set

Property: com.sun.identity.agents.config.agent.logout.url[n]

Hot-swap: yes

Agent Logout URL Regular Expression

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

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

To set for local configurations, add the property to the agent.conf file.

Specifies a Perl-compatible regular expression that matches logout URLs.

For example, to match URLs with protectedA or protectedB in the path and op=logout in the query string, use the following setting:

com.forgerock.agents.agent.logout.url.regex= \
    *(/protectedA\?|/protectedB\?/).*(\&op=logout\&)(.*|$)

When you use this property, the agent ignores the settings for Logout URL List.

Default: not set

Property: com.forgerock.agents.agent.logout.url.regex

Hot-swap: yes

Logout Cookies List for Reset

Cookies to be reset upon logout in the same format as the cookie reset list.

List of cookies to be reset upon logout in the format: name[=value][;Domain=value].

For example Cookie2=value;Domain=subdomain.domain.com, which equates to: com.sun.identity.agents.config.logout.cookie.reset[0]=Cookie2=value;Domain=subdomain.domain.com

Default: not set

Property: com.sun.identity.agents.config.logout.cookie.reset[n]

Hot-swap: yes

Logout Redirect URL

The end user gets redirected to this URL after logout, unless the Disabled Logout Redirection property is set to true. Configure alongside the Logout URL List property.

The URL you define in this property must be handled by your web server.

Default: not set

Property: com.sun.identity.agents.config.logout.redirect.url

Hot-swap: yes

Invalidate Logout Session

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

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

To set for local configurations, add the property to the agent.conf file.

During the logout flow, this property specifies whether the agent is responsible for invalidating the end user's session.

Possible values are:

• true. The agent invalidates the session in AM when redirecting to the logout URL.

  Use this value when the Logout URL List property is set to a page in your application, and your application does not handle the session invalidation process.

• false. The agent does not invalidate the session in AM when redirecting to the logout URL.

  Use this value in the following scenarios:

  • When the OpenAM Logout URL property is set to a SAML v2.0 single logout page in AM.

  • When the OpenAM Logout URL property is set to AM's end user pages.

  • When the OpenAM Logout URL property is set to a page in your application, and your application handles the session invalidation process.

Default: true

Property: org.forgerock.agents.config.logout.session.invalidate

Hot-swap: yes

Enable Regex for Logout URL List

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

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

To set for local configurations, add the property to the agent.conf file.

Allow regular expressions in Logout URL List.

Default: false

Property: org.forgerock.agents.config.logout.regex.enable

Hot-swap: yes

Policy Client Service Properties

Policy Cache Polling Period

Polling interval in minutes during which an entry remains valid after being added to the agent's cache.

Default: 3

Property: com.sun.identity.agents.config.policy.cache.polling.interval

Hot-swap: no

SSO Cache Polling Period

Polling interval in minutes during which an SSO entry remains valid after being added to the agent's cache.

Default: 3

Property: com.sun.identity.agents.config.sso.cache.polling.interval

Hot-swap: no

User ID Parameter

Agent sets this value for User ID passed in the session from AM to the REMOTE_USER server variable.

Default: UserToken

Property: com.sun.identity.agents.config.userid.param

User ID Parameter Type

User ID can be fetched from either SESSION or LDAP attributes.

Default: SESSION

Property: com.sun.identity.agents.config.userid.param.type

Fetch Policies From The Root Resource

When true, the agent caches the policy decision of the resource and all resources from the root of the resource down. For example, if the resource is http://host/a/b/c, then the root of the resource is http://host/. This setting can be useful when a client is expect to access multiple resources on the same path. Yet, caching can be expensive if very many policies are defined for the root resource.

Default: false

Property: com.sun.identity.agents.config.fetch.from.root.resource

Hot-swap: no

Retrieve Client Hostname

When enabled, get the client hostname through DNS reverse lookup for use in policy evaluation. This setting can impact performance.

Default: false

Property: com.sun.identity.agents.config.get.client.host.name

Policy Clock Skew

Time in seconds used adjust time difference between agent system and AM. Clock skew in seconds = AgentTime - AM ServerTime.

Use this property to adjust for small time differences encountered despite use of a time-synchronization service. When this property is not set and agent time is greater than AM server time, the agent can make policy calls to the AM server before the policy subject cache has expired, or you can see infinite redirection occur.

Default: 0

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

Hot-swap: no

Policy Evaluation Realm

In AM 6.5 and earlier versions, this property was named Realm.

Realm where AM evaluates polices for policy decision requests from the agent.

By default, AM evaluates policies in the top-level realm. Set this property to cause AM to use a different realm. This property is recognized by AM, not the agent.

Important

The policy set configured by Policy Set must exist in the realm configured by Policy Evaluation Realm. Otherwise, policy evaluation produces DENY results without writing warnings to the logs.

The default policy set exists only in the top-level realm. If you are using a different realm for policy evaluation, do one of the following:

• Create the iPlanetAMWebAgentService policy set in that realm.

• Create a different policy set in that realm, and configure Policy Set to use it.

Default: / (top-level realm)

Type: Map of application name:realm

Property: org.forgerock.openam.agents.config.policy.evaluation.realm

Hot-swap: Yes

Policy Set

In AM 6.5 and earlier versions, this property was named Application.

The name of the policy set where AM evaluates polices for policy decision requests from the agent.

By default, AM evaluates policies in iPlanetAMWebAgentService. Set this property to cause AM to use a different policy set. This property is recognized by AM, not the agent.

Important

The policy set configured by Policy Set must exist in the realm configured by Policy Evaluation Realm. Otherwise, policy evaluation produces DENY results without writing warnings to the logs.

The default policy set exists only in the top-level realm. If you are using a different realm for policy evaluation, do one of the following:

• Create the iPlanetAMWebAgentService policy set in that realm.

• Create a different policy set in that realm, and configure Policy Set to use it.

Default: iPlanetAMWebAgentService

Type: Map of application name:policy set

Property: org.forgerock.openam.agents.config.policy.evaluation.application

Hot-swap: Yes

Advice Handling Properties

Composite Advice Handling

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

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

To set for local configurations, add the property to the agent.conf file.

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

Default: false

Property: com.sun.am.use_redirect_for_advice

Composite Advice Encode

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

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

To set for local configurations, add the property to the agent.conf file.

Whether to based64 URL-encode composite advices before sending them to custom login endpoints. Set to true to increase the security, and protect against cross-site scripting attacks.

The following example is a request from the Agent to AM for a custom login page:

• When this property is false, advices are not encoded:

  http://mylogin.dom.com:80/mylogin?agent/custom-login-response=
  https://www.mydomain.com:443/agent/custom-login-response?state=b2e...bff
  &composite_advice=<Advices><AttributeValuePair><Attribute name="TransactionConditionAdvice"/><Value>05c...f6a</Value></AttributeValuePair></Advices>
  &original_request_url=https://www.mydomain.com:443/superweb

• When this property is true, advices are encoded as follows:

  http://mylogin.dom.com:80/mylogin?agent/custom-login-response=
  https://www.mydomain.com:443/agent/custom-login-response?state=b2e...bff
  &composite_advice=PEFkdm...zPg
  &original_request_url=https://www.mydomain.com:443/superweb

The following example is an OIDC request from the Agent to AM:

• When this property is false, advices are not encoded:

  http://am/server/oauth2/authorize?claims=
  {"id_token":{"acr":{"essential":true,"values":
  ["composite_advice: <Advices><AttributeValuePair><Attribute name="TransactionConditionAdvice"/><Value>05c...f6a</Value></AttributeValuePair></Advices>"]
  },"TxId":{"value":"05c...f6a"}}}
  &response_mode=form_post&state=b2e...bff
  &redirect_uri=https://www.mydomain.com:443/agent/cdsso-oauth2
  &response_type=id_token&scope=openid
  &client_id=myagent&agent_provider=true&agent_realm=/&nonce=6C6...C47

• When this property is true, advices are encoded:

  http://am/server/oauth2/authorize?claims=
  {"id_token":{"acr":{"essential":true,"values":
  ["composite_advice:PEFkdm...zPg"]
  },"TxId":{"value":"05c...f6a"}}}
  &response_mode=form_post&state=b2e...bff
  &redirect_uri=https://www.mydomain.com:443/agent/cdsso-oauth2
  &response_type=id_token&scope=openid
  &client_id=myagent&agent_provider=true&agent_realm=/&nonce=54B...909

Available: AM versions 5.5.3, 6.0.1, 6.5.3, and later

Default: false

Property: com.forgerock.agents.advice.b64.url.encode

Hot-swap: Yes

Locale

Agent Locale (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

The default locale for the agent.

Default: en_US

Property: com.sun.identity.agents.config.locale

Hot-swap: no

Anonymous User

Anonymous User

Enable or disable REMOTE_USER processing for anonymous users.

Default: false

Property: com.sun.identity.agents.config.anonymous.user.enable

Cookie Processing

Encode special characters in Cookies

When enabled, 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

Property: com.sun.identity.agents.config.encode.cookie.special.chars.enable

Profile Attributes Cookie Prefix

Sets cookie prefix in the attributes headers.

Default: HTTP_

Property: com.sun.identity.agents.config.profile.attribute.cookie.prefix

Profile Attributes Cookie Maxage

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

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

Property: com.sun.identity.agents.config.profile.attribute.cookie.maxage

URL Handling

URL Comparison Case Sensitivity Check

When enabled, enforces case insensitivity in both policy and not-enforced URL evaluation.

Default: true

Property: com.sun.identity.agents.config.url.comparison.case.ignore

Encode URL's Special Characters

When enabled, encodes the URL which has special characters before doing policy evaluation.

Default: false

Property:

Ignore Naming URL

Ignore Preferred Naming URL in Naming Request (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

When enabled, do not send a preferred naming URL in the naming request.

Default: true

Property: com.sun.identity.agents.config.ignore.preferred.naming.url

Invalid URL

Invalid URL Regular Expression

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

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

To set for local configurations, add the property to the agent.conf file.

Specifies a Perl-compatible regular expression to parse valid request URLs. The web agent rejects requests to invalid URLs with HTTP 403 Forbidden status without further processing.

For example, to filter out URLs containing a list of characters and words such as ./ /. / . %00-%1f, %7f-%ff, %25, %2B, %2C, %7E, .info, configure the following regular expression:

com.forgerock.agents.agent.invalid.url.regex=
^(\?!.\/|\/.|.|.info|%2B|%00-%1f|%7f-%ff|%25|%2C|%7E).*$

Default: not set

Property: com.forgerock.agents.agent.invalid.url.regex

Ignore Server Check

Ignore Server Check (deprecated)

 This property does not apply to Web Agents 5.8.2.1, although it may appear in the AM console.

When true, do not check whether AM is up before doing a 302 redirect.

Default: false

Property: com.sun.identity.agents.config.ignore.server.check

Ignore Path Info

Ignore Path Info in Request URL

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

Make sure therefore when this property is enabled that there is nothing following the wildcard in the not-enforced list or policy.

Note

The NGINX Plus web agent does not support this setting.

Default: false

Property: com.sun.identity.agents.config.ignore.path.info

Multi-Byte Enable Properties

Native Encoding of Profile Attributes (deprecated)

This property does not apply to Web Agents 5.8, although it may appear in the AM console.

When true, the agent encodes the LDAP header values in the default encoding of operating system locale. When disabled, the agent uses UTF-8.

Default: false

Property: com.sun.identity.agents.config.convert.mbyte.enable

Goto Parameter Name

Goto Parameter Name

Renames the goto parameter. The web 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

In this example, the URL appended to the goto2 parameter is the URL that the user tried to access when the web agent redirected the request to the accessDenied.html page. Note that you configure the access denied page using the Resources Access Denied URL (com.sun.identity.agents.config.access.denied.url) property.

The Goto Parameter Name property also affects the OpenAM Logout URL (com.sun.identity.agents.config.logout.url) property.

Default: goto

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

Hot-swap: yes

JSON-Formatted Response

URLs to Receive JSON-Formatted Responses

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

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

To set for local configurations, add the property to the agent.conf file.

Use wildcard patterns to specify a list of resource URLs that will trigger a JSON-formatted response from the agent, and optionally, override the default HTTP status code.

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

Returning the responses in JSON format is useful for non-browser-based, or AJAX applications, that may not want to redirect users to the AM user interface for authentication.

Tip

You should set the HTTP Return Code for JSON-Formatted Responses property to a supported HTTP code, for example 202, to prevent applications that do not support redirects, for example, from displaying a default error page.

For example, you could specify the following settings:

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

Performing a GET operation on a protected resource covered by the wildcard pattern would trigger a JSON response, as follows:

$  curl --include https://www.example.com/api/
HTTP/1.1 202 Accepted
Date: Tue, 29 Jan 2019 15:10:09 GMT
Server: Apache/2.4.6 (CentOS) OpenAM Web Agent/5.5.1.0
Set-Cookie: am-auth-jwt=; Path=/; Max-Age=0; Expires=Thu, 01-Jan-1970 00:00:00 GMT
Set-Cookie: agent-authn-tx=eJwN....XI34=; Path=/; HttpOnly; Max-Age=300; Expires=Tue, 29-Jan-2019 15:15:09 GMT
Content-Length: 418
Content-Type: text/html; charset=iso-8859-1

{
  "error": {
  "errors": [
    {
       "message": "redirect",
       "location": "https://openam.example.com:8443/openam/oauth2/authorize
       ?response_mode=form_post
       &state=d38a8b36-894e-4544-a5a1-d9230fb85246
       &redirect_uri=https%3A%2F%2Fwww.example.com%3A443%2Fagent%2Fcdsso-oauth2
       &response_type=id_token
       &scope=openid
       &client_id=myApacheAgent
       &agent_provider=true
       &agent_realm=%2F
       &nonce=531F....BB67"
    }
  ],
  "code": 302
  }
}

Notice that the HTTP result code is the specified 202 Accepted, and the JSON response contains the actual result, a 302 Found (redirect) to the AM server for authentication.

Default: not set

Property: org.forgerock.agents.config.json.url[n]

Headers and Values to Receive JSON-Formatted Responses

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

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

To set for local configurations, add the property to the agent.conf file.

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

Tip

You should set the HTTP Return Code for JSON-Formatted Responses property to a non-error HTTP code, for example 202, to prevent user agents displaying their default error pages.

For example, you could specify the following settings:

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

Performing a GET operation, and including the specified header, would trigger a JSON response, as follows:

$  curl --include --header "enableJsonResponse: true" https://www.example.com/endpoints/
HTTP/1.1 202 Accepted
Date: Tue, 29 Jan 2019 15:10:09 GMT
Server: Apache/2.4.6 (CentOS) OpenAM Web Agent/5.5.1.0
Set-Cookie: am-auth-jwt=; Path=/; Max-Age=0; Expires=Thu, 01-Jan-1970 00:00:00 GMT
Set-Cookie: agent-authn-tx=eJwN....EySX; Path=/; HttpOnly; Max-Age=300; Expires=Tue, 29-Jan-2019 15:30:19 GMT
Content-Type: text/html; charset=iso-8859-1

{
  "error": {
  "errors": [
    {
      "message": "redirect",
      "location": "https://openam.example.com:8443/openam/oauth2/authorize
      ?response_mode=form_post
      &state=d1e8b9e4-53c4-134a-bc6e-7b9c7f22e943
      &redirect_uri=https%3A%2F%2Fwww.example.com%3A443%2Fagent%2Fcdsso-oauth2
      &response_type=id_token
      &scope=openid
      &client_id=myApacheAgent
      &agent_provider=true
      &agent_realm=%2F
      &nonce=531F....BB67"
   }
  ],
  "code": 302
  }
}

Notice that the HTTP result code is the specified 202 Accepted, and the JSON response contains the actual result, a 302 Found (redirect) to the AM server for authentication.

Default: not set

Property: org.forgerock.agents.config.json.header[Header]=Value

Invert Properties That Receive JSON-Formatted Responses

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

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

To set for local configurations, add the property to the agent.conf file.

When true, invert the meaning of both the org.forgerock.agents.config.json.url and org.forgerock.agents.config.json.header properties.

When inverted, the specified values in those two properties do not trigger JSON-formatted responses. Only non-specified values trigger JSON-formatted responses.

Default: false

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

HTTP Return Code for JSON-Formatted Responses

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

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

To set for local configurations, add the property to the agent.conf file.

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

Tip

Set this property to a non-error HTTP code, for example 202, to prevent user agents displaying their default error pages.

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

Default: not set

Property: org.forgerock.agents.config.json.response.code

Miscellaneous Header-Related Properties

Add Cache-Control Headers

When true, enables teh use of Cache-Control headers that prevent proxies from caching resources accessed by unauthenticated users.

Default: false

Property: com.forgerock.agents.cache_control_header.enable

MIME-Encode HTTP Header Values

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

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

To set for local configurations, add the property to the agent.conf file.

MIME-encoding of HTTP header values:

• Not set or 0: The agent MIME-encodes the value of HTTP headers if said value is a multi-byte Unicode string.

• 1: The agent MIME-encodes the value of every HTTP header.

• 2. The agent does not MIME-encode the value of any HTTP header.

Default: not set

Property: com.forgerock.agents.header.mime.encode

Hot-swap: yes

Deprecated Properties

Anonymous User Default Value (deprecated)

User ID of unauthenticated users.

Default: anonymous

Property: com.sun.identity.agents.config.anonymous.user.id