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

Preface

Read these release notes before you install the Web 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™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Chapter 1. What's New in Web Agents

Before you install AM Web Agents or update your existing web agent installation, read these release notes.

Important

Before upgrading to Web Agents 5.6.x, consider the following points:

  • Web Agents 5.6.x only supports AM 5.5 and later.

  • Web Agents 5.6.x requires the WebSocket protocol to communicate with AM. Both the web server and the network infrastructure must support the WebSocket protocol. For example, Apache HTTP server requires the proxy_wstunnel_module for proxying the WebSocket protocol.

    Refer to your network infrastructure and web server documentation for more information about WebSocket support.

  • If you are upgrading from a version earlier than 5, Web Agents 5 introduced notable changes in the configuration. For example, if you are using custom login pages, you must enable the org.forgerock.openam.agents.config.allow.custom.login property. For more information about changes introduced in Web Agents 5, refer to the Web Agents 5 Release Notes.

1.1. Patch Releases

ForgeRock patch releases contain a collection of fixes that have been grouped together and released as part of our commitment to support our customers. For general information on ForgeRock's maintenance and patch releases, see Maintenance and Patch Availability Policy.

Web Agents 5.6.1.1
  • Web Agents 5.6.1.1 is the latest release targeted for Web Agents 5.6.1.0 deployments and can be downloaded from the ForgeRock Backstage website. To view the list of fixes in this release, see Web Agents 5.6.1.1.

1.2. New Features

Web Agents 5.6.1.1
  • There are no new features in this release.

Web Agents 5.6.1.0
  • Support for Public AM URLs

    Web Agents 5.6.1.0 includes a new property, com.forgerock.agents.public.am.url, that specifies the public URL of the AM to redirect to. Use this property in environments where custom login pages are in a network that can only access AM using a proxy, a firewall, or any other technology that remaps the AM URL to one accessible by the custom login pages.

    For more information, see Login URL Properties in the User Guide.

  • Support for Converting SSO Tokens into OpenID Connect JWTs

    Web Agents 5.6.1.0 includes a new property, com.forgerock.agents.accept.ipdp.cookie, that specifies whether the agent should convert SSO tokens (iPlanetDirectoryPro cookies) present on requests into OpenID Connect JWTs.

    Set this property when your end users access resources protected by both Web Agents 4.x (which use SSO tokens) and 5.x (which use OpenID Connect JWTs). Converting the SSO token to a JWT will ensure a seamless experience to the user without additional redirection or re-authentication.

    For more information, see Profile Properties in the User Guide.

Web Agents 5.6.0

Web Agents 5.6.0 is a minor release that includes new platform support, bug fixes, and a new feature:

  • Added Support for Distributed Policy Evaluation

    Web Agents 5.6.0 introduces a policy cache, which builds upon the existing policy decision cache.

    When enabled, web agents download and store details about policies from AM, and use them to make authorization decisions without having to contact AM each time. This reduces the agents' callbacks to AM and can increase the performance of the agents.

    Important

    This functionality is a Technology Preview.

    For more information, see "Caching Capabilities" in the User Guide.

1.3. Major Improvements

Web Agents 5.6.1.1
  • There are no major improvements in this release.

Web Agents 5.6.1.0
  • There are no major improvements in this release.

Web Agents 5.6.0
  • There are no major improvements in this release.

Chapter 2. Before You Install

This chapter covers software and hardware prerequisites for installing and running web 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. Platform Requirements

The following table summarizes platform support.

Supported Operating Systems and Web Servers
Operating SystemsOS VersionsWeb Servers & Minimum Supported Versions
Amazon Linux 2,
CentOS,
Oracle Linux,
Red Hat Enterprise Linux
6,
7
Apache HTTP Server 2.4,
IBM HTTP Server 9.0,
NGINX Plus R16 (NGINX open source build 1.15.2),
NGINX Plus R17 (NGINX open source build 1.15.7)
IBM AIX
6, [b]
7
IBM HTTP Server 9
Microsoft Windows Server
2008 R2 [b]
Apache HTTP Server 2.4, [a]
Microsoft IIS 7.5
2012, [b]
2012 R2 [b]
Apache HTTP Server 2.4, [a]
Microsoft IIS 8,
Microsoft IIS 8.5
2016
Apache HTTP Server 2.4, [a]
Microsoft IIS 10
Oracle Solaris SPARC,
Oracle Solaris x64
10,
11
Apache HTTP Server 2.4
Ubuntu Linux
16.04 LTS, [b]
18.04 LTS
Apache HTTP Server 2.4,
NGINX Plus R16 (NGINX open source build 1.15.2),
NGINX Plus R17 (NGINX open source build 1.15.7)

