Best Practice

Tips and feature insights for Web Policy Agents 4.x

Last updated Jan 5, 2021

The purpose of this article is to provide tips and feature insights introduced in Web Policy Agents 4.x It is recommended that you read this article prior to installing and using web policy agents 4.x. You should also refer to the product documentation.

1 reader recommends this article


This article has been archived and is no longer maintained by ForgeRock.



You should upgrade to Web policy agent 4.2, which includes fixes to a number of known issues; you can download this from BackStage.

The installation process for IIS web policy agents 4.x is different to previous versions. You should use the agentadmin tool to install and configure your IIS policy agents. This tool is located in the /path/to/policy_agent/bin directory. If you run agentadmin without any options (as an administrator), it will return a full list of possible commands. 

See Web Policy Agent Guide › Installing Web Policy Agents 4.2 in Microsoft IIS for further information on using agentadmin to install your IIS policy agents.


See How do I upgrade to Web Policy Agent 4.x from a previous version? for information on upgrading from a previous version.


Web policy agents no longer include independent NSS/NSPR libraries for handling SSL.

If you use SSL between the the policy agent and AM/OpenAM, you should firstly ensure OpenSSL is available prior to installing the policy agent. See OpenAM Web Policy Agent 4 Release Notes › Important Changes to Existing Functionality for further information. If you are using Microsoft® Windows®, you can use the native Schannel for SSL communication as of Web policy agent 4.1; see Web Policy Agent Release Notes › New Features in 4.1 for further information.

Secondly, the approach needed to install the policy agent depends on your use case as follows:

  • HTTPS  only communication between the policy agent and AM/OpenAM server (without certificate authentication) - the agentadmin tool will handle this scenario without any additional setup as agentadmin trusts all available server certificates.
  • HTTPS only communication but with mutual ssl-auth enabled in AM/OpenAM (with certificate authentication) - you can use one of the following approaches:
    • Configure environment variables - you will need to configure the following environment variables in your operating system prior to installation: AM_SSL_KEY - path to a private key file (pem encoded) AM_SSL_PASSWORD - password for a private key (if set)  AM_SSL_CERT - path to a public key file (certificate; pem encoded) AM_SSL_CA - path to a CA certs file (pem encoded) Optionally, you can also set the following environment variables: AM_SSL_CIPHERS - cipher suites used in SSL handshake (similar to the SSLCipherSuite directive in mod_ssl) AM_SSL_OPTIONS  - disable SSL/TLS handling in OpenSSL for one or more versions (by using the following possible values: -SSLv3 -TLSv1 -TLSv1.1 -TLSv1.2)  The settings you specify are automatically transferred to the agent.conf file. You can then proceed with the installation.
    • Use the agentadmin tool - alternatively, you can use the --forceinstall option to install the policy agent.   agentadmin --forceInstall The following encryption properties (that correspond to the AM_SSL_ environment variables) can then be set in the agent.conf file after installation: = AM_SSL_CA com.forgerock.agents.config.cert.file = AM_SSL_CERT com.forgerock.agents.config.cert.key = AM_SSL_KEY com.forgerock.agents.config.cert.key.password = AM_SSL_PASSWORD com.forgerock.agents.config.ciphers = AM_SSL_CIPHERS org.forgerock.agents.config.tls = AM_SSL_OPTIONS

Load balancers and reverse proxies

By default, both web policy agent 4.x and the agentadmin tool use long running connections with keep alives when communicating with AM/OpenAM (for login and policy processing). This can cause issues if there is a load balancer or reverse proxy between the policy agent and AM/OpenAM server.

If you use a load balancer or reverse proxy, you should add the following setting to the agent.conf file after installation:

org.forgerock.agents.config.keepalive.disable = true

This setting will switch off the long running socket connection and allow the connections to work as expected within a reverse proxy / load balanced environment.

New files and locations

The following new files have been introduced as part of the changes made for web policy agents 4.x:

Configuration and log files are now specific to the instance (each virtual host and IIS application will have its own instance). The relevant paths for these files are now as follows:

  • agent.conf - /path/to/policy_agent/instances/agent_n/config directory.
  • debug.log - /path/to/policy_agent/instances/agent_n/logs/debug directory.
  • audit.log - /path/to/policy_agent/instances/agent_n/logs/audit directory.

Shared Memory Files 

