Release notes
ForgeRock supports and maintains versions according to the ForgeRock Product Support Lifecycle Policy | IG and Agents. Some older Web Agent versions have reached Product End of Life (EOL). If you are still running an EOL version, upgrade as soon as possible to an actively maintained version.
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.
What’s new
Remove HTTP Server header in IIS
In IIS, the agent can now remove the Server header from all responses.
To enable the feature, set the
Remove IIS HTTP Server Header property
(org.forgerock.agents.config.iis.headers.server.disable) to true.
Limit the number of stored log files
To help manage the amount of stored data, the new property Maximum Number of Debug Log Files is now available to limit the number of rotated log files that the agent stores.
SUSE Linux Enterprise
Apache Web Agent now supports SUSE Linux Enterprise 15.
Log agent errors in the Apache log system
In Apache Web Agent, it is now possible to cause the agent error logs to appear in the Apache log system. For more information, refer to Configure error logs.
Requirements
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.
Supported operating systems and web servers
| Operating systems | OS versions | Web servers & minimum supported versions |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(1)For information about which version of CentOS to use with the listed
NGINX Plus, refer to the Nginx Plus documentation.
(2)Support to be discontinued in a future release.
(3)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.
| 32-bit architectures are not supported. |
AM requirements
-
Web Agent 2023.3 supports AM 6.5 and later.
-
Web Agent 2023.3 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_modulefor 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 |Enable Custom Login Mode property. For more information about changes introduced in Web Agent 5, refer to the Web Agent 5 Release notes.
OpenSSL requirements
| Web Agent no longer works with OpenSSL versions lower than 1.1.1. It is essential to upgrade if you are using an earlier version. |
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.
| Operating systems | OpenSSL versions |
|---|---|
|
|
|
|
|
|
(1)On Windows, Web Agent uses the Windows built-in Secure Channel API by default.
Other requirements
Before installing Web Agent on your platform, make sure the system meets the following requirements:
Linux systems
-
Web Agent on Linux supports Glibc 2.17 and later versions, and is compatible with Glibc 2.14 and later versions. For Glibc versions before 2.14, contact ForgeRock Support.
-
Web Agent on Linux requires a minimum of 16 MB of shared memory for the session and policy cache, and the various worker processes. Additionally, it needs 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, refer to Environment variables.
-
If Enable POST Data Preservation is
true, and POST Data Storage Directory takes its default value ofweb_agents/agent_type/instances/agent_n/log, the agent requires additional free disk space in thelogdirectory to store the POST data.
Microsoft Windows systems
-
Before installing the IIS web agent, make sure 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 Agent on Windows requires a minimum of 16 MB of shared memory for the session and policy cache, and the various worker processes in the system page file. Additionally, it needs 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, refer to Environment variables.
-
If Enable POST Data Preservation is
true, and POST Data Storage Directory takes its default value ofweb_agents/agent_type/instances/agent_n/log, the agent requires additional free disk space in thelogdirectory to store the POST data.
Special requests
If you need support for a combination not listed here, contact ForgeRock at info@forgerock.com.
Incompatible changes
NGINX binaries renamed
NGINX binaries on Backstage have been renamed as follows:
-
Old name format:
web-agent-version-NGINX_rn_Centosn_64bit.zip -
New name format:
web-agent-version-NGINX_rn_Rheln_64bit.zip
OpenSSL support
The following versions of OpenSSL are no longer supported:
| Operating systems | OpenSSL versions |
|---|---|
|
|
|
|
|
|
For more information, refer to OpenSSL requirements.
Deprecation
The following objects are deprecated, as defined in Release levels and interface stability:
| Deprecated in | Object/description | Removed in |
|---|---|---|
Web Agent 5.10.1 |
Monitoring endpoint. Refer to Monitoring |
Not yet removed |
Web Agent 5.9 |
|
Web Agent 2023.3 |
|
Web Agent 2023.3 |
|
|
Web Agent 2023.3 |
|
|
Web Agent 2023.3 |
Removed
The following objects are removed, as defined in Release levels and interface stability:
| Removed in | Object/description | Deprecated in |
|---|---|---|
Web Agent 2023.3 |
|
Web Agent 5.9 |
|
Web Agent 5.9 |
|
|
Web Agent 5.9 |
|
|
Web Agent 5.9 |
Fixes
The following issue was fixed in this release:
-
AMAGENTS-5341: Installer crashes when checking permissions
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.
Limitations
The following limitations are inherent to the design, not bugs to be fixed:
Custom login redirection mode
Redirect of users to a specific AM instance, an AM site, or website other than AM. For more information, refer to Login redirect.
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:
-
Open the IIS Manager and select the Configuration Editor.
-
Unlock the IIS
system.webServer/modulesmodule. -
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
com.sun.identity.client.notification.url is configured.
The com.sun.identity.client.notification.url property is removed in this release.
Earlier versions of Web Agent use it to specify the notification listener
for the agent. 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 agent 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 HTTP 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 = falseInstall 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.
Known issues
The following important issue remained open at the time of this release:
-
AMAGENTS-5495: Web agent validator reports access to OpenSSL v.1.1.x instead of v3.x
-
AMAGENTS-5594: Web agent will return 403 errors if OpenSSL libraries aren’t loaded.
Documentation
| Date | Description |
|---|---|
March 2023 |
Initial release of Web Agent 2023.3 software.
|
Appendix A: Release levels and interface stability
For information about release levels, refer to ForgeRock Product Support Lifecycle Policy | IG and Agents.
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.
| Stability Label | Definition |
|---|---|
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. |
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 everyone, 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.