[a] The Apache HTTP Server Project does not offer binary releases for Microsoft Windows. The ForgeRock Apache HTTP Server web agent for Windows was tested against the binaries offered by Apache Lounge.

[b] Support for this platform will be discontinued in a future release.


Important

  1. Web Agents 5.6.1.1 requires the WebSocket protocol to communicate with AM. Both the web server and the network infrastructure must support the WebSocket protocol. For example, Apache HTTP server requires the proxy_wstunnel_module for proxying the WebSocket protocol.

    Refer to your network infrastructure and web server documentation for more information about WebSocket support.

  2. Support for 32-bit architectures on Unix-based platforms will be discontinued in a future release.

2.2. Access Management Requirements

Web Agent 5.6.1.1 does not interoperate with:

  • OpenAM

  • AM versions earlier than 5.5.

2.3. OpenSSL Requirements

Agents require OpenSSL or the Windows built-in Secure Channel API to be present. These libraries help to secure communications, for example, when connecting to AM using the WebSocket protocol.

The following table summarizes OpenSSL support in Agents 5.6.1.1:

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.0, 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 web agents use the Windows built-in Secure Channel API by default.


Note

OpenSSL 1.0.2 or newer is required to support TLSv1.2. If you have to use an earlier, weaker cipher in your environment, configure the org.forgerock.agents.config.tls bootstrap property with a security protocol other than TLSv1.2.

2.4. Other Requirements

Before installing web agents on your platform, also make sure that the system meets the following requirements:

Linux Systems
  • Before installing web agents on Linux, make sure the system can run gcc 4.4.7. libc.so.6 must be available and it must support the GLIBC_2.3 ABI. You can check this by running the following command: strings libc.so.6 | grep GLIBC_2.

  • Web agents on Linux require a minimum of 16 MB of shared memory for the session and policy cache and the various worker processes and additionally, 32 KB shared memory for the logging system. Failure to provide enough shared memory may result in errors similar to the following:

    2017-11-10 12:06:00.492 +0000   DEBUG [1:7521][source/shared.c:1451]am_shm_create2() about to create block-clusters_0, size 1074008064
    2017-11-10 12:06:00.492 +0000   ERROR [1:7521]am_shm_create2(): ftruncate failed, error: 28

    To configure additional shared memory for the session and policy cache, see "Configuring Web Agent Environment Variables" in the User Guide.

  • If POST data preservation is enabled, the web agent requires additional free disk space in the web agent installation directory to store the POST data cache files. To change the POST data storage directory, see Post Data Preservation Properties in the User Guide.

Microsoft Windows Systems
  • Before installing the IIS web agent, 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 agents on Windows require a minimum of 16 MB of shared memory for the session and policy cache and the various worker processes in the system page file and additionally, 32 KB shared memory for the logging system. Failure to provide enough shared memory may result in errors similar to the following:

    2017-11-10 12:06:00.492 +0000   DEBUG [1:7521][source/shared.c:1451]am_shm_create2() about to create block-clusters_0, size 1074008064
    2017-11-10 12:06:00.492 +0000   ERROR [1:7521]am_shm_create2(): ftruncate failed, error: 28

    To configure additional shared memory for the session and policy cache, see "Configuring Web Agent Environment Variables" in the User Guide.

  • If POST data preservation is enabled, the web agent requires additional free disk space in the web agent installation directory to store the POST data cache files. To change the POST data storage directory, see Post Data Preservation Properties in the User Guide.

2.5. 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 Existing Functionality

Web Agents 5.6.1.1
  • There are no major changes in this release, other than bug fixes.

