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 Cache

Stored in the shared memory pool defined by the AM_MAX_SESSION_CACHE_SIZE environment variable, the session and policy cache stores session and policy information.

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 a JWT 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 policy decision, the agent reuses it without contacting AM.

• If there is no 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 Validity in Cache

Event	What is invalidated?
Session contained in the JWT 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 decision. 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.

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

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

To have the installer change the ownership of created directories to be the same User and Group as specified in the Apache configuration, specify the optional --changeOwner switch.

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

--changeOwner

Optionally have the installer change the ownership of created directories to be the same user that is running the selected IIS site.

--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/nginx15_agent/bin/../instances/agent_3/config/agent.conf;
openam_agent_instance 2
...
   location /customers {
   openam_agent on;
   openam_agent_configuration /web_agents/nginx15_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.

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

Specifies 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

Specifies a space-separated list of security protocols preceded by a dash - that will not be used when connecting to AM.

The supported protocols are the following:

• SSLv3

• TLSv1

• TLSv1.1

• TLSv1.2 (Default)

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

Default: -SSLv3 -TLSv1 -TLSv1.1

You can also change the default value by setting an environment variable, AM_SSL_OPTIONS. For more information, see "Configuring Web Agent Environment Variables".

Note

SSLv2 is disabled always regardless of setting.

org.forgerock.agents.init.retry.max

This is the maximum number of consecutive agent initialization retries.

Default: 0 (when not set)

org.forgerock.agents.init.retry.wait

This is the wait time in seconds between retries.

Default: 0 (when not set)

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

Set this to 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

Set this to 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

com.sun.identity.agents.config.naming.url

Specifies a space-separated list of AM URLs to which the web 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 of the list, it automatically connects to the next available URL. The agent will stay connected to the new URL until the URL fails, or the agent is restarted.

Default: AM_URL/openam/

Group, agentgroup

For assigning the agent to a previously configured web agent group in order to inherit selected properties from the group. Select Unassigned to remove the agent from a web agent group.

Password

Agent password used when creating the password file and when installing the agent.

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

Status

Status of the agent configuration.

Location of Agent Configuration Repository

Whether the agent's configuration is managed centrally through AM (centralized) or locally in the web agent configuration file (local).

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

Default: centralized

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

Agent Configuration Change Notification

Specifies whether AM sends a notification to the web agent to reread the agent profile after a change to a hot-swappable property. This property only applies 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

Specifies 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

Specifies the name of the cookie that holds the OpenID Connect JSON web token (JWT) on the user's browser.

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

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

• The name of this cookie 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 JWT 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

Enable Notifications

Specifies whether AM sends notifications to the web 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

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

Hot-swap: no

Agent Notification URL

This property does not apply to Web Agents 5.5, 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

Default: agent-root-URL/amagent

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

Hot-swap: yes

Configuration Reload Interval

Interval in minutes to fetch 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

This property does not apply to Web Agents 5.5, 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]

Enable Agent Keepalive Connections (Not yet in the AM console)^[5]

Specifies how the web agent connects to AM during the session validation process.

Session validation is a process composed of several requests going to and coming from AM. When this property is set to false, the agent opens a single connection to AM which is reused to satisfy every request required for a session, then closes it. When set to true, the agent opens and closes a connection for every request required when validating a session.

Setting this property to false reduces the overhead of opening and closing connections to AM. However, if you use load balancers or reverse proxy servers that do not allow applications to keep connections open, you must set this property to true.

Default: true

Property: org.forgerock.agents.config.keepalive.disable

SSO Only Mode

When enabled, the agent enforces authentication, so that upon verification of the user's identity, the user receives a session token.

When true , the web agent only manages 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, which is the default, the web agents will also manage user authorization, by using the policy engine in AM.

Tip

Sessions in AM have an idle timeout after which they expire. In general, when users access protected resources through an agent, the agent requests policy decision in behalf of that user, which resets the idle timeout.

