Readme for Web Policy Agent 4.1.0-40 patch

Last updated Jan 5, 2021

The purpose of this article is to provide specific guidance on installing the Web Policy Agent 4.1.0-40 patch. Web policy agents 4.2 is now available, which supersedes the 4.1.0-x patches.

1 reader recommends this article


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


Redistribution, reproduction (in whole or in part) of this document is strictly prohibited unless otherwise agreed to in writing by ForgeRock. Use of this code supplied as part of this patch requires a commercial software license with ForgeRock AS or with one of its affiliates. All use shall be exclusively subject to such license between the licensee and ForgeRock AS.  

Obtaining this patch

Web policy agents 4.2 is now available, which supersedes the 4.1.0-x patches. The 4.2 release includes everything from the 4.1.0-x patches plus additional fixes. See Web Policy Agent Release Notes for further information.

You can download this release from BackStage.

Potential breaking changes

Patch releases of the agent 4.1.0-37 and above contain major functionality changes to the CDSSO/POST Data Preservation flow. Customers running these releases and above in CDSSO mode should note the behavior has now changed to use the PDP module ( dummypost URL ) to handle CDSSO re-POSTs. The original URL will be restored after CDSSO/LARES is received, parsed and validated. If you are using a non-standard CDSSO login flow, you must implement the same sequence of redirects/re-posts as the original cdcservlet. 

It is stressed that these changes are accommodated for and tested thoroughly before placing into a production environment. If they are not, it could cause potential downtime.

See Configuration Instructions below for further details.

Installation instructions

Please follow the instructions in the install documentation to install a fresh instance: Web Policy Agent Guide

Please note that you must do the following if this is an existing install (that is, you have an existing agent.conf file):

  1. Stop the Web server containing the web policy agents
  2. Ensure both the agentadmin executable and libraries (.so or .dll depending on platform) are replaced.
  3. Extract the configuration encryption key from the agent.conf file (located in the /path/to/web_agents/agent_version/instances/Agent_nnn/config directory), for example: $ grep config.key agent.conf com.sun.identity.agents.config.key = MTVkOWQ3ZjYtMTY3Yi1jNg==
  4. Re-encrypt the password, for example: $ agentdir\bin>agentadmin --p "MTVkOWQ3ZjYtMTY3Yi1jNg==" "youragentpassword"
  5. Replace the value of the com.sun.identity.agents.config.password property in the agent.conf file with this encrypted password.
  6. Repeat steps 2 to 4 for all web policy agents on this web server. 
  7. Start the web server containing the web policy agents.

Configuration instructions

4.1.0-37 and later

  • A new configuration property (org.forgerock.agents.config.cdsso.original.url.redirect.param) has been introduced to facilitate migrating custom CDSSO endpoints used for authentication. You should set this property to the name of the query parameter used to store the original URL in advanced properties; the agent will then add the original request URL (URL-encoded) to the CDSSO login redirect URL. For example, if you set it as follows: org.forgerock.agents.config.cdsso.original.url.redirect.param=mycustomgoto The resulting cdcservlet URL will be similar to this:
  • A new configuration property (org.forgerock.agents.config.cdsso.txcookie.maxage) has been introduced, which controls the max-age value on the CDSSO TX cookie (if AM_AGENT_KEY is set). The default setting is 30 seconds. The value of this new property is added to the value of com.sun.identity.agents.config.policy.clock.skew to derive total validity time.

4.1.0-33 and later