Web Agents 5.6.1.0
  • Changes to the agentadmin --V Command

    Earlier versions of Web Agents included the agentadmin --V command, which you can use to validate an agent instance configuration.

    As part of the validation process, the agentadmin command ensures that the core init and shutdown agent sequences are working as expected. In some situations, this check made the agent instance unresponsive, causing unexpected service outages.

    Web Agents 5.6.1.0 does not execute the init and shutdown sequences when using the --V option. To run them, use the --Vi option instead.

    For more information, see "Command-Line Tool Reference" in the User Guide.

Web Agents 5.6.0
  • Fully Qualified Domain Name Checking Off by Default

    The com.sun.identity.agents.config.fqdn.check.enable is now set to false by default. This default value was changed for the 5.6.0 release and differs from previous releases, which was set to true. The change better aligns local configurations to be consistent with centralized profiles, which has FQDN checking off by default.

3.2. Deprecated Functionality

Web Agents 5.6.1.1
  • There is no deprecated functionality in this release.

Web Agents 5.6.1.0
  • There is no deprecated functionality in this release.

Web Agents 5.6.0
  • There is no deprecated functionality in this release.

3.3. Removed Functionality

Web Agents 5.6.1.1
  • No components were removed in this release.

Web Agents 5.6.1.0
  • No components were removed in this release.

Web Agents 5.6.0
  • No components were removed in this release.

Chapter 4. Fixes, Limitations, and Known Issues

4.1. Key Fixes

Web Agents 5.6.1.1
  • AMAGENTS-2816: WPA5 is using hardcoded socket read timeout value for Windows SSL handshake processing module

  • AMAGENTS-2798: Seg Fault when custom login=true but login.url is empty

Web Agents 5.6.1.0
  • AMAGENTS-2678: sso cookie is not found on custom-login-response and requires us to customize the service url

  • AMAGENTS-2684: Create arg on Validator to not initiate validate_worker_init_shutdown.

  • AMAGENTS-2702: If an sso token is presented, optimise agent flow by oauth2 token exchange

Web Agents 5.6.0
  • AMAGENTS-215: FQDN checking should be turned off by default - Web agent local file

  • AMAGENTS-1264: Update IIS agent Basic Auth support for JwtPasswordReplay

  • AMAGENTS-1861: Agent 5 crash in websocket_handshake on Solaris SPARC

  • AMAGENTS-2175: Erroneous size data in log messages on 32bit SPARC Solaris 10 WebAgent

  • AMAGENTS-2188: Replace use of non-threadsafe strerror

  • AMAGENTS-2199: Port override does not work properly when agent is behind load balancer

  • AMAGENTS-2407: Agent is resetting CDSSO session cookie on authn redirect with policy advice available

  • AMAGENTS-2456: WPA for Windows does not support OpenSSL 1.1.x

4.2. Limitations

Web Agents 5.6.1.1
  • There are no known limitations or workarounds in this release.

Web Agents 5.6.1.0
  • There are no known limitations or workarounds in this release.

Web Agents 5.6.0
  • There is no deprecated functionality in this release.

4.3. Known Issues

Web Agents 5.6.1.1
  • There are no known issues in this release.

Web Agents 5.6.1.0
  • AMAGENTS-456: URL Comparison Case Sensitivity Check does not work for policies

  • AMAGENTS-523: The files created during installation (e.g agent.conf) have the wrong permissions

  • AMAGENTS-1584: Error message is confusing if using a different realm for obtaining the ID token compared with the SSO token

  • AMAGENTS-2164: When setting audit log location to REMOTE there is a huge drop in performance

  • AMAGENTS-2617: Build machine value is missing in version output for centos 7 nginx builds

Web Agents 5.6.0
  • AMAGENTS-456: URL Comparison Case Sensitivity Check does not work for policies

  • AMAGENTS-523: The files created during installation (e.g agent.conf) have the wrong permissions

  • AMAGENTS-1584: Error message is confusing if using a different realm for obtaining the ID token compared with the SSO token

  • AMAGENTS-2164: When setting audit log location to REMOTE there is a huge drop in performance

  • AMAGENTS-2617: Build machine value is missing in version output for centos 7 nginx builds

