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.
Read these release notes before installing Java Agents 5.5.
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™ is the only offering for access management, identity management, user-managed access, directory services, and an identity gateway, designed and built as a single, unified platform.
The platform includes the following components that extend what is available in open source projects to provide fully featured, enterprise-ready software:
ForgeRock Access Management (AM)
ForgeRock Identity Management (IDM)
ForgeRock Directory Services (DS)
ForgeRock Identity Gateway (IG)
ForgeRock Identity Message Broker (IMB)
Chapter 1. What's New in Java Agents
Before you install or update Java agents, read these release notes.
1.1. New Features
Java Agents 5.5 is a major release that introduces new features, functional enhancements and fixes.
Java Agents 5.5 only support AM 5.5 and later. For more information, see Section 2.2, "Access Management Requirements".
Query Parameter Handling
Java Agents 5.5 introduces a number of properties to retain or remove nominated query parameters from incoming URL requests. Removing or retaining parameters affects the way the agent saves URLs in the policy decision cache, which may help your environment to achieve more cache hits, improving performance.
For more information, see Section 1.4.12, "Query Parameter Handling" in the User Guide.
New Monitoring Interfaces
Java Agents 5.5 introduces new monitoring interfaces to expose performance metrics about the agent instance.
Additionally, if further analysis and visualization are required, tools such as Grafana can be used to create customized charts and graphs based on the information collected by monitoring.
The following monitoring interfaces have been added:
For more information about monitoring services, see Section 4.3, "Configuring Performance Monitoring" 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:
|Operating Systems (OS)||OS Versions||Web Application Containers & Versions|
[a] Version 7.0.79 or later is required.
[b] Version 6.3.3 or later is required.
[c] Version 220.127.116.11 or later is required.
[d] Version 12.1.3 or later is required.
Java Agents use the WebSocket protocol to receive notifications from AM. Both the Java container and the network infrastructure must support the WebSocket protocol to receive notifications from AM.
2.2. Access Management Requirements
Java Agents 5.5 do not interoperate with:
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.
|IBM Java (WebSphere only)||8|
2.4. Supported Clients
The following table summarizes supported clients and their minimum required versions:
|Client Platform||Native Apps[a]||Chrome 33+||Internet Explorer 9+ [b]||Edge 0.1+||Firefox 28+||Safari 6.2+||Mobile Safari|
|Windows 7 or later|
|Mac OS X 10.8 or later|
|Ubuntu 12.04 LTS or later|
|iOS 7 or later|
|Android 4.3 or later|
[a] Native Apps is a placeholder to indicate AM is not just a browser-based technology product. An example of a native app would be something written to use AM's REST APIs, such as the sample OAuth 2.0 Token Demo app.
[b] Internet Explorer 9 is the minimum required for end users. For the administration console, Internet Explorer 11 is required.
2.5. Special Requests
If you have a special request regarding support for a combination not listed here, contact ForgeRock at firstname.lastname@example.org.
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
There are no important changes in this release.
3.2. Deprecated Functionality
There is no deprecated functionality in this release.
3.3. Removed Functionality
Sample Applications Removed
Java Agents 5.5 do not include the sample applications that demonstrated how to configure container security, which is not applicable since Java Agents 5.
Java Agents 5.5 remove support for the following configuration properties:
Service Resolver Class (
Chapter 4. Fixes, Limitations, and Known Issues
4.1. Key Fixes
The following important issues were fixed in this release:
AMAGENTS-1851: Errors Authentication when using Authn Tree and Java Agents
AMAGENTS-1799: J2EEAgent bundles ESAPI and causes Users Webapp with ESAPI issues
AMAGENTS-1571: Alternative Agent Port Number not working in a LB env when sso cookie is present
AMAGENTS-1537: Agent 5 does not have standard solution for custom login pages.
AMAGENTS-1516: JASPA: password encryption via the admin tool throws an exception
AMAGENTS-1368: Java Agent: Implement angular.js solution
The following limitations and workarounds apply to Java Agent 5.5:
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:
Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > SSO.
Remove all cookie domains from the CDSSO Domain List (
Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > Global.
Configure any required entries in the Agent Root URL for CDSSO (
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:
4.3. Known Issues
The following important known issues remained opened at the time release 5.5.0 became available:
AMAGENTS-1966: The global SSO_ONLY mode is not honoured by the agent
AMAGENTS-1578: Java Agent makes error messages when NEU property is empty
AMAGENTS-1036: com.sun.identity.agents.config.cdsso.enable is ignored for JASPA 5 and should be deleted from OpenSSOAgentConfiguration.properties file
AMAGENTS-1035: JASPA initialises data members corresponding to properties it no longer uses.
AMAGENTS-990: OpenSSOAgentConfiguration and OpenSSOAgentBootstrap properties files contains container versions
AMAGENTS-988: Java Agent 5 should not have a value for com.sun.identity.client.notification.url property in OpenSSOAgentConfiguration.properties
AMAGENTS-896: When using local configuration for Agent and setting log level to be message we do not get any output in debug.out
Chapter 5. Documentation Updates
The following table tracks changes to the documentation set following the release of Java Agents 5.5:
First release of Web Agents 5.5
Appendix A. Getting Support
For more information or resources about AM and ForgeRock Support, see the following sections:
A.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.
A.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.
A.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.