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:

  • 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

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

Important

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:

    • Prometheus

    • CREST

    • CSV

    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:

Table 2.1. 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.

Table 2.2. 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:

Table 2.3. 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
  • There are no important changes in this release.

3.2. Deprecated Functionality

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

3.3. Removed Functionality

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

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

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.

  • 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

4.3. Known Issues

Java Agents 5.5

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:

Table 5.1. Documentation Change Log
DateDescription
2018-09-19

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.

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 :