If the agent is configured in SSO mode or if it does not need to ask AM for policy decision because it is already cached, the session may expire in AM due to idle timeout before the user logs out from the application.

To mitigate this issue, set the value of the SSO Caching Polling Period (com.sun.identity.agents.config.sso.cache.polling.interval) property to a value smaller than the one assigned for the session idle timeout in AM.

This way, the agent will poll AM about the session on behalf of the user before the session expires.

Default: false

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

Resources Access Denied URL

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

The following are not permitted in the URL:

• Wildcards

• The . directory specifier

• The .. directory specifier

Default: not set

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

Agent Debug Level

Default is Error. Increase to Message or even All for fine-grained detail.

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

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

Default: true

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

Agent Debug File Size

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

Default: 10000000

Hot-swap: no. This is a bootstrap property.

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

Local Agent Debug File Name (Not yet in the AM console)^[5]

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

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

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

Audit Access Types

Specfies the type of audit events to log. Valid values include:

• 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

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

Hot-swap: yes

Audit Log Location

Specifies the location where the web agent logs audit messages. Valid values include:

• 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

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

Hot-swap: yes

Remote Log Filename

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

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

Remote Audit Log Interval

Periodic interval in minutes in which audit log messages are sent to the remote log file.

Default: 5

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

Hot-swap: no

Rotate Local Audit Log

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

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

Local Audit Log Rotation Size

Specifies 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. This is a bootstrap property.

Local Agent Audit File Name (Not yet in the AM console)^[5]

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

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

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

FQDN Check

Enables checking of FQDN default value and FQDN map values.

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

Default: false

FQDN Default

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 any 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 servervirtual.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

Ignore Path Info for Not-Enforced URLs

When enabled, 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 about Ignore Path Info, see Ignore Path Info Properties.

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

Enable Regular Expressions for Not-Enforced URLs (Not yet in the AM console)^[5]

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 set to 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 enabled, 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 Client IP List

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

Default: not set

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

Note

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

Client IP Validation

When enabled, 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 List (Not yet in the AM console)^[5]

Specifies 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]

Enable Regular Expressions for Not-Enforced URLs from IP (Not yet in the AM console)^[5]

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 (Not yet in the AM console)^[5]

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

Default: false

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

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

Maps 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 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

Attribute Multi-Value Separator

Specifies 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 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 Name

Name of the SSO token cookie used between the AM server and the agent.

Default: iPlanetDirectoryPro

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

Hot-swap: no

Cookie Security

When enabled, the agent marks cookies secure, sending them only if the communication channel is secure.

Default: false

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

Hot-swap: no

HTTPOnly Mode (Not yet in the AM console)^[5]

Agents with this property set to true mark cookies as HTTPOnly to prevent scripts and third-party programs from accessing the cookies.

Default: false

Property: com.sun.identity.cookie.httponly

CDSSO Redirect URI

Specifies a URI the agent uses to process CDSSO requests.

Default:agent/cdsso-oauth2

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

Hot-swap: yes

Cross Domain SSO

This property does not apply to Web Agents 5.5, although it may appear in the AM console. CDSSO is always enabled.

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

CDSSO Servlet URL

This property does not apply to Web Agents 5.5, 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: not set

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

Session Cookie Reset on Authentication Redirect (Not yet in the AM console) ^[5]

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

By default, 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

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]

Allow Custom Login Mode (Not yet in the AM console)^[5]

Specifies whether the agent should use the default or the custom login mode when redirecting unauthenticated users.

Before configuring this property, ensure you have read "Redirection and Conditional Redirection".

Possible values are:

• false. Default login redirection mode enabled (OIDC compliant login flow). Use with the following properties:

  • OpenAM Conditional Login URL (com.forgerock.agents.conditional.login.url)

  • Regular Expression Conditional Login URL (org.forgerock.agents.config.conditional.login.pattern and org.forgerock.agents.config.conditional.login.url)

  Note that if the Allow Custom Login Mode property is set to true but the redirection URL contains the oauth2/authorize endpoint, the agent will use the default login redirection mode nevertheless.

