Notes covering prerequisites, fixes, known issues for ForgeRock® Access Management web policy agents. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.
Read these release notes before you install the Web Policy Agent.
The information contained in these release notes cover prerequisites for installation, known issues and improvements to the software, changes and deprecated functionality, and other important information.
About ForgeRock Identity Platform™ Software
ForgeRock Identity Platform™ is the only offering for access management, identity management, user-managed access, directory services, and an identity gateway, designed and built as a single, unified platform.
The platform includes the following components that extend what is available in open source projects to provide fully featured, enterprise-ready software:
ForgeRock Access Management (AM)
ForgeRock Identity Management (IDM)
ForgeRock Directory Services (DS)
ForgeRock Identity Gateway (IG)
ForgeRock Identity Message Broker (IMB)
Chapter 1. What's New
Before you install AM web policy agents or update your existing web policy agent installation, read these release notes.
1.1. New Features
Agents 4.2 now supports IBM HTTP server v7 and v9 on IBM AIX. Apache v22 and v24 are no longer supported on IBM AIX, but may be available upon request from Support. For more information on the supported platforms, see Table 2.1, "Supported Operating Systems & Web Servers".
1.2. Major Improvements
Improved Cache Performance
For Ajax-based applications that use key-value pairs in its URLs, there may be similar URLs that differ by key-value pair in the cache; thus, causing extra time searching through the cache. For example, the following two URLs differ by the
param2=value4|5key-value pair in the cache:
Web Agents 4.2 supports the ability for administrators to select common key-value pairs to ignore. Once the list of ignored parameters is processed, the remaining parameters are sorted alphabetically by the key. This process produces less entries in the web agent policy cache and, therefore, improves the look-up speed of cached policy evaluation.
Support for Load Balancers That do not Support Session Stickiness
Web Policy Agent 4.2 includes a new environment variable,
AM_AGENT_REST_LOGIN, to allow the agent to authenticate to AM servers configured behind a load balancer, which does not support session stickiness.
Improved Performance through Pattern-Based Policy Enforcement Rule
Web Policy Agent 4.2 implements a limited regular-expression-based parameter to match a specific pattern during policy evaluation. Once a policy has been selected, the results are cached for the session for the polling interval.
The regular expression-based parameter ensures that the agent's cache does not become cluttered with URL paths that are only used once per session.
Message Level Debug Improvements
Web Policy Agent 4.2 now supports improvements in message level debug logging labels. Now,
Allis the same as
Messageand provides the same output to better match AM's debug message levels. Also, the
Alldebug levels include additional diagnostic timing information.
For more information, see General Properties in the Web Policy Agent Guide.
Additional Improvements from Agents 4.1.0 Patches
Web Policy Agent 4.2 includes changes made in previous patch releases for Agents 4.1.0. To view these improvements and fixes, see Readme for Web Policy Agent 4.1.0-40 patch in the ForgeRock Knowledge Base.
Chapter 2. Before You Install
This chapter covers software and hardware prerequisites for installing and running web policy agent software.
ForgeRock supports customers using the versions specified here. Other versions and alternative environments might work as well. When opening a support ticket for an issue, however, make sure you can also reproduce the problem on a combination covered here.
2.1. Web Policy Agents Platform Requirements
The following table summarizes platform support.
|Operating Systems||OS Versions||Web Servers & Versions|
[a] Centos 5 is deprecated in Agents 4.2.
[b] Apache 2.2 is deprecated in Agents 4.2. Apache 2.2 is limited to OpenSSL 1.0.x.
[c] The Apache HTTP Server Project does not offer binary releases for Microsoft Windows. The ForgeRock Apache HTTP Server policy agent for Windows was tested against the binaries offered by Apache Lounge.
[d] IBM HTTP server v7 is limited to OpenSSL 1.0.x. Apache 2.2 systems are limited to OpenSSL 1.0.x, IHSv7 is just one case.
[e] Apache HTTP Server v2.2 and v2.4 are available upon request. Contact Support for the patch.
The following table summarizes OpenSSL support for SSL and TLS connections. Make sure you are aware of the OpenSSL requirements for new installations if you are still on OpenSSL 0.9.8:
|Operating Systems||OpenSSL Versions|
|OpenSSL 1.0.x, OpenSSL 1.1.0, OpenSSL 1.1.1|
|Microsoft Windows Server||OpenSSL 1.0.x, OpenSSL 1.1.1 [a]|
|OpenSSL 0.9.8, OpenSSL 1.0.x, OpenSSL 1.1.0, OpenSSL 1.1.1|
|IBM AIX||OpenSSL 0.9.8, OpenSSL 1.0.x, OpenSSL 1.1.0, OpenSSL 1.1.1|
[a] On Windows operating systems, the policy agents use the native Windows SSL libraries by default.
OpenSSL 1.1.0, OpenSSL 1.1.1 and TLS v1.3 are supported for Web Policy Agent 4.2.
OpenSSL 1.0.1 and 1.0.2 is required to support TLSv1.2.
OpenSSL 1.1.1 is required to support TLSv1.3.
Windows Secure Channel does not support TLS v1.3 yet. If Windows Secure Channel is mandatory for your deployment, you can use OpenSSL.
Before installing web policy agents on your platform, also make sure that the system meets the following requirements:
- Linux Systems
Web Policy Agents on Linux systems require a minimum of 135 megabytes of free disk space at all times. If the amount of free space drops below this threshold, a warning similar to the following appears in the
[Fri Nov 11 10:02:10.138732 2016] [amagent:error] [pid 4350:tid 140545949357888] amagent_init() status: no space left on device [Fri Nov 11 10:02:10.138981 2016] [:emerg] [pid 4350:tid 140545949357888] AH00020: Configuration Failed, exiting am_log_init() free disk space on the system is only 116703232 bytes, required 134900080 bytes
- Microsoft Windows Systems
Before installing the IIS 7 web policy agent on Microsoft IIS 7 or IIS 8, make sure that the optional Application Development component of Web Server (IIS) is installed. In the Windows Server 2012 Server Manager for example, Application Development is a component of Web Server (IIS) | Web Server.
Web Policy Agents on Windows systems require a minimum of 1.07 gigabytes of free disk space at all times. If the amount of free space drops below this threshold, a warning similar to the following appears in the
2016-11-10 10:12:10.291 +0000 ERROR [10716:9348] am_shm_create(): free disk space on the system is only 528949248 bytes, required 1073627136 bytes 2016-11-10 10:12:10.291 +0000 ERROR [10716:9348] get_memory_segment(): shared memory error: blocks
After making more disk space available, you will need to restart the web policy agent.
Failure to free up disk space and restart the web policy agent may result in errors similar to the following:
2016-11-10 10:19:43.610 +0000 ERROR [3764:9348] OpenAMHttpModule(): agent init for site 1 failed (error: -31)
2.2. Special Requests
If you have a special request regarding support for a combination not listed here, contact ForgeRock at firstname.lastname@example.org.
Chapter 3. Changes and Deprecated Functionality
This chapter covers both major changes to existing functionality, and also deprecated and removed functionality.
3.1. Important Changes to Web Policy Agent Functionality
New Agents Profiles on AM 6.x are not Compatible with Agent 4.x by Default
New agent profiles created on AM 6.x are not compatible with Web Policy Agent 4.x by default, causing the agent to return HTTP 403 error messages. To work around this issue, set the
com.sun.identity.agents.config.logout.urlproperties in the agent profile, otherwise the agent will return persistent 403 errors.
Addition of a New Environment Variable:
Web Policy Agents 4.2 now provides an environment variable,
AM_LOG_ONE, to enable direct logging for an agent instance to mitigate against any performance impact when the debug logging is enabled. This variable is used for single agent instances only.
For more information, see Web Policy Agent Environment Properties in the Web Policy Agent Guide.
Incoming request URL is Shown in the
ampostpreservequery parameter in CDSSO mode
org.forgerock.agents.config.cdsso.original.url.redirect.paramcustom property is still available but it is redundant in Agents 4.2.
For more information, see Miscellaneous Custom Properties in the Web Policy Agent Guide.
Support for TLSv1.3 and OpenSSL 1.1.1
Web Policy Agents 4.2 now supports TLSv1.3, which requires OpenSSL 1.1.1 or later.
For a list of supported protocols, see Table 2.2, "Supported OpenSSL Versions".
Procedure to Enable SSL for Windows Agents Changed
Earlier versions of the web policy agents used the
org.forgerock.agents.config.secure.channel.disableproperty to determine whether to use OpenSSL or the native Windows libraries for SSL communications.
This property is no longer used and web policy agents 4.1.1 use the native Windows libraries for SSL communications by default. Perform the following steps to enable OpenSSL:
AM_SSL_SCHANNELenvironment variable to
falseand restart the IIS or Apache server.
Ensure the OpenSSL libraries are available. For more information, see Table 4.1, "OpenSSL DLL Locations on 32-bit and 64-bit Windows" in the Web Policy Agent Guide or Table 3.1, "OpenSSL Libraries Location by Operating System" in the Web Policy Agent Guide .
Changes to the
Web Policy Agents 4.1.1 behave as if the
org.forgerock.agents.config.keepalive.disableproperty is set to
falsewhen notifications are disabled.
For more information, see Miscellaneous Custom Properties in the Web Policy Agent Guide.
UTF-8 strings in headers are now MIME-encoded
Web Policy Agents now base64-encode UTF-8 strings in headers, then wrap the string as described in RFC 2047:
encoded-word = "=?" charset "?" encoding "?" encoded-text "?="
For example, given a UTF-8 username, such as
ɗëɱø, Web Policy Agents will:
Encode the string in base64 format:
Wrap the base64-encoded string as per RFC 2047:
Unencoded URLs are now passed to AM
Web Policy Agents no longer encode paths before passing them to AM for policy evaluation. AM will receive the path with the same formatting as provided by the user agent.
For example, given a URL containing UTF-8 characters, such as
http://www.example.com/bon/café, Web Policy Agents will pass this exact string to AM.
AM performs its own URL encoding, so to match the example above the policy would need to be configured with the following as a resource:
You may need to add additional resource specifiers to handle the raw URL strings that are now passed on from Web Policy Agents 4.1 and newer.
Re-Implemented Properties for Forward Proxy Configuration
Properties for configuring a forward proxy for communication from the web policy agent to AM have been re-implemented. They were previously removed in Web Policy Agent 4.0.0.
For information on the properties, see Forward Proxy Custom Properties in the Web Policy Agent Guide.
32-bit and 64-bit Application Pools Support on IIS
Web Policy Agent 4.1 now supports 32-bit and 64-bit application pools on the same IIS environment.
3.2. Deprecated Functionality
Deprecated functionality are features that ForgeRock plans to remove support in a future Agents release version:
Apache 2.2 support is deprecated in Agents 4.2.
Centos 5 support is deprecated in Agents 4.2.
3.3. Removed Functionality
The following agent configuration properties are no longer required in Agents 4.1:
Chapter 4. Web Policy Agents Fixes, Limitations, and Known Issues
4.1. Key Fixes
4.1.1. Key Fixes in Agents 4.2
AMAGENTS-323: With 4.1.0 we create more than 11 shared memory segments causing AIX32 bit to crash / fail to start
AMAGENTS-364: agents.config.policy.evaluation.realm does not handle realm aliases
AMAGENTS-504: default ports an not handled as expected, e.g. NotificationURL
AMAGENTS-845: Attribute value set by session.attribute.mapping is not available
AMAGENTS-924: 3rd party WPA 4.x http parser does not correctly handle http 1.0 / 1.1 mode switching
AMAGENTS-1030: Nginx Web agent add Authorization header and send request along.
AMAGENTS-1246: Improve cache performance by allowing agent to remove named parameters from urls
AMAGENTS-1339: agentadmin --g crash on 4.1.0-27
AMAGENTS-1391: Accelerate performance by allowing agent to cache and enforce a pattern-based agent policy enforcement rule
AMAGENTS-1551: WPA agentadmin --g option is changing empty xml element value
AMAGENTS-1588: agentadmin for varnish requires glibc 2.14
AMAGENTS-1646: WPA4 for Varnish is crashing in VRB_Iterate
AMAGENTS-1677: WPA for Varnish does not require workaround for the limited stack space anymore
AMAGENTS-1711: Setting Message level debug on the agent results in WARN level debug.
AMAGENTS-1738: Agent4 on AIX fails to decode session token
AMAGENTS-1757: Missing com.sun.identity.agents.config.fqdn.default remote configuration property can crash the agent
AMAGENTS-1759: WPA4 for IIS post data preservation + cdsso returns 404 error
AMAGENTS-1771: WPA4 invalid JSON response with a valid session
AMAGENTS-1781: WPA4 for IIS post data preservation + cdsso to redirect page returns 404 error
AMAGENTS-1801: Agent does not log any OpenSSL library validation errors
AMAGENTS-1808: Varnish agent crash in VRTPRIV_dynamic_kill
AMAGENTS-1821: Agent4 corrupts audit log entries
AMAGENTS-1834: Agent4 is missing com.forgerock.agents.cdsso.cookie.urlencode configuration property handler available in agent3
AMAGENTS-1835: Adjust retry numbering to be consistent
AMAGENTS-1857: Agent4 POST data handler results in sporadic HTTP 200 status codes
AMAGENTS-1875: Agent4 crash in base64 encode method
AMAGENTS-1902: Agent4 for Apache server on Windows is crashing on worker process restart
AMAGENTS-1976: BACKPORT AMAGENTS-1348: Add option of fast direct logger
AMAGENTS-1977: Add openssl 1.1.1 library detection for AIX web agent
AMAGENTS-1991: Deadlock in agent4 for Apache server on Windows with remote audit enabled
The following limitations and workarounds apply to Web Policy Agent 4.x:
The NGINX Plus policy agent does not support the ignore path info properties
Apache HTTP Server Authentication Functionality Not Supported
The web agent replaces authentication functionality provided by Apache, for example, the
mod_auth_*modules. Integration with built-in Apache httpd authentication directives, such as
Requireis not supported.
4.3. Known Issues
4.3.1. Known Issues in 4.2
AMAGENTS-377: URL with query parameters is not recognised as agent logout url
AMAGENTS-456: URL Comparison Case Sensitivity Check does not work for policies
AMAGENTS-554: sso-only mode does not work for specific URLs
AMAGENTS-703: cache usage is much smaller than expected
AMAGENTS-773: Agent Authenticator profile can't evaluate policies in sub-realm
AMAGENTS-798: Session upgrade and custom goto parameter automated tests fail when using autodeploy for c-agent tests
AMAGENTS-925: WPA 4 uses faulty WSAPoll feature on windows. This creates intermittent socket errors.
AMAGENTS-1125: Session properties with tab is lost or replaced by space on Agent
AMAGENTS-1206: com.sun.identity.agents.config.load.balancer.enable does not work from Central Profile
AMAGENTS-1420: Nginx binaries currently fail with latest opensource Nginx
Chapter 5. Documentation Updates
The following table tracks changes to the documentation set following the release of AM Web Policy Agent 4.2:
Release of Web Agents 4.2.
The following documentation updates were made:
Updated the default value for the
Reorganization of web policy agent documentation
Web Policy Agents 4.1 documentation refresh, which includes the following updates:
Web Policy Agents 4.1 documentation refresh, which includes the following updates:
|2018-05-08||Added IIS 8.5 to the list of supported platforms for Web Policy Agent 4.1.x.|
Appendix A. Getting Support
For more information or resources about AM and ForgeRock Support, see the following sections:
A.1. Accessing Documentation Online
ForgeRock publishes comprehensive documentation online:
The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.
While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.
ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.
A.2. Using the ForgeRock.org Site
The ForgeRock.org site has links to source code for ForgeRock open source software, as well as links to the ForgeRock forums and technical blogs.
If you are a ForgeRock customer, raise a support ticket instead of using the forums. ForgeRock support professionals will get in touch to help you.
A.3. Getting Support and Contacting ForgeRock
ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.