Notes covering new features, fixes and known issues for ForgeRock® Access Management Java agents. ForgeRock Access Management provides open source authentication, authorization, entitlement and federation software.

Preface

Read these release notes before installing Java Agents 5.7.

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 Java Agents

Before you install or update Java agents, read these release notes.

Important

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

  • Java Agents 5.7 only support AM 5.5 and later.

  • Java Agents 5.7 use the WebSocket protocol to communicate with AM. Both the Java container and the network infrastructure must support the WebSocket protocol.

    Refer to your network infrastructure and Java container documentation for more information about WebSocket support.

  • If you are upgrading from a version earlier than 5, Java Agents 5 introduced notable changes. For example, they dropped support for JAAS and require you to enable a new property if you are not using the AM UI as the login page.

    For more information about changes introduced in Java Agents 5, refer to the Java Agents 5 Release Notes.

1.1. New Features

Java Agents 5.7

Java Agents 5.7 is a major release that introduces new features, functional enhancements and fixes.

Important

Java Agents 5.7 only support AM 5.5 and later. For more information, see "AM Requirements".

  • Added Debug File Rotation Properties

    Java Agents 5.7 adds properties for rotating debug log files by size and time, and limiting the number of rotated debug log files to retain.

    For more information, see "Debug and Metric Properties" in the User Guide.

  • Added SSO Token Compatibility Properties

    Java Agents 5.7 adds properties for allowing use of SSO tokens, which can be exchanged for JWTs, therefore allowing a mixture of older and newer agents in a deployment.

    For more information, see Enabling Support for Exchanging SSO Tokens in the User Guide.

  • Added Autonomous "Fallback" Mode

    Java Agents 5.7 adds a com.forgerock.agents.config.fallback.mode bootstrap property, which enables the agents to run in an autonomous, "fallback" mode, independently of an AM instance.

    The agents will allow access as defined by not-enforced rules, and block access to everything else.

    For more information, see "Autonomous "Fallback" Mode" in the User Guide.

  • Added Ability to Specify Cookie and Header Values in Not-enforced Rules

    Java Agents 5.7 adds the ability to specify cookie and header values in not-enforced rules, and combine them with HTTP methods.

    For more information, see Not-Enforced URI Processing Properties in the User Guide.

  • Added Ability to Include Reason for Authentication in Custom Redirection Login Mode

    Java Agents 5.7 adds the ability to add a parameter with a value that includes the reason authentication is required. The parameter is included in the URL used when the agent redirects to a custom URL for authentication, and can be used to provide additional feedback to the user.

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

  • Added Support for Jetty Base Path

    The Jetty Java Agent 5.7 adds support for specifying the Jetty base path (the equivalent to the JETTY_BASE environment variable for Jetty) during the agent installation process.

    For more information, see "Installing the Jetty Java Agent" in the User Guide.

  • Added Support for Redirecting to AM's Success URL

    Java Agents 5.7 support redirecting the end user to the success URL configured in the AM authentication service they used to authenticate.

    For more information, see the Redirect to AM's Success URL property in Login Processing Properties in the User Guide.

  • Added Support for Customizing Authentication Error Messages

    By default, after an authentication failure error, Java agents return an HTTP 400 message regardless of the reason that caused the failure in the first place.

    Java Agents 5.7 lets you redirect the end user to a specific URL or URI, as well as customize the error message based on the reason, if required. For more information, see "Authentication Failure Notification" in the User Guide.

  • Added Support for Configuring the Authentication Tracking Cookie

    Java agents use a cookie for tracking the progress of authentication with AM.

    By default, the agent uses one cookie to track all authentication requests. If the number of concurrent requests is large enough, the cookie may exceed the browser size limit and requests will fail.

    Java Agents 5.7 lets you configure the agent so it creates one cookie for each authentication request to AM. For more information, see the Authentication Tracking Cookie Name (org.forgerock.agents.authn.cookie.name) property in Cookie Properties in the User Guide.

  • Added Support for Public AM URLs

    Java Agents 5.7 includes a new bootstrap property, org.forgerock.agents.public.am.url, that specifies the public URL of the AM instance.

    Use this property only if:

    • The agent is using the custom login redirection mode (custom login pages using SSO tokens).

    • The custom login pages are not in the same domain as the agent, and there is a proxy, firewall, or any other technology that remaps URLs between AM and the custom login pages.

    Consider an example where the traffic between AM and the agent happens through the example-internal.com network, but the custom login pages are on the example-external.com domain. In this case, you would configure https://openam.example-external.com:8443/openam as the public AM URL.

    For more information, see AM Public URL in the User Guide.

  • Added Property Aliasing

    Java Agents 5.7 introduces aliases for configuration and bootstrap properties.

    For more information, see "About Java Agent Properties" in the User Guide.

1.2. Major Improvements

No major improvements have been added in this release.

Chapter 2. Before You Install