• true. Custom login redirection mode enabled (Non-OIDC compliant login flow). Use with the following properties:

  • OpenAM Login URL (com.sun.identity.agents.config.login.url)

  • OpenAM Conditional Login URL (com.forgerock.agents.conditional.login.url)

  • Regular Expression Conditional Login URL (org.forgerock.agents.config.conditional.login.pattern and org.forgerock.agents.config.conditional.login.url)

Default: false

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

Hot-swap: yes

OpenAM 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, ensure you have read "Redirection and 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 DSN 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 com.sun.identity.agents.config.redirect.param property) with the agent's CDSSO endpoint and a state parameter.

The following is an example of a redirection 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.

Once 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:

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

• You must 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 following is an example of a redirection 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

OpenAM Conditional Login URL (Not yet in the AM console)^[5]

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, ensure you have read "Redirection and Conditional Redirection".

If the FQDN Check property (com.sun.identity.agents.config.fqdn.check.enable) 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 format [String]|[URL, URL...][?realm=value&module=value2&service=value3], with no spaces between values. Specify values in conditional redirects as follows:

• String

  Specifies the incoming log in request URL. It can take the following values:

  • A domain. For example, example.com.

    When you specify a domain in a conditional redirect, web agents match both the domain itself and its subdomains. For example, example.com matches mydomain.example.com and www.example.com.

    Domains can also include path information. For example, www.example.com/market.

  • A subdomain. For example, mydomain.example.com.

    Subdomains can include path information. For example, example.com/secure.

  • A path. For example, /myapp.

  • Anything else contained in the log in request URL. For example, a port, such as 8080.

  • No value, in which case 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 org.forgerock.agents.config.conditional.login.pattern and org.forgerock.agents.config.conditional.login.url properties instead.

• URL, URL...

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

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

  • A website other than AM.

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

  • A 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 org.forgerock.openam.agents.config.allow.custom.login property is set to false.

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

  • The org.forgerock.openam.agents.config.allow.custom.login property must be set to true.

  • When the agent redirects the user to the custom login page, it appends a goto parameter (as configured in the com.sun.identity.agents.config.redirect.param property) with the agent's CDSSO endpoint and a state parameter.

    The following is an example of a redirection 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.

    Once 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:

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

    • You must 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 following is an example of a redirection 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

  Specifies the AM realm to where the agent should log the users to. 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 DSN 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

  Specifies 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[2]=sales.example.com/marketplace|?realm=marketplace
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 yet in the AM console)^[5]

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, ensure you have read "Redirection and Conditional Redirection".

Regular expression conditional login URLs require two properties:

• org.forgerock.agents.config.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 OpenAM Conditional Login URL (com.forgerock.agents.conditional.login.url) property, except you do not specify the string.

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

Agent Connection Timeout

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

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

Polling Period for Primary Server

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

OpenAM Logout URL

AM logout page URLs, such as http://openam.example.com:8080/openam/UI/Logout.

Default: AM_URL/openam/UI/Logout

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

Hot-swap: yes

Enable Logout URL Redirect (Not yet in the AM console)^[5]

When disabled, instead of redirecting the user-agent, the web agent performs session logout in the background and then continues processing access to the current URL.

Default: enabled

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

Hot-swap: yes

Logout URL List

List of application logout URLs, such as http://www.example.com/logout.html. The user is logged out of the AM session when these URLs are accessed. When using this property, specify a value for the Logout Redirect URL property.

Default: not set

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

Hot-swap: yes

Agent Logout URL Regular Expression (Not yet in the AM console)^[5]

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

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

User gets redirected to this URL after logout. Specify this property alongside a Logout URL List.

Default: not set

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

Hot-swap: yes

Invalidate Logout Session

Specifies whether the agent must invalidate the user session in AM when redirecting to the logout URL specified either by the Logout URL list (com.sun.identity.agents.config.agent.logout.url) or the AM logout URL (com.sun.identity.agents.config.logout.url) properties.

