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

1.1. New Features

Web Agents 5.6

Web Agents 5.6 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 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.2. Major Improvements

Web Agents 5.6
  • 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 use the WebSocket protocol to receive notifications from AM. Both the web server and the network infrastructure must support the WebSocket protocol to receive notifications from AM. For example, Apache HTTP server requires the proxy_wstunnel_module module for proxying the WebSocket protocol.

    For more information, refer to your network infrastructure and web server documentation.

  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 does not interoperate with:

  • OpenAM

  • AM versions earlier than 5.5.

2.3. OpenSSL Requirements

Agents require OpenSSL or the native Windows SSL libraries to be present. These libraries help to secure communications, for example when connecting to AM using websockets.

The following table summarizes OpenSSL support in Agents 5.6:

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 native Windows SSL libraries by default.


Note

OpenSSL 1.0.2 or newer is required to support 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
  • 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 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
  • There is no deprecated functionality in this release.

3.3. Removed Functionality

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

Chapter 4. Fixes, Limitations, and Known Issues

4.1. Key Fixes

Web Agents 5.6
  • 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

The following limitations and workarounds apply to Web Agents 5.6:

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

4.3. Known Issues

Web Agents 5.6
  • 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-03-29

Initial release of Web Agents 5.6


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 Interface Stability

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

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

Interface Stability Definitions
Stability LabelDefinition

Stable

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

Deprecated

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

Removed

This 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 evolving new technology that are 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 interfaces can change without notice. If you depend on one of these interfaces, contact ForgeRock support or email info@forgerock.com to discuss your needs.


Appendix B. Getting Support

For more information or resources about AM and ForgeRock Support, see the following sections:

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

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

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