Chapter 5. Documentation Updates

The following table tracks changes to the documentation set following the release of AM Web Agent 5.6:

Documentation Change Log
DateDescription
2019-08-02

Initial release of Web Agents 5.6.1.1.

2019-07-04

Initial release of Web Agents 5.6.1.0.

The following documentation updates were made for this release:

2019-03-29

Initial release of Web Agents 5.6.0.


Appendix A. Release Levels and Interface Stability

This appendix includes ForgeRock definitions for product release levels and interface stability.

A.1. ForgeRock Product Release Levels

ForgeRock defines Major, Minor, Maintenance, and Patch product release levels. The release level is reflected in the version number. The release level tells you what sort of compatibility changes to expect.

Release Level Definitions
Release LabelVersion NumbersCharacteristics

Major

Version: x[.0.0] (trailing 0s are optional)

  • Bring major new features, minor features, and bug fixes

  • Can include changes even to Stable interfaces

  • Can remove previously Deprecated functionality, and in rare cases remove Evolving functionality that has not been explicitly Deprecated

  • Include changes present in previous Minor and Maintenance releases

Minor

Version: x.y[.0] (trailing 0s are optional)

  • Bring minor features, and bug fixes

  • Can include backwards-compatible changes to Stable interfaces in the same Major release, and incompatible changes to Evolving interfaces

  • Can remove previously Deprecated functionality

  • Include changes present in previous Minor and Maintenance releases

Maintenance, Patch

Version: x.y.z[.p]

The optional .p reflects a Patch version.

  • Bring bug fixes

  • Are intended to be fully compatible with previous versions from the same Minor release


A.2. ForgeRock Product Stability Labels

ForgeRock products support many features, protocols, APIs, GUIs, and command-line interfaces. Some of these are standard and very stable. Others offer new functionality that is continuing to evolve.

ForgeRock acknowledges that you invest in these features and interfaces, and therefore must know when and how ForgeRock expects them to change. For that reason, ForgeRock defines stability labels and uses these definitions in ForgeRock products.

ForgeRock Stability Label Definitions
Stability LabelDefinition

Stable

This documented feature or interface is expected to undergo backwards-compatible changes only for major releases. Changes may be announced at least one minor release before they take effect.

Evolving

This documented feature or interface is continuing to evolve and so is expected to change, potentially in backwards-incompatible ways even in a minor release. Changes are documented at the time of product release.

While new protocols and APIs are still in the process of standardization, they are Evolving. This applies for example to recent Internet-Draft implementations, and also to newly developed functionality.

Legacy

This feature or interface has been replaced with an improved version, and is no longer receiving development effort from ForgeRock.

You should migrate to the newer version, however the existing functionality will remain.

Legacy features or interfaces will be marked as Deprecated if they are scheduled to be removed from the product.

Deprecated

This feature or interface is deprecated and likely to be removed in a future release. For previously stable features or interfaces, the change was likely announced in a previous release. Deprecated features or interfaces will be removed from ForgeRock products.

Removed

This feature or interface was deprecated in a previous release and has now been removed from the product.

Technology Preview

Technology previews provide access to new features that are considered as new technology that is not yet supported. Technology preview features may be functionally incomplete and the function as implemented is subject to change without notice. DO NOT DEPLOY A TECHNOLOGY PREVIEW INTO A PRODUCTION ENVIRONMENT.

Customers are encouraged to test drive the technology preview features in a non-production environment and are welcome to make comments and suggestions about the features in the associated forums.

ForgeRock does not guarantee that a technology preview feature will be present in future releases, the final complete version of the feature is liable to change between preview and the final version. Once a technology preview moves into the completed version, said feature will become part of the ForgeRock platform. Technology previews are provided on an “AS-IS” basis for evaluation purposes only and ForgeRock accepts no liability or obligations for the use thereof.

Internal/Undocumented

Internal and undocumented features or interfaces can change without notice. If you depend on one of these features or interfaces, contact ForgeRock support or email info@forgerock.com to discuss your needs.


Appendix B. Getting Support

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.

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.

Read a different version of :