Possible values are:

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

  Use this value when the com.sun.identity.agents.config.agent.logout.url 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 com.sun.identity.agents.config.logout.url property is set to a SAML v2.0 single logout page in AM.

  • When your application uses AM's end user pages. In this case, the com.sun.identity.agents.config.logout.url property is set to AM's logout page and the com.sun.identity.agents.config.agent.logout.url property is not set.

  • When the com.sun.identity.agents.config.agent.logout.url property is set to a page in your application, and your application handles the session invalidation process.

Default: true

Property: com.sun.identity.agents.config.logout.session.invalidate

Hot-swap: yes

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.

Tip

Sessions in AM have an idle timeout after which they expire. In general, when users access protected resources through an agent, the agent requests policy decision in behalf of that user, which resets the idle timeout.

If the agent is configured in SSO mode or if it does not need to ask AM for policy decision because it is already cached, the session may expire in AM due to idle timeout before the user logs out from the application.

To mitigate this issue, set the value of the SSO Caching Polling Period (com.sun.identity.agents.config.sso.cache.polling.interval) property to a value smaller than the one assigned for the session idle timeout in AM.

This way, the agent will poll AM about the session on behalf of the user before the session expires.

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

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

Realm

Realm where AM starts policy evaluation for this web agent.

Edit this property when AM should start policy evaluation in a realm other than the top-level realm, /, when handling policy decision requests from this web agent.

This property is recognized by AM, not the web agent, and does not support realm aliases.

Default: / (top-level realm)

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

Hot-swap: yes

Application

Application where AM looks for policies to evaluate for this web agent.

Edit this property when AM should look for policies that belong to an application other than iPlanetAMWebAgentService when handling policy decision requests from this web agent.

This property is recognized by AM, not the web agent.

Default: iPlanetAMWebAgentService

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

Hot-swap: yes

Composite Advice Handling (Not yet in the AM console)^[5]

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

Agent Locale

The default locale for the agent.

Default: en_US

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

Hot-swap: no

Anonymous User

Enable or disable REMOTE_USER processing for anonymous users.

Default: false

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

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

Maximum age in seconds of custom cookie headers.

Default: 300

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

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: com.sun.identity.agents.config.encode.url.special.chars.enable

Ignore Preferred Naming URL in Naming Request

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 Regular Expression (Not yet in the AM console)^[5]

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

Ignore Server Check

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

Native Encoding of Profile Attributes

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

Allows to rename 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

CA Certificate File Name (Not yet in the AM console)^[5]

Set this property to the file name that contains one or more CA certificates. The file should be Privacy Enhanced Mail (PEM) encoded. AM requires PEM files to be base64-encoded ASCII data.

When using the Windows built-in Secure Channel API, set this property to the friendly name of the CA certificate file as it appears in the certificates snap-in. For example, the friendly name of the imported CA certificate in the image below is openam.example.com.

CA Friendly Name in the Windows Certificates Snap-in

You must set this property if com.sun.identity.agents.config.trust.server.certs is set to false.

Important

If you are using the Windows built-in Secure Channel API but your environment does not require client authentication, configure the following properties:

com.forgerock.agents.config.cert.ca.file =
com.forgerock.agents.config.cert.file = CA-cert-friendly-name
com.sun.identity.agents.config.trust.server.certs = false

Default: not set

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

Public Client Certificate File Name (Not yet in the AM console)^[5]

When AM is configured to perform client authentication, set this property to the name of the file that contains the public PEM-encoded client certificate that corresponds with the private key specified in com.forgerock.agents.config.cert.key.

When using the Windows built-in Secure Channel API, you can set this property to either the friendly name of the certificate file as it appears in the certificates snap-in, or the name of the file containing the client certificate in PKCS#12/PFX format.

To use a client certificate file in PKCS#12/PFX format:

1. Obtain your client certificate, ensuring the signing chain is intact, and that the key and CA certificate are included.