This section covers software and hardware prerequisites for installing and running Java Agents.

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 & Web Application Containers
Operating Systems (OS)OS VersionsWeb Application Containers & Minimum Supported Versions
Amazon Linux 2,
CentOS,
Oracle Linux,
Red Hat Enterprise Linux
6, [a]
7,
8
Apache Tomcat 7.0.79, [a]
Apache Tomcat 8.5,
Apache Tomcat 9.0, [b]
Eclipse Jetty 9, [c]
IBM WebSphere Application Server 8.5.5.9,
IBM WebSphere Application Server 9.0,
Oracle WebLogic Server 12c (12.2.1.3),
Red Hat JBoss Enterprise Application Platform 7.1, [a]
Red Hat JBoss Enterprise Application Platform 7.2, [b]
Red Hat JBoss Enterprise Application Platform 7.3, [b]
WildFly 19, [b]
WildFly 20 [b]
Ubuntu Linux
16.04 LTS, [a]
18.04 LTS,
20.04 LTS
IBM AIX
7
IBM WebSphere Application Server 8.5.5.9,
IBM WebSphere Application Server 9.0
Microsoft Windows Server
2012 R2, [a]
2016
2019
Apache Tomcat 7.0.79, [a]
Apache Tomcat 8.5,
Apache Tomcat 9.0 [b]
Oracle Solaris SPARC,
Oracle Solaris x64
11 [a]
Apache Tomcat 7.0.79, [a]
Apache Tomcat 8.5,
Apache Tomcat 9.0, [b]
Oracle WebLogic Server 12c (12.2.1.3)

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

[b] Supports JDK 11.

[c] Version 9.4.13 or later is required for JDK 11 support.


Important

Java Agents use the WebSocket protocol to communicate with AM. Both the Java container and the network infrastructure must support the WebSocket protocol.

Refer to your network infrastructure and Java container documentation for more information about WebSocket support.

2.2. AM Requirements

Java Agents 5.7 do not interoperate with:

  • OpenAM

  • AM versions earlier than 5.5.

2.3. Java Requirements

Java agents run in a Java container, and require a Java Development Kit.

ForgeRock supports customers using the following Java versions. ForgeRock recommends the most recent Java update, with the latest security fixes.

Supported Java Development Kit Versions
VendorVersion
Oracle Java8, 11
IBM Java (WebSphere only)8
OpenJDK8, 11

For information on the web container requirements for JDK 11, see "Platform Requirements".

2.4. Supported Clients

The following table summarizes supported clients and their minimum required versions:

Supported Clients
Client Platform Native Apps [a] Chrome 62+Internet Explorer 11+Edge 25+Firefox 57+Safari 11+Mobile Safari
Windows 8 or later [b]   
Mac OS X 10.11 or later     
Ubuntu 14.04 LTS or later      
iOS 9 or later     
Android 6 or later      

[a] Native Apps is a placeholder to indicate the platform is not limited to browser-based technologies. An example of a native app would be something written to use our REST APIs.

[b] Windows 10 only.


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

Java Agents 5.7
  • Specify Agent Profile Realm During Installation

    Java Agents 5.7 lets you specify the realm in which the agent profile exists, making the process easier if you are not using the top-level realm.

    Performing installation using an existing response file that does not specify the realm will assume the top-level realm.

    For more information, see "Installing Java Agents" in the User Guide.

  • Added SSO Token to JWT Exchange Metrics

    Java Agents 5.7 adds a number of SSO token to JWT exchange-related monitoring metrics.

    For more information, see "SSO Token to JWT Exchange Metrics" in the User Guide.

  • Cookies Marked as HTTPOnly by Default

    Java Agents 5.7 sets the com.sun.identity.cookie.httponly property to true by default.

    If you are upgrading from a previous version and have scripts that require access to the contents of the cookies set by the agent, you should switch this property to false.

  • Access to Favicon Files Not-Enforced by Default

    Java Agents 5.7 allows all access to files named favicon.ico by default.

    To disable this feature, set the org.forgerock.agents.auto.not.enforce.favicon property to false.

    For more information, see Not-Enforced URI Processing Properties in the User Guide.

  • com.iplanet.am.session.client.polling.enable Property Renamed

    The com.iplanet.am.session.client.polling.enable property, which specifies whether the agent should subscribe to AM for notifications, has been renamed to com.iplanet.am.session.client.polling.enabled.

  • Changes to the Debug File Properties

    Java Agents 5.7 introduces changes to the following debug file properties:

    • Debug File Rotation Suffix (org.forgerock.agents.debug.suffix).

      The default value has changed from -1 to be unset.

    • Debug File Rotation Size (org.forgerock.agents.debug.rotation.size.bytes).

      The default value has changed from -1 to be unset. If this property is set but Debug File Rotation Suffix is not enabled, the agent uses a value of -yyyy.MM.dd-HH.mm as the suffix.

    • Debug File Rotation Time (org.forgerock.agents.debug.rotation.time.minutes).

      The default value has changed from -1 to be unset. If this property is set but Debug File Rotation Suffix is not enabled, the agent uses a value of -yyyy.MM.dd-HH.mm as the suffix.

