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

Overview

Quick Start

What's New

Discover new features and improvements in this version.

Prepare for Deployment

Learn about the requirements for running Web Agents software in production.

Check Compatibility

Review key implementation changes and compatibility with previous deployments.

Review Fixes

Review bug fixes, limitations, and open issues.

Check Doc Updates

Track important changes to the documentation.

Get Support

Find out where to get professional support and training.


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.

The ForgeRock Common REST API works across the platform to provide common ways to access web resources and collections of resources.

Chapter 1. What's New

1.1. What's New in Web Agents 5.8.2

Web Agents 5.8.2 is a maintenance release. It does not introduce new features.

1.2. What's New in Web Agents 5.8.1

Web Agents 5.8.1 is a maintenance release. It does not introduce new features.

1.3. What's New in Web Agents 5.8

The bootstrap property org.forgerock.agents.config.connection.pool.enable was added for HTTP connection pooling, and is enabled by default.

Use connection pooling to improve performance when AM is available over low bandwidth connections, or to throttle the maximum number of connections made by the agent.

For more information, see org.forgerock.agents.config.connection.pool.enable in the User Guide.

The name of the cookie that the agent accepts as an SSO token, or uses in custom login mode, can now be specified in the property com.sun.identity.agents.config.cookie.name. If the cookie name is not specified, the agent retrieves it from the AM server.

For more information, see Cookie Name in the User Guide, Accept SSO Token in the User Guide, and Custom Login Mode in the User Guide.

A load balancing cookie can now be sent to AM for policy, session, and other calls. Use this property to reduce the number of calls that different AM instances make to the Core Token Service (CTS).

For more information, see AM Load Balancer Cookie Enabled in the User Guide.

Chapter 2. Requirements

Important

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.

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
7,
8
Apache HTTP Server 2.4,
IBM HTTP Server 9,
NGINX Plus R21, [a]
NGINX Plus R22,
NGINX Plus R23
Ubuntu Linux
16.04 LTS, [a]
18.04 LTS,
20.04 LTS
Apache HTTP Server 2.4,
IBM HTTP Server 9,
NGINX Plus R21, [a]
NGINX Plus R22,
NGINX Plus R23
IBM AIX
7
IBM HTTP Server 9
Microsoft Windows Server
2012 R2 [a]
Apache HTTP Server 2.4, [a] [b]
Microsoft IIS 8.5 [a]
2016
Apache HTTP Server 2.4, [b]
Microsoft IIS 10
2019
Apache HTTP Server 2.4, [b]
Microsoft IIS 10

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

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


Important

  1. Web Agents 5.8.2 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 Agents 5.8.2 supports AM 5.5 and later.

  • Web Agents 5.8.2 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.

2.3. OpenSSL Requirements

Web Agents requires 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.8.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.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, run the following command to make sure that libc.so.6 is available, and that it supports the GLIBC_2.3 API:

    $ 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 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 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. Incompatible Changes

3.1. Incompatible Changes in Web Agents 5.8.2

No incompatible changes were introduced in this release.

3.2. Incompatible Changes in Web Agents 5.8.1

No incompatible changes were introduced in this release.

3.3. Incompatible Changes in Web Agents 5.8

No incompatible changes were introduced in this release.

Chapter 4. Deprecation

Deprecation is defined in "Release Levels and Interface Stability".

Deprecated In Object Description

Web Agents 5.7

com.forgerock.agents.accept.ipdp.cookie

For AM 6 or later, use com.forgerock.agents.accept.sso.token instead, as described in Accept SSO Token in the User Guide.

Chapter 5. Removed

Removed is defined in "Release Levels and Interface Stability".

5.1. Incompatible Changes in Web Agents 5.8.2

No features or properties were removed in this release.

5.2. Incompatible Changes in Web Agents 5.8.1

No features or properties were removed in this release.

5.3. Incompatible Changes in Web Agents 5.8

The following property was removed in this release.

Object Description

org.forgerock.agents.config.keepalive.disable

Removed with the introduction of org.forgerock.agents.config.connection.pool.enable for connection pooling.