2. Run the agentadmin tool to generate an encrypted password for the certificate file:

   C:\> cd web_agents\iis_agent\bin
   C:\path\to\web_agents\iis_agent\bin> agentadmin.exe --p "Encryption Key" "Certificate File Password"
   
   Encrypted password value: zck+6RKqjtc=

   The value used for Encryption Key comes from the com.sun.identity.agents.config.key property. The value of Certificate File Password should be the password required to access the client certificate file.

3. Use the encrypted password value in the agent configuration file as follows:

   com.forgerock.agents.config.cert.file=C:\Certificates\myClientCertificate.pfx
   com.forgerock.agents.config.cert.key=
   com.forgerock.agents.config.cert.key.password=zck+6RKqjtc=
   com.sun.identity.agents.config.trust.server.certs=false

4. Restart the agent.

If you do not want to use a file directly, enter the friendly name of the certificate as the value of the com.forgerock.agents.config.cert.file property instead. As an example, the friendly name of the imported certificate in the image below is openam.example.com.

Friendly Name in the Windows Certificates Snap-in

Default: not set

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

Private Client Certificate File Name (Not yet in the AM console)^[5]

Set this property to the name of the file that contains the private key. On UNIX systems, that key should be encoded in PEM format.

On Windows systems, that entry depends. If SSL mutual authentication is required with AM, that entry should contain the name of the private key or certificate imported in the Windows Certificate Manager, part of the Microsoft Management Console. For a web server, that should point to the Local Machine or Service certificate store, depending on the account associated with the Web server.

Default: not set

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

Private Key Password (Not yet in the AM console)^[5]

Set this property to the obfuscated private key password. Obfuscate the password by using agentadmin --p, as demonstrated in the following example to generate the value:

Unix example:

$ cd /web_agents/agent-type/bin
$ ./agentadmin --p "key" "`cat newpassword.file`"

Here, agent-type corresponds to the file system directory for the particular agent type, such as apache24_agent, newpassword.file is a file containing the private key password, and key is the obfuscation key as specified by com.sun.identity.agents.config.key.

Windows example:

C:\>cd c:\web_agents\agent-type\bin
C:\path\to\web_agents\bin\>agentadmin.exe --p "key" "newpassword"

Here, agent-type corresponds to the file system directory for the particular agent type, such as apache24_agent, newpassword is the new private key password, and key is the obfuscation key as specified by com.sun.identity.agents.config.key.

Tip

You can generate a new obfuscation key by using agentadmin --k.

This property is not used on Microsoft Windows systems.

Default: not set

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

Supported Cipher List (Not yet in the AM console)^[5]

Set this property to a list of ciphers to support. The list consists of one or more cipher strings separated by colons, as defined in the man page for ciphers available at http://www.openssl.org/docs/apps/ciphers.html.

Default: HIGH:MEDIUM

Property: com.forgerock.agents.config.ciphers

AM SSL Certificate Verification (Not yet in the AM console)^[5]

When SSL is configured, set to false to trust the AM SSL certificate only if the certificate is found to be correct and valid. Default is true to make it easy to try SSL during evaluation.

Important

The default setting, true, means that the web agent trusts all server certificates. Change this to false, and test that your web agent can trust server certificates before deploying the web agent in production.

Default: true

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

Use OpenSSL for Secure Communications (Not yet in the AM console)^[5]

On Windows operating systems, web agents use the built-in Secure Channel API for SSL/TLS communications. Set this property to true to disable the built-in Secure Channel API and use OpenSSL instead.

The org.forgerock.agents.config.secure.channel.disable property must be set in the /web_agents/agent_type/instances/Agent_nnn/config/agent.conf file under the Bootstrap Properties section.

Default: false

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

OpenSSL Certificate Verification Depth (Not yet in the AM console)^[5]

Specifies the certificate verification depth for OpenSSL. The supported format is a number between 0 and 9, as specified in the OpenSSL man pages.