Chapter 4. Deprecated Functionality

Java Agents 5.7
  • No features have been deprecated in this release.

Chapter 5. Removed Functionality

Java Agents 5.7
  • Ignore Path Info Property Removed

    Java Agents 5.7 removes the Ignore Path Info (com.sun.identity.agents.config.ignore.path.info, org.forgerock.agents.ignore.path.info.enabled) property.

    Java Agents 5.7 uses alternative, internal methods to ensure a not-enforced rule such as /*.gif cannot be abused; for example, by attempting to access http://host/index.html#hack.gif.

Chapter 6. Fixes, Limitations, and Known Issues

6.1. Key Fixes

Java Agent 5.7
  • AMAGENTS-2648: Space Characters in UID aren't encoded.

  • AMAGENTS-3050: JASPA - Need to redirect a standard page instead of FORBIDDEN when nonce is missing in jwt/cookie

  • AMAGENTS-3517: JASPA: Fix validate call which is broken for restricted tokens

6.2. Limitations

The following limitations and workarounds apply to Java Agent 5.7:

  • CDSSO Domain List Restrictions for WildFly and JBoss

    Cookie support in WildFly and JBoss has been implemented so that only one cookie can be set with a certain name. This prevents setting the same cookie for multiple domains.

    Configuring the CDSSO Doimain List policy agent property with more than one cookie domain may result in redirection loops.

    To work around this issue, perform the following steps:

    1. Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > SSO.

    2. Remove all cookie domains from the CDSSO Domain List (com.sun.identity.agents.config.cdsso.domain) property.

    3. Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > Global.

    4. Configure any required entries in the Agent Root URL for CDSSO (sunIdentityServerDeviceKeyValue) property.

    The Java agent will set the cookie domain based on the requested resource.

  • CDSSO Domain List Restrictions for Tomcat

    Tomcat 8.0.x introduced a new cookie processor, org.apache.tomcat.util.http.Rfc6265CookieProcessor, that became the default cookie processor on Tomcat 8.5.x.

    Due to the new cookie processor's cookie validation checks, configuring domains with leading dots (.) in the CDSSO Cookie Domain List property (com.sun.identity.agents.config.cdsso.domain) may result in the following issues:

    • Java agents returning HTTP 403 errors.

    • Tomcat server logging messages similar to the following:

      ERROR: AmFilter: Error while delegating to inbound handler: CDSSO Result Task Handler, access will be denied
      java.lang.IllegalArgumentException: An invalid domain [.example.com] was specified for this cookie
      at org.apache.tomcat.util.http.Rfc6265CookieProcessor.validateDomain(Rfc6265CookieProcessor.java:183)
      at org.apache.tomcat.util.http.Rfc6265CookieProcessor.generateHeader(Rfc6265CookieProcessor.java:125)
      at org.apache.catalina.connector.Response.generateCookieString(Response.java:989)
      at org.apache.catalina.connector.Response.addCookie(Response.java:937)
      at org.apache.catalina.connector.ResponseFacade.addCookie(ResponseFacade.java:386)
      at com.sun.identity.shared.encode.CookieUtils.addCookieToResponse(CookieUtils.java:412)
      ...

    To work around this issue, perform one of the following actions:

    • Configure the legacy cookie processor implementation, org.apache.tomcat.util.http.LegacyCookieProcessor, in your Tomcat server. Refer to the documentation for your version of Tomcat for more information.

    • Ensure the domains entered in the CDSSO Cookie Domain List property start with a number or a letter. For example:

      Valid configuration

      com.sun.identity.agents.config.cdsso.domain[0]=example.com
      com.sun.identity.agents.config.cdsso.domain[1]=123company.com

      Invalid configuration

      com.sun.identity.agents.config.cdsso.domain[0]=.example.com
      com.sun.identity.agents.config.cdsso.domain[1]=.mycompany.com
  • The agentadmin Command Shows Warning Messages When Using JDK 11

    The agentadmin command may show warning messages similar to the following when using JDK 11:

    WARNING: An illegal reflective access operation has occurred
        WARNING: Illegal reflective access by org.forgerock.openam.sdk.com.google.inject.internal.cglib.core.$ReflectUtils$1 ...
        WARNING: Please consider reporting this to the maintainers of org.forgerock.openam.sdk.com.google.inject.internal.cglib.core.$ReflectUtils$1
        WARNING: Use --illegal-access=warn to enable warnings of further illegal reflective access operations
        WARNING: All illegal access operations will be denied in a future release

    You can safely ignore these messages.

6.3. Known Issues

Java Agent 5.7
  • No issues were open at the time of the release.

Chapter 7. Documentation Updates

The following table tracks changes to the documentation set following the release of Java Agents 5.7:

Documentation Change Log
DateDescription
August 2020

First release of Java 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 :