Shared memory files are stored in the following locations depending on which operating system you are using:

  • Microsoft® Windows® - c:\....webagent....\iis_agent\lib\ folder.
  • Unix® and Linux® - /dev/shm/ directory.
  • Solaris® - /tmp/ directory.

If the web policy agent crashes, it will try to recover (remove) the shared memory files on its own. If it is unable to recover by itself, you will need to manually remove the shared memory files from the relevant location and then restart the web server.

Virtual Hosts support in Apache™

Web policy agents 4.x support installing policy agents into multiple virtual hosts on Apache web servers. Each virtual host has its own web policy agent configuration. However, the installer cannot add more than one configuration into httpd.conf file; this needs to be done manually.

You should follow the instructions given in Web Policy Agent Guide › Installing Apache Web Policy Agents into a Virtual Host to correctly install policy agents into multiple virtual hosts.


Once you have installed your multiple policy agent instances, you can switch an agent instance off by changing AmAgent On for the relevant agent instance to AmAgent Off in the httpd.conf file.

IIS policy agents

IIS policy agents now support multiple worker processes, application pools, restarts and recycles. However, you must not mix 32bit and 64bit agent instances on the same IIS server or within the same Microsoft® Windows® server instance unless you are using IIS policy agent 4.1, which does support this. 

Each IIS site has a bindings table, where you can configure server names and port details for a site; these values must correspond to the policy agent FQDN/cookie domain for that site.

IIS can sometimes lock one or more configuration sections in the IIS Manager (under Site > Management > Configuration), which will cause issues with the installation. This typically happens if an earlier installation was terminated. You can resolve this issue by ensuring all configuration sections are unlocked. 

Refer to Web Policy Agent User's Guide › To disable and enable a web policy agent in an IIS site for further information on enabling or disabling agent instances in IIS.

Reverting IIS configuration

You can revert the IIS configuration to a pre-policy agent state as follows:

  1. Remove agent instances using the following command for each agent instance: C:\> agentadmin.exe --r agent_1
  2. Delete all agent instances from IIS using the following command: C:\> agentadmin.exe --g
  3. Enter the following command to reset IIS completely: C:\> iisreset

Alternatively, you can revert the IIS configuration from the IIS Manager as follows:

  1. Remove the agent instance from the Site > Modules list.
  2. Remove the agent instance from the Global Configuration > Modules > Configure Native Modules list.​

Other information

You should also be aware of the following when you are using the new web policy agents:

  • You can have a maximum of 32 policy agent installs.
  • The shared cache maximum size is limited to 2GB. This is the absolute limit of all of the dynamic cache resizes. You can reduce the limit if required by setting the following environment variable in your operating system: AM_MAX_SHARED_POOL_SIZE
  • The cache entry TTL (the overall use of the cache) depends on each particular session and its maxcaching/timeleft values. In the event of the cache entry being valid (within TTL range) and no notification being received, the policy agent will always use the cached entry.
  • Policy requests are limited to a maximum of three retries with a two second wait in between (in case of a communication or any other failure).
  • The Agent POST Data Preservation (PDP) module supports arbitrary data. See Web Policy Agent Guide › Configuring Web Policy Agent Advanced Properties for further information. This can be replayed with one of the following:
    • with http-form-reposts in the Agent Filter module (as per web policy agents 3.x).
    • with the help of the inline JavaScript® Repost module.
  • You can now configure JSON-only responses (JSON status / message) as an alternative to the generic HTTP 302 redirect message. This can be configured with the new org.forgerock.agents.config.json.url property as described in Web Policy Agent Guide › JSON-Formatted Response Properties.
  • You should not use the Path Info properties. All policies' not-enforced rules must be written in a form that supports the real request URL, rather than one de-(or re-)composed from a pathinfo value.

See Also

What versions of Agents are compatible with AM?

How do I silently remove a Web Agent (All versions)?

Best practice for installing IIS Web Agents (All versions)

FAQ: Configuring Agents in Identity Cloud and AM

Agents and policies in AM

Troubleshooting AM and Agents

Web Policy Agent 4.2 Release Notes

Web Policy Agent 4.2 Guide

Web Policy Agent 4.1 Release Notes

Web Policy Agent 4.1 Guide

OpenAM Web Policy Agent 4 Release Notes

OpenAM Web Policy Agent 4 User's Guide

Related Training


Related Issue Tracker IDs

AMAGENTS-52 (WPA on Windows should be able to use Schannel for SSL/TLS communication)

Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.