To turn off server certification validation, set the com.sun.identity.agents.config.trust.server.certs property to true.

Default: 9

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

URLs to Receive JSON-Formatted Responses (Not yet in the AM console)^[5]

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 yet in the AM console)^[5]

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-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=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 yet in the AM console)^[5]

Set to true to 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 will not trigger JSON-formatted responses. Any non-specified value will trigger JSON-formatted responses, instead.

Default: false (not set)

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

HTTP Return Code for JSON-Formatted Responses (Not yet in the AM console)^[5]

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

Tip

You should 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

Add Cache-Control Headers (Not yet in the AM console)^[5]

Set this property to true to enable 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

Anonymous User Default Value

User ID of unauthenticated users.

Default: anonymous

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

If the agent is behind a proxy or load balancer, then the agent can get client IP and host name values from the proxy or load balancer. For proxies and load balancer that support providing the client IP and host name in HTTP headers, you can use the following properties.

When multiple proxies or load balancers sit in the request path, the header values can include a comma-separated list of values with the first value representing the client, as in client,next-proxy,first-proxy.

Client IP Address Header

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

Default: not set

Property: com.sun.identity.agents.config.client.ip.header

Client Hostname Header

HTTP header name that holds the hostname of the client.

Default: not set

Property: com.sun.identity.agents.config.client.hostname.header

Load Balancer Setup

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

Property: com.sun.identity.agents.config.load.balancer.enable

Override Request URL Protocol

Enable if the agent is sitting behind a SSL/TLS off-loader, load balancer, or proxy such that the protocol users use is different from the protocol the agent uses. When enabled, the protocol is overridden with the value from the Agent Deployment URI Prefix (property: com.sun.identity.agents.config.agenturi.prefix).

Default: false

Property: com.sun.identity.agents.config.override.protocol

Override Request URL Host

Enable if the agent is sitting behind a SSL/TLS off-loader, load balancer, or proxy such that the host name users use is different from the host name the agent uses. When enabled, the host is overridden with the value from the Agent Deployment URI Prefix (property: com.sun.identity.agents.config.agenturi.prefix).

Default: false

Property: com.sun.identity.agents.config.override.host

Override Request URL Port

Enable if the agent is sitting behind a SSL/TLS off-loader, load balancer, or proxy such that the port users use is different from the port the agent uses. When enabled, the port is overridden with the value from the Agent Deployment URI Prefix (property: com.sun.identity.agents.config.agenturi.prefix).

Default: false

Property: com.sun.identity.agents.config.override.port

Override Notification URL

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

Default: false

Property: com.sun.identity.agents.config.override.notification.url

Forward Proxy Host Name (Not yet in the AM console)^[5]

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

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

Forward Proxy Port Number (Not yet in the AM console)^[5]

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

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

Forward Proxy User Name (Not yet in the AM console)^[5]

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

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

Forward Proxy Password (Not yet in the AM console)^[5]

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

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

POST Data Preservation

Enables HTTP POST data preservation.

Default: false

Property: com.sun.identity.agents.config.postdata.preserve.enable

POST Data Entries Cache Period

POST cache entry lifetime in minutes.

Default: 10

Property: com.sun.identity.agents.config.postcache.entry.lifetime

POST Data Sticky Load Balancing Mode (Not yet in the AM console)^[5]

Specifies whether to create a cookie, or to append a query string to the URL to assist with sticky load balancing. Possible values are:

• COOKIE. The web agent creates a cookie with the value specified in the com.sun.identity.agents.config.postdata.preserve.stickysession.value property.

• URL. The web agent appends the value specified in the com.sun.identity.agents.config.postdata.preserve.stickysession.value to the URL query string.

Default: not set

com.sun.identity.agents.config.postdata.preserve.stickysession.mode

POST Data Sticky Load Balancing Value (Not yet in the AM console)^[5]

Specifies a key-value pair separated by the = character that the web agent creates when evaluating the com.sun.identity.agents.config.postdata.preserve.stickysession.mode property.

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

