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 Agent

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

Important

Before upgrading to Web Agents 5.7, consider the following points:

  • Web Agents 5.7 only support AM 5.5 and later.

  • Web Agents 5.7 require 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 Agent 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 Agent 5, refer to the Web Agent 5 Release Notes.

1.1. New Features

Web Agent 5.7
  • Added Support for SameSite Configuration

    Web Agents 5.7 add the SameSite Cookie Attribute property (com.forgerock.agents.cdsso.cookie.samesite) to set the SameSite attribute on all cookies the agent creates.

    For more information, see SameSite Cookie Attribute in the User Guide.

  • Policy Cache Feature Now Supported

    Web Agents 5.7 introduced a technical preview of the policy cache feature. The feature is fully supported in this release.

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

  • Accept Secure Cookies From AM Over HTTP

    A new bootstrap property allows the agent to accept secure cookies from AM over HTTP. For more information, see Accept Secure Cookies From AM Over HTTP in the User Guide.

1.2. Major Improvements

No major improvements have been added 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, [a]
7,
8
Apache HTTP Server 2.4,
IBM HTTP Server 9.0,
NGINX Plus R16, [a] [b]
NGINX Plus R17, [a] [b]
NGINX Plus R21,
NGINX Plus R22
IBM AIX
7
IBM HTTP Server 9
Microsoft Windows Server
2012 R2 [a]
Apache HTTP Server 2.4, [c]
Microsoft IIS 8.5
2016
Apache HTTP Server 2.4, [c]
Microsoft IIS 10
2019
Apache HTTP Server 2.4, [c]
Microsoft IIS 10
Oracle Solaris SPARC,
Oracle Solaris x64
11 [a]
Apache HTTP Server 2.4
Ubuntu Linux
16.04 LTS, [a]
18.04 LTS,
20.04 LTS
Apache HTTP Server 2.4,
NGINX Plus R16, [a][d]
NGINX Plus R17, [a][d]
NGINX Plus R21,
NGINX Plus R22

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

[b] Not supported on CentOS 8

[c] 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.

[d] Not supported on Ubuntu 20.04


Important

  1. Web Agents 5.7 require 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. 32-bit architectures are not supported.

2.2. AM Requirements

Web Agent 5.7 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 Web Agents 5.7:

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.


Important

  1. OpenSSL 1.0.2 or later 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. OpenSSL 1.1.1 or later is required to support TLSv1.3.

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 to Existing Functionality

Web Agent 5.7
  • Changes to the agent-authn-tx Pre-Authentication Cookie

    Web Agents use the agent-authn-tx cookie to track the progress of authentication with AM.

    Earlier versions of Web Agents 5.x created a single cookie containing records to identify all concurrent authentication requests to AM.

    In environments with lots of concurrent requests, or where the protected URLs are long, the cookie can reach the maximum size supported by the browser. When this happens, new authentication requests fail and the agent issues a 403 HTTP message to the user.

    By default, Web Agents 5.7 create a pre-authentication cookie for each authentication request to AM, with the name of agent-authn-tx-string.

    Web Agents 5.7 also introduces the Multivalue for Pre-Authn Cookie property (org.forgerock.openam.agents.config.multivalue.pre.authn.cookies) to control which of the modes it will use when creating pre-authentication cookies.

    During upgrade, be mindful of the names of the cookies if you have them configured in network proxies, load balancers, and similar.

    For more information, see Multivalue for Pre-Authn Cookie in the User Guide.

  • HttpOnly Cookies Now Enabled by Default

    Web Agents 5.7 now set the HttpOnly flag on cookies, which means they can only be transmitted over HTTP or HTTPS protocols. This prevents malicious third-party software or scripts from accessing them.

    New installations of Web Agents 5.7 will have the HTTP Only (com.sun.identity.cookie.httponly) property set to true.

  • Property and Value Pairs Set as Custom Properties Are the Source of Truth

    Earlier versions of the agents do not have a rule to define the source of truth of a property. This means that the source of truth of some properties is the UI value, while for others it is the value set in the Custom Properties UI field.

    Web Agents 5.7 always use the value set in the Custom Properties UI field as the source of truth for that property, if configured.

Chapter 4. Deprecated Functionality

Web Agent 5.7
  • The Exchange SSO Token for JWT (com.forgerock.agents.accept.ipdp.cookie) property is deprecated and will be removed in a later version.

    Use Accept SSO Token in the User Guide instead. For more information about custom login, see "Custom Login Redirection Mode" in the User Guide

Chapter 5. Removed Functionality

Web Agent 5.7
  • No features have been removed from this release.

Chapter 6. Fixes, Limitations, and Known Issues

6.1. Key Fixes