The removed property is ignored for Web Agents 5.8.

Chapter 6. Fixes

6.1. Fixes in Web Agents 5.8.2

For information about security issues fixed in this release, see "Security Advisories". The following issues were fixed in this release:

  • AMAGENTS-4275: Notifications not working AM with Weblogic Server

  • AMAGENTS-4292: WPA is failing to complete authentication when there is no Content-Length header set on authn POST from AM

  • AMAGENTS-4298: Validator segmentation fault with validate_session_profile test

6.2. Fixes in Web Agents 5.8.1

The following issues were fixed in this release:

  • AMAGENTS-4216: When fragment redirection is enabled, the Agent ignores the query string

  • AMAGENTS-4188: Agent 5.8 will crash with local (not central) configuration.

  • AMAGENTS-4165: agent will not translate http to https in agent/cdsso-oauth2 redirect in SSL offloading case on nginx

  • AMAGENTS-4101: inconsistent behavior for JSON request between web agent 4.2.1.2 and 5.7.0 for content-type header

  • AMAGENTS-4064: fragments don't work in a ssl terminated environment

  • AMAGENTS-3165: Seg Fault if policy evaluation realm properties are null in local configuration.

6.3. Fixes in Web Agents 5.8

The following issues were fixed in this release:

  • AMAGENTS-3986: Web agent is not shutting down correctly, leaving worker processes waiting on semaphores.

  • AMAGENTS-3848: com.sun.identity.agents.config.local.log.size does not work in agent.conf

  • AMAGENTS-3818: Upgrade source bundled PCRE library to PCRE2

  • AMAGENTS-3780: (MIME) UTF-8 base64 headers encoding is missing "?=" at the end of encoded value

  • AMAGENTS-3718: Webagent does not read getSessionInfo response attributes outside "properties" element

  • AMAGENTS-3682: Agent 5.7 fragment support incompatible with pattern-based conditional login

6.4. Security Advisories

ForgeRock issues security advisories in collaboration with our customers and the open source community to address any security vulnerabilities transparently and rapidly. ForgeRock's security advisory policy governs the process on how security issues are submitted, received, and evaluated as well as the timeline for the issuance of security advisories and patches.

For details of all the security advisories across ForgeRock products, see Security Advisories in the Knowledge Base library.

Chapter 7. Limitations

7.1. Limitations in Web Agents 5.8.2

No additional limitations were introduced in this release.

7.2. Limitations in Web Agents 5.8.1

No additional limitations were introduced in this release.

7.3. Limitations in Web Agents 5.8

The following limitations are inherent to the design, not bugs to be fixed:

Redirect of users to a specific AM instance, an AM site, or website other than AM, requires AM 6 or later versions. For more information, see "Login Redirection and Login Conditional Redirection" in the User Guide.

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

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.

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

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.

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

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.

Chapter 8. Known Issues

Web Agents issues are tracked at https://bugster.forgerock.org/jira/browse/AMAGENTS.

8.1. Known Issues in Web Agents 5.8.2

No additional issues were opened in this release.

8.2. Known Issues in Web Agents 5.8.1

No additional issues were opened in this release.

8.3. Known Issues in Web Agents 5.8

The following important issue remained open at the time of this release:

  • 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-3507: We still use locale (%Z) on windows logging time even though were statically UTC

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

  • AMAGENTS-3798: The AM Conditional Login URL should check that the entry has a | in it

  • AMAGENTS-3864: Cannot install web agent if the AM URL does not return 302

  • AMAGENTS-3992: com.forgerock.agents.config.hostmap does not seem to use the IP address

Chapter 9. Documentation

DateDescription
May 2021

Release of Web Agents 5.8.2 software.

April 2021

Release of Web Agents 5.8.1 software.

February 2021

Release of Web Agents 5.8 software.

In addition to the changes described elsewhere in these notes, the following important changes were made to the documentation:

New documents
  • The ForgeRock Identity Cloud Guide was added to provide examples of how to integrate your business application and APIs with ForgeRock Identity Cloud.

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 :