When configuring POST data preservation with cookies, set the cookie name in the cookie pair to the same value configured in the com.sun.identity.agents.config.postdata.preserve.lbcookie property.

Default: not set

Property: com.sun.identity.agents.config.postdata.preserve.stickysession.value

POST Data Sticky Load Balancing Cookie Name (Not yet in the AM console)^[5]

Specifies the name of a cookie to use for enabling sticky load balancing when the com.sun.identity.agents.config.postdata.preserve.stickysession.mode property is set to COOKIE.

Set the cookie name to the same value configured in the com.sun.identity.agents.config.postdata.preserve.stickysession.value property.

Default: not set

Property: com.sun.identity.agents.config.postdata.preserve.lbcookie

POST Data Storage Directory (Not yet in the AM console)^[5]

The directory local to the agent installation where the agent writes preserved POST data while requesting authorization to AM.

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_type/log

Property: org.forgerock.agents.config.postdata.preserve.dir

Submit POST Data using JavaScript (Not yet in the AM console)^[5]

When set to true, preserved POST data will be resubmitted to the destination server after authentication by using JavaScript.

Default: false

Property: org.forgerock.agents.pdp.javascript.repost

URLs Ignored by the Agent POST Data Inspector (Not yet in the AM console)^[5]

Specifies a list of URLs that will not be processed by the web agent POST data inspector. This allows other modules on the same server to access the POST data directly.

The following example uses wildcards to add a file named postreader.jsp in the root of any protected website to the list of URLs that will not have their POST data inspected: org.forgerock.agents.config.skip.post.url[0]=http*://*:*/postreader.jsp

Note

Any URLs added to this property should also be added to the Not-Enforced URLs ( com.sun.identity.agents.config.notenforced.url) property. See Not-enforced URL Processing Properties.

Default: not set

Property: org.forgerock.agents.config.skip.post.url[n]

Override Proxy Server's Host and Port

When enabled ignore the host and port settings.

Default: false

Property: com.sun.identity.agents.config.proxy.override.host.port

Hot-swap: no

Authentication Type

The agent should normally perform authentication, so this is not required. If necessary, set to none.

Default: not set

Property: com.sun.identity.agents.config.iis.auth.type

Hot-swap: no

Replay Password Key

DES key for decrypting the basic authentication password in the session.

Default: not set

Property: com.sun.identity.agents.config.replaypasswd.key

Filter Priority

The loading priority of filter, DEFAULT, HIGH, LOW, or MEDIUM.

Default: HIGH

Property: com.sun.identity.agents.config.iis.filter.priority

Filter configured with OWA

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

Property: com.sun.identity.agents.config.iis.owa.enable

Change URL Protocol to HTTPS

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

Property: com.sun.identity.agents.config.iis.owa.enable.change.protocol

Idle Session Timeout Page URL

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

Property: com.sun.identity.agents.config.iis.owa.enable.session.timeout.url

Show Password in HTTP Header

Set to true if encrypted password should be set in HTTP header AUTH_PASSWORD.

Default: false

Property:com.sun.identity.agents.config.iis.password.header

Logon and Impersonation

Set to true if agent should do Windows Logon and User Impersonation.

Default: false

Property: com.sun.identity.agents.config.iis.logonuser

Check User in Domino Database

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

Default: false

Property: com.sun.identity.agents.config.domino.check.name.database

Use LTPA token

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

Default: false

Property: com.sun.identity.agents.config.domino.ltpa.enable

LTPA Token Cookie Name

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

Default: LtpaToken

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

LTPA Token Configuration Name

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

Default: LtpaToken

Property: com.sun.identity.agents.config.domino.ltpa.config.name

LTPA Token Organization Name

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

Default: not set

Property: com.sun.identity.agents.config.domino.ltpa.org.name

Custom Properties

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

• customproperty=custom-value1

• customlist[0]=customlist-value-0

• customlist[1]=customlist-value-1