Web Agent 5.7
  • AMAGENTS-2893: Race condition in agent-authn-tx cookie causes lost state identifier's.

  • AMAGENTS-3051: Agent is enforcing case sensitivity for agent_realm parameter in the jwt id_token received from AM

  • AMAGENTS-3181: Blocking READ causes too much buffering on Input FIlter on slow uploading clients.

  • AMAGENTS-3232: WebAgent override Request URL does not takes X-Forwarded-Host may have port.

  • AMAGENTS-3530: naming.url is case sensitive

  • AMAGENTS-3533: Webagent for Varnish returns 500 error on empty PDP request

  • AMAGENTS-3577: AM Console, WPA Profile (i)Pop-Up for log file Size (2 settings) are bootstrap props; NOT Hot-Swappable

  • AMAGENTS-3627: Problem handling notifications after agent token expires

  • AMAGENTS-3652: Infinite loop in am_sdk_handle_subscription when there is an error in net_read_ssl

  • AMAGENTS-3667: When upgrading to agent 5.7.0, certain properties which were set before will no longer have intended effect.

6.2. Limitations

The following limitations and workarounds apply to Web Agent 5.7:

  • The Custom Login Redirection Mode Requires AM 6 or Later

  • Ignore Path Info Properties Is not Supported for NGINX Plus Agent

    The NGINX Plus web agent does not support the following ignore path info properties:

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

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

  • IIS Web Agents May Fail to Install When IIS Configuration Is Locked

    Installing web agents in IIS may fail with an error similar to the following:

    Creating configuration...
        Error: failed to create module entry for MACHINE/WEBROOT/APPHOST/AgentSite/ (error 0x80070021, line: 1823).
        The process cannot access the file because another process has locked a portion of the file. (error: 0x21).
        Installation failed.

    This error message means the agentadmin.exe command cannot access some IIS configuration files because they are locked.

    To work around this issue, perform the following steps:

    1. Open the IIS Manager and select the Configuration Editor.

    2. Unlock the IIS system.webServer/modules module.

    3. Retry the web agent installation.

    Note

    Unlocking the system.webServer/modules module should allow the installation to finish. However, you may need to unlock other modules depending on your environment.

  • 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.

  • IIS Web Agent With Client-Based Sessions Returning HTTP 403 Errors When Accessing Protected Resources

    IIS web agents configured for client-based sessions will return HTTP 403 errors when trying to access a protected resource if the com.sun.identity.client.notification.url property is configured.

    The com.sun.identity.client.notification.url property, used by earlier versions of the web agents to specify the notification listener for the agent, is not used or required anymore. However, to provide backwards-compatibility with earlier versions of the agents, AM populates this property when creating the agent profile.

    The value of this property should removed for all web agents installations, and must be removed for IIS web agents configured for client-based sessions.

  • Default Welcome Page Showing After Upgrade Instead of Custom Error Pages

    After upgrading, you may see the default Apache welcome pages instead of custom error pages defined by the Apache ErrorDocument directive.

    If you encounter this issue, check your Apache ErrorDocument configuration. If the custom error pages are not in the document root of the Apache server, you should enclose the ErrorDocument directives in Directory elements. For example:

    <Directory "/web/docs">
       ErrorDocument 403 myCustom403Error.html
    </Directory>

    Refer to the Apache documentation for more details on the ErrorDocument directive.

  • CA Certificate File Name Property not Honored when Client Authentication is not Required in Secure Channel Environments

    If you are using the Windows built-in Secure Channel API but your environment does not require client authentication, instead of setting the CA certificate friendly name in the CA Certificate File Name Property, set it in the Public Client Certificate File Name property. For example:

    com.forgerock.agents.config.cert.ca.file =
    com.forgerock.agents.config.cert.file = CA-cert-friendly-name
    com.sun.identity.agents.config.trust.server.certs = false
  • Install IIS Web Agents on Child Applications Before Installing in Parent Application

    In an IIS environment where you need to protect a parent application and a child application with different web agent configurations, you must install the web agent on the child application before installing the web agent in the parent. Trying to install a web agent on a child that is already protected will result in error.

6.3. Known Issues

Web Agent 5.7
  • AMAGENTS-2732: com.sun.identity.agents.config.login.url property is no longer ignored

  • AMAGENTS-2813: Agents Logout perform logout multiple times

  • AMAGENTS-3493: Custom login redirection add original_request_url parameter which is not used

  • AMAGENTS-3506: If there are permissions issues with password file with installation on IIS then the log messages are not helpful

  • AMAGENTS-3510: system_0.log logging loop process_dead(): unable to verify liveness of rw lock process n (error 1)

  • AMAGENTS-3567: With the Policy Cache Mode for the Web Agents there is a plugin which if used could mean that policy cache does not work

  • AMAGENTS-3629: Rename references from OpenAM to AM

  • AMAGENTS-3663: Nginx Agent print absolute build path into debug logs

Chapter 7. Documentation Updates

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

Documentation Change Log
DateDescription
August 2020

Initial release of Web Agents 5.7.


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 on ForgeRock's support offering, including support plans and service level agreements (SLAs), visit https://www.forgerock.com/support.

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 :