Tips and feature insights for Web Policy Agents 4.x

Installation

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.

SSL

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: com.forgerock.agents.config.cert.ca.file = 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:

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:

• A new agent.conf file has been introduced, which now contains all the agent bootstrap and configuration properties. This file replaces OpenSSOAgentBootstrap.properties and OpenSSOAgentConfiguration.properties. See OpenAM Web Policy Agent 4 Release Notes › Important Changes to Existing Functionality for further information.
• A new debug.log file has been introduced, which replaces the amAgent debug log. See How do I enable debug logging for troubleshooting Agents (All versions)? for further information on raising the debug logging level.

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.

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

N/A

Related Issue Tracker IDs

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