• custommap[key1]=custommap-value-1

• custommap[key2]=custommap-value-2

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

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

AM_SYSTEM_LOG_LEVEL

Specifies the log level of garbage collector statistics for all web agents instances in the container. The logs are written into the /web_agents/agent_type/log/system_n.log file, where n indicates the agent group number.

Consider an environment with two Apache server installations:

• Apache_1 has two agent instances configured, agent_1 and agent_2, configured to share runtime resources (AmAgentId is set to 0). Both agent instances will write to the syslog_0.log file.

• Apache_2 has one agent instance configured, agent_3, with AmAgentId set to 1. The instance will write to the syslog_1.log file.

The system_n.log file can contain the following information:

• Agent version information, written when the agent instance starts up.

• Logs for the agent background processes.

• WebSocket connection errors.

• Cache stats and removal of old POST data preservation files.

• Agent notifications.

The default value of the AM_SYSTEM_LOG_LEVEL variable is Error. Increase it to Message or All for fine-grained detail.

Valid values for the variable are:

• All

• Error

• Info

• Message

• Warning

AM_MAX_SESSION_CACHE_SIZE

Specifies the maximum size of shared memory for the session and policy cache, in bytes. When unset, the session cache size is 16777216 bytes (16 MB). The maximum size the cache can grow is 1073741824 bytes (1 GB), and the minimum size is 1024 bytes (1 MB).

Setting the variable to 0 configures a cache size of 16777216 bytes (16 MB).

You may need to increase the size of the session and policy cache if you plan to hold many active sessions at any given time.

AM_RESOURCE_PERMISSIONS

(Unix only) Specifies the permissions that the agent sets for its runtime resources. Possible values are:

• 0600

• 0660

• 0666

The AM_RESOURCE_PERMISSIONS environment variable requires the umask value to allow these permissions for the files.

Consider an example where the Apache agent is running with the apache user. The umask value is set to 0022 and the AM_RESOURCE_PERMISSIONS environment variable is set to 0666. The agent runtime resources will have the following permissions:

Resource Permissions Example in Linux

Resource	Permission	Owner
/path/to/web_agents/agent_type/log/system_n.log	644	apache
/path/to/web_agents/agent_type/log/monitor_n.log	644	apache
/path/to/web_agents/agent_type/instances/agent_n/conf/agent.conf	640	apache
/path/to/web_agents/agent_type/instances/agent_n/logs/debug/debug.log	644	apache
/dev/shm/am_cache_0	644	apache
/dev/shm/am_log_data_0	644	apache

Any semaphores owned by the apache user have 644 permissions as well.

Consider another example where umask is set to 0002 and the AM_RESOURCE_PERMISSIONS environment variable is set to 0666. The files would be created with 664 permissions, which would allow the files to be read and written by the members of the group, as well.

AM_MAX_AGENTS

Specifies the maximum number of agent instances in the installation. The higher the number, the more shared memory the agent reserves. The default value is 32.

If the number of web agent instances in the installation surpasses this limit, the agent instance starting over the limit logs an error message and does not protect the resources.

AM_NET_TIMEOUT

Specifies the timeout in seconds for the agent installer to contact AM during agent configuration validation. If not set, the default 4 seconds will be used.

For example, if the installer contacts AM to validate an agent configuration that lasts longer than 4 seconds, the installation will fail due to the default timeout of 4 seconds. You can extend this timeout by setting this environment variable.

AM_SSL_OPTIONS

Overrides the default SSL/TLS protocols for the agent, set in the org.forgerock.agents.config.tls bootstrap property (for more information, see Bootstrap Properties).

Specifies a space-separated list of security protocols preceded by a dash - that will not be used when connecting to AM.

The supported protocols are the following:

• SSLv3

• TLSv1

• TLSv1.1

• TLSv1.2 (Default)

For example, to configure TLSv1.1, set the environment variable to AM_SSL_OPTIONS = -SSLv3 -TLSv1 -TLSv1.2.