Notes covering prerequisites, fixes, known issues for ForgeRock® Access Management web policy agents. ForgeRock Access Management provides authentication, authorization, entitlement, and federation software.

Preface

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

Web Policy Agent 4.2
  • 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

Web Policy Agent 4.2
  • 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|5 key-value pair in the cache:

    https:/www.example.com/p1/p2?param1=value1&param2=value4&param3=value3
    https:/www.example.com/p1/p2?param1=value1&param2=value5&param3=value3

    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, All is the same as Message and provides the same output to better match AM's debug message levels. Also, the Info, Message, and All debug 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.

Table 2.1. Supported Operating Systems & Web Servers
Operating SystemsOS VersionsWeb Servers & Versions
CentOS
Red Hat Enterprise Linux
Oracle Linux
5[a]
Apache HTTP Server 2.2[b], 2.4
6, 7
Apache HTTP Server 2.2[b], 2.4
NGINX Plus R12
Microsoft Windows Server
2008 R2
Microsoft IIS 7.5
Apache HTTP Server 2.2[b], 2.4[c]
2012, 2012 R2
Microsoft IIS 8, 8.5
Apache HTTP Server 2.2[b], 2.4[c]
2016
Microsoft IIS 10
Apache HTTP Server 2.2[b], 2.4[c]
Oracle Solaris x64
Oracle Solaris SPARC
10, 11
Apache HTTP Server 2.2[b], 2.4
Ubuntu Linux
14.04 LTS
Apache HTTP Server 2.2[b], 2.4
NGINX Plus R12
16.04 LTS
NGINX Plus R12
IBM AIX
6.1, 7.1
IBM HTTP Server v7[d], v9[e]

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

Table 2.2. Supported OpenSSL Versions
Operating SystemsOpenSSL Versions
CentOS
Red Hat Enterprise Linux
Oracle Linux
Ubuntu Linux
OpenSSL 1.0.x, OpenSSL 1.1.0, OpenSSL 1.1.1
Microsoft Windows Server OpenSSL 1.0.x, OpenSSL 1.1.1 [a]
Oracle Solaris X86/SPARC
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.


Note

  • 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 agent.log file:

    [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 agent.log file:

    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 info@forgerock.com.

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

Web Policy Agent 4.2
  • 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.login.url and com.sun.identity.agents.config.logout.url properties in the agent profile, otherwise the agent will return persistent 403 errors.

  • Addition of a New Environment Variable: AM_LOG_ONE

    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 ampostpreserve query parameter in CDSSO mode

    The org.forgerock.agents.config.cdsso.original.url.redirect.param custom 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".

Web Policy Agent 4.1.1
  • Procedure to Enable SSL for Windows Agents Changed

    Earlier versions of the web policy agents used the org.forgerock.agents.config.secure.channel.disable property 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:

  • Changes to the org.forgerock.agents.config.keepalive.disable Property

    Web Policy Agents 4.1.1 behave as if the org.forgerock.agents.config.keepalive.disable property is set to false when notifications are disabled.

    For more information, see Miscellaneous Custom Properties in the Web Policy Agent Guide.

Web Policy Agent 4.1
  • 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:

    1. Encode the string in base64 format: yZfDq8mxw7g=.

    2. Wrap the base64-encoded string as per RFC 2047: =?UTF-8?B?yZfDq8mxw7g=?=.

  • 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: http://www.example.com/bon/caf%C3%A9

    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:

    • com.forgerock.agents.nss.shutdown

    • com.sun.identity.agents.config.profilename

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

4.2. Limitations

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

    • com.sun.identity.agents.config.ignore.path.info

    • com.sun.identity.agents.config.ignore.path.info.for.not.enforced.list

  • 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 AuthName, FilesMatch, and Require is 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:

Table 5.1. Documentation Change Log
DateDescription
2018-10-26

Release of Web Agents 4.2.

The following documentation updates were made:

2018-09-25

Updated the default value for the org.forgerock.agents.config.tls property to -SSLv3 -TLSv1 -TLSv1.1. For more information, see Bootstrap Properties in the Web Policy Agent Guide.

2016-09-20

Reorganization of web policy agent documentation

2016-12-02

4.1.0 Release

2017-05-19

Web Policy Agents 4.1 documentation refresh, which includes the following updates:

2018-01-25

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.

ForgeRock has staff members around the globe who support our international customers and partners. For details, visit https://www.forgerock.com, or send an email to ForgeRock at info@forgerock.com.

Read a different version of :