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

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

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:

Supported Operating Systems & Web Application Containers
Operating Systems (OS)OS VersionsWeb Application Containers & Versions
CentOS
Red Hat Enterprise Linux
Oracle Linux
Amazon Linux 2
6, 7
Apache Tomcat 7 [a], 8, 8.5, 9.0
Red Hat JBoss Enterprise Application Platform 6 [b], 7.1
WildFly 9, 10.1, 11, 12
IBM WebSphere Application Server 8.5 [c], 9.0
Eclipse Jetty 9
Oracle WebLogic Server 12c [d]
Microsoft Windows Server
2008 R2, 2012, 2012 R2, 2016
Apache Tomcat 7 [a], 8, 8.5, 9.0
Oracle Solaris x64
Oracle Solaris SPARC
10, 11
Apache Tomcat 7 [a], 8, 8.5, 9.0
Oracle WebLogic Server 12c [d]
Ubuntu Linux
14.04 LTS, 16.04 LTS, 18.04 LTS
Apache Tomcat 7 [a], 8, 8.5, 9.0
Red Hat JBoss Enterprise Application Platform 6 [b], 7.1
WildFly 9, 10.1, 11, 12
IBM WebSphere Application Server 8.5 [c], 9.0
Eclipse Jetty 9
Oracle WebLogic Server 12c [d]
IBM AIX
6, 7
IBM WebSphere Application Server 8.5 [c], 9.0

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

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

2.4. Supported Clients

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

Supported Clients
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

Java Agents 5.5.1.0
  • 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 Repository Property Defaults to CENTRALIZED

    The Location of Agent Configuration Repository property now defaults to the value of CENTRALIZED. For more information, see Profile Properties in the User Guide.

Java Agents 5.5
  • There are no important changes in this release.

3.2. Deprecated Functionality

Java Agents 5.5.1.0
  • There is no deprecated functionality in this release.

Java Agents 5.5
  • There is no deprecated functionality in this release.

3.3. Removed Functionality

Java Agents 5.5.1.0
  • No components were removed in this release.

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

Java Agents 5.5.1.0

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

Java Agents 5.5

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

Limitations in 5.5.1.0
  • There are no known limitations and workarounds that apply to Java Agent 5.5.1.0.

Java Agents 5.5.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:

    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.

4.3. Known Issues

Java Agents 5.5.1.0

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.

Java Agents 5.5

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:

Documentation Change Log
DateDescription
2018-12-05

Release of Java Agents 5.5.1.0.

  • Updated the section to secure communications between AM and the agents to include information about AM 6.5 and later. For more information, see "Configuring Access Management Servers to Communicate With Java Agents" in the User Guide.

  • Updated entries in the Reference for AM Conditional Login URL, AM Custom Conditional Login URL, and AM Conditional Logout URL properties. These entries now accept incoming request headers in addition to Domain/path to redirect the user to the specific URL. For more information, see "Configuring AM Services Properties" in the User Guide.

  • Updated text for the Location of the Agent Configuration Repository property. For more information, see Profile Properties in the User Guide.

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.

Read a different version of :