In load balancer mode, a new configuration property (org.forgerock.agents.config.forward.cookies) is available to allow one or more secondary cookies to be sent to PLL endpoints. This change allows for non-default load balancer cookie names that have been set in the AM/OpenAM server configuration (

The new configuration property can be set with a single value or multiple comma separated values (no spaces) as shown in these examples:

org.forgerock.agents.config.forward.cookies=CookieName org.forgerock.agents.config.forward.cookies=CookieName,OtherCookieName

Load balancer mode is indicated by setting the com.sun.identity.agents.config.load.balancer.enable property to true in the agent.conf file. This property must only exist once in the agent.conf file.

4.1.0-31 and later

  • A new parameter (org.forgerock.agents.config.restricted.token.mode) has been created to allow further constraining of restricted tokens. When set, it will only allow SSO only restricted tokens issued through the agent to be used with that agent; this prevents peer agents from using each other's cookies. You can set it as follows: org.forgerock.agents.config.restricted.token.mode=true
  • The org.forgerock.agents.config.lares.cookie.compatibility.mode parameter (which has not been used since 4.1.0-25) has been removed. Keeping this value in the configuration is harmless.  

4.1.0-30 and later

Review the Post Data Preservation (PDP) setting and set it to false if it is not required:


In earlier versions (4.1.0-25 to 4.1.0-29), PDP had to be enabled, but as of this patch, it should only be enabled if needed. 

4.1.0-11 to 4.1.0-29

Edit the agent.conf file and add the port number to the com.sun.identity.client.notification.url property and restart the policy agent. This change is needed because of known issue: AMAGENTS-504 (default ports an not handled as expected, e.g. NotificationURL), which causes notifications between AM/OpenAM and the policy agent to fail because of the missing port number. This issue affects both centralized and local configurations.

This issue is resolved in 4.1.0-30.

4.1.0-25 to 4.1.0-29

You must switch PDP on if you use HTTP Post due to changes made to address: AMAGENTS -469 (Browser hang in PDP with agent 4.1 using mod_jk with a fileupload servlet). This can be enabled as follows:


You must switch post data preservation on if you are using policy agent 4.1.0-25 to 4.1.0- 29 even if you do not use Cross-Domain SSO as stated in previous readmes.

4.1.0-10 and later

ErrorDocument is now being observed correctly. This means that users could see a difference between accessing a standard 403 page compared with accessing the default root document (http(s)://host:port/) after upgrade. For example, the default Apache™ 2.4 install on CentOS™ 7 configures an ErrorDocument in conf.d/welcome.conf but no where else; this would result in you getting the standard welcome to Apache page, but in the background, it is still a 403 page.

Hotfix details

This is a cumulative patch containing resolution to the following defects on top of 4.1.0:







































Additional notes


There is a new limit set for Post Data Preservation; this will now stop working if there is less than 100MB disk space in the PDP directory (AM_PDP_DIR or temporary directory). Expired files will be removed once a minute.


If notifications are disabled, then keep alives are also disabled. This is a consequence of the changes to reduce calls in AMAGENTS-1473 (If Agent notifications are off in local mode, then do not perform add/remove listener calls.) as these keep alives were predominantly to allow callbacks to occur.

An additional fix to AMAGENTS-1371 (Backport Java agent 5 cookie based CDSSO PDP to allow this to work in situations where sticky load balancing is not allowed) was needed to cater for URI encoding for the cookie.


Issue AMAGENTS-1579 (Encounter a Forbidden error when using AM_AGENT_REST_LOGIN=5 against AM 5.x ) occurs in patches 4.1.0-30 to 4.1.0-34 if the com.sun.identity.agents.config.naming.url property has a trailing slash. You can workaround this issue by removing the trailing slash or you can upgrade to patch 4.1.0-36, which fixes the issue.


AMAGENTS-1371 (Backport Java agent 5 cookie based CDSSO PDP to allow this to work in situations where sticky load balancing is not allowed) is a backport of Agents 5 functionality. This allows complex architectures to work with CDSSO without sticky load balancing.

To use this new functionality, set an environment variable AM_AGENT_KEY to a shared secret. When a CDSSO LARES post comes in, usually the details are saved in a local server cache. When this environment variable is detected, instead of being saved in a local file, a new cookie X-AMAGENT-TX is created. This contains a zipped and encrypted copy of the data that was posted. A peer server can read this and use its own AM_AGENT_KEY to see if this request originates from a peer.

As a backup mechanism the regular file system will be checked for the redirected file, and if the environment variable is not present, the existing functionality will be used.

The encryption will use OpenSSL based encryption on Unix® and native Windows encryption on Microsoft® Windows®.



  • The policy/session cache has been reduced to 32 MB. This adjusts the default amount of shared memory required down to 161 MB, comprising of 32 MB for the policy/session cache and 128.7 MB for the logging segment. The audit segment is no longer in shared memory and operates in a per-process list.
  • This change reduces the number of shared memory segments needed to 2. This is especially important for AIX 32 bit installations.
  • For CDSSO, time checking is now enforced for the LARES assertions. This means that time synchronization is needed between AM/OpenAM and Policy Agents. The old policy agent 3.x property (com.sun.identity.agents.config.policy.clock.skew) has been re-introduced to allow time skewing in checking the NotBefore and NotOnOrAfter sections. This defaults to zero and is set in seconds.


  • There are extra diagnostic messages at an INFO level to aid in performance testing.
  • By default, policy/session cache garbage collection now runs once a minute instead of every 3 seconds as it did in the 4.1.0 GA release and prior patch versions. This is the equivalent of running with the environment variable AM_CACHE_GC_INTERVAL set to 60. This environment variable will still overwrite the default value of 60 if set.


  • The maximum URI size has been increased to 8k.

Known issues

For other outstanding defects, please see the release notes in the See Also section.


Due to changes in the installer for IIS, some variations may occur in agentadmin --i, agentadmin --n and agentadmin --l. Specifically in interactive mode, there is the ability to have a more fine grained choice over application and virtual directories: AMAGENTS-1033 (New IIS installer is not backwards compatible with silent install mode) that was not there in earlier patches.

See Also

Web Policy Agent Guide

Web Policy Agent Release Notes

Copyright and TrademarksCopyright © 2021 ForgeRock, all rights reserved.