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.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:
Chapter 1. What's New in Java Agents
Before you install or update Java agents, read these release notes.
1.1. New Minor Release
ForgeRock periodically issues patch and minor releases with important fixes to improve the functionality, performance, and security of your java agent deployments. Java Agents 5.5.1.0 is the latest minor release and can be downloaded from the ForgeRock BackStage website. To view the list of fixes in this release, see Java Agents 5.5.1.0.
Important
Before upgrading to Java Agents 5.5.1.0, consider the following points:
Java Agents 5.5.x only support AM 5.5 and later.
Java Agents 5.5.x use the WebSocket protocol to receive notifications from AM. Both the container and the network infrastructure must support the WebSocket protocol to receive notifications from AM.
1.2. New Features in 5.5
Java Agents 5.5 is a major release that introduces new features, functional enhancements and fixes.
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 "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:
Prometheus
CREST
CSV
For more information about monitoring services, see "Configuring Performance Monitoring" in the User Guide.
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 8.5.5.9 or later is required. [d] Version 12.1.3 or later is required. | |||||||||||||
Important
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:
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.
| Vendor | Version |
|---|---|
| Oracle Java | 8 |
| IBM Java (WebSphere only) | 8 |
| OpenJDK | 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 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
Ability to Specify Name-Value Pairs of Incoming HTTP Request Headers for Conditional Login, Conditional Custom Login, and Custom Logut
Java Agents 5.5.1.0 now supports the ability to specify redirection URLs for conditional login, conditional custom login, and custom logout based on incoming request headers and not only on FQDN parameters. For more information, see Login URL Properties in the User Guide.
Location of Agent Configuration RepositoryProperty Defaults toCENTRALIZEDThe
Location of Agent Configuration Repositoryproperty now defaults to the value ofCENTRALIZED. For more information, see Profile Properties in the User Guide.
There are no important changes in this release.
3.2. Deprecated Functionality
There is no deprecated functionality in this release.
There is no deprecated functionality in this release.
3.3. Removed Functionality
No components were removed in this release.
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.
Removed Properties
Java Agents 5.5 remove support for the following configuration properties:
Service Resolver Class (
com.sun.identity.agents.config.service.resolver)
Chapter 4. Fixes, Limitations, and Known Issues
4.1. Key Fixes
The following important issues were fixed in this release:
AMAGENTS-96: RFE: Base conditional login url on a specific request header instead of on the FQDN of the request.
AMAGENTS-988: Java Agent 5 should not have a value for com.sun.identity.client.notification.url property in OpenSSOAgentConfiguration.properties
AMAGENTS-1964: JASPA: Fix README.md file which is distributed with the Grafana dashboard
AMAGENTS-1966: JASPA: SSO_ONLY mode isn't honoured by the agent.
AMAGENTS-1971: JASPA: Remove (or at least lessen) the "Interface just defines constants" antipattern
AMAGENTS-2044: JASPA: Tidy the code that loads properties on startup.
AMAGENTS-2083: Agent 5.x does not install when the AM server is running on wildfly
AMAGENTS-2099: Cannot run IG and JPA together, SLF4J initialisation failure
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
4.2. Limitations
There are no known limitations and workarounds that apply to Java Agent 5.5.1.0.
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 (
com.sun.identity.agents.config.cdsso.domain) property.Navigate to Realms > Realm Name > Applications > Agents > Java > Agent Name > Global.
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.
4.3. Known Issues
The following important known issues remained opened at the time 5.5.1.0 became available:
AMAGENTS-1965: Java Agent Dashboard Sample Instructions are for AM rather than for Agent
AMAGENTS-2059: JASPA: Change properties handling code.
The following important known issues remained opened at the time 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:
| Date | Description |
|---|---|
| 2018-12-05 | Release of Java Agents 5.5.1.0.
|
| 2018-09-19 | First release of Java 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.
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.