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.

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.6.x, consider the following points:

  • Java Agents 5.6.x only supports AM 5.5 and later.

  • Java Agents 5.6.x 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. Maintenance Releases

ForgeRock maintenance releases contain a collection of fixes and minor RFEs that have been grouped together and released as part of our commitment to support our customers. For general information on ForgeRock's maintenance and patch releases, see Maintenance and Patch Availability Policy.

Java Agents 5.6.3
  • Java Agents 5.6.3 is the latest release targeted for Java Agents 5.6.x deployments and can be downloaded from the ForgeRock Backstage website.

    See the list of fixes here.

1.2. New Features

Java Agents 5.6.3
  • Added Support for Public AM URLs

    Java Agents 5.6.3 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 org.forgerock.agents.public.am.url in the User Guide.

Java Agents 5.6.2.1
  • No new features were introduced in this release, only bug fixes.

Java Agents 5.6.2.0
  • SSO Token Compatibility Properties Added

    Java Agents 5.6.2.0 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 Ability to Specify Cookie and Header Values in Not-enforced Rules

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

  • Allow Agents to Refresh Session's Idle Timeout

    Sessions in AM have an idle timeout after which they expire. In general, when users access protected resources through an agent, the agent requests a policy decision on behalf of that user, which resets the idle timeout.

    When the agent does not need to reach out for AM frequently, however, sessions may unexpectedly expire in AM due to idle timeout before users have finished accessing the application.

    Java Agents 5.6.2.0 includes the new org.forgerock.agents.idle.time.window.minutes property to specify the amount of time the agent will wait before making a call to AM to refresh the session's idle timeout, provided that the user is actively accessing the application or site.

    For more information, see Idle Timeout Window in the User Guide.

Java Agents 5.6.1.1
  • No new features were introduced in this release, only bug fixes.

Java Agents 5.6.1.0
  • No new features were introduced in this release, only bug fixes.

Java Agents 5.6.0
  • No new features were introduced in this release, only bug fixes.

1.3. Major Improvements

Java Agents 5.6.3
  • AMAGENTS-2060: Allow Configuration for amFilterCDSSORequest Expiration Time

  • AMAGENTS-3106: JASPA : Enable redirect to session's successURL if needed.

  • AMAGENTS-3133: JASPA : Deal with samesite=lax issues

  • AMAGENTS-3264: JASPA: Check the browser version(s) and set the samesite cookie attributes if browser supports

Java Agents 5.6.2.1
  • There are no major improvements or enhancements in this release.

Java Agents 5.6.2.0
  • Add TRACE Messages to Login Process

    TRACE-level debugging has been added to better track any issues.

  • New Option to Change Advice Format Value

    Web agents 5.6.2.0 introduces a new property, com.forgerock.agents.advice.b64.url.encode=1, which changes the advice format XML, sent as part of the composite advice by the agent to AM. When the property is enabled, the advice is sent as base64url-encoded data.

    For more information, see AMAGENTS-2973: Create option to Change Advice Format Value

Java Agents 5.6.1.1
  • There are no major improvements or enhancements in this release.

Java Agents 5.6.1.0
  • There are no major improvements or enhancements in this release.

Java Agents 5.6.0
  • Specify Agent Profile Realm During Installation

    Java Agents 5.6 allow you to 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.

1.4. Security Advisories

ForgeRock issues security advisories in collaboration with our customers and the open source community to address any security vulnerabilities transparently and rapidly. ForgeRock's security advisory policy governs the process on how security issues are submitted, received, and evaluated as well as the timeline for the issuance of security advisories and patches.

For details of all the security advisories across ForgeRock products, see Security Advisories in the Knowledge Base.

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,
7
Apache Tomcat 7.0.79,
Apache Tomcat 8.5,
Apache Tomcat 9.0, [a]
Eclipse Jetty 9, [b]
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 6.3.3, [c]
Red Hat JBoss Enterprise Application Platform 7.1,
Red Hat JBoss Enterprise Application Platform 7.2, [a]
WildFly 13,
WildFly 14,
WildFly 15, [a]
WildFly 16 [a]
Ubuntu Linux
16.04 LTS, [c]
18.04 LTS
IBM AIX
6, [c]
7
IBM WebSphere Application Server 8.5.5.9,
IBM WebSphere Application Server 9.0
Microsoft Windows Server
2008 R2, [c]
2012, [c]
2012 R2, [c]
2016
Apache Tomcat 7.0.79,
Apache Tomcat 8.5,
Apache Tomcat 9.0 [a]
Oracle Solaris SPARC,
Oracle Solaris x64
10,
11
Apache Tomcat 7.0.79,
Apache Tomcat 8.5,
Apache Tomcat 9.0, [a]
Oracle WebLogic Server 12c (12.2.1.3)

[a] Supports JDK 11.

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

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


Important

Java Agents uses 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. Access Management Requirements

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

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 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.6.3
  • There are no important changes in functionality in this release, other than bug fixes.

Java Agents 5.6.2.1
  • There are no important changes in functionality in this release, other than bug fixes.

Java Agents 5.6.2.0
  • Cookies Marked as HTTPOnly by Default

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

Java Agents 5.6.1.1
  • There are no important changes in functionality in this release, other than bug fixes.

Java Agents 5.6.1.0
  • There are no important changes in functionality in this release, other than bug fixes.

Java Agents 5.6.0
  • There are no important changes in functionality in this release, other than bug fixes.

3.2. Deprecated Functionality

Java Agents 5.6.3
  • No functionality has been deprecated in this release.

Java Agents 5.6.2.1
  • No functionality has been deprecated in this release.

Java Agents 5.6.2.0
  • No functionality has been deprecated in this release.

Java Agents 5.6.1.1
  • No functionality has been deprecated in this release.

Java Agents 5.6.1.0
  • No functionality has been deprecated in this release.

Java Agents 5.6.0
  • No functionality has been deprecated in this release.

3.3. Removed Functionality

Java Agents 5.6.3
  • No functionality has been removed in this release.

Java Agents 5.6.2.1
  • No functionality has been removed in this release.

Java Agents 5.6.2.0
  • No functionality has been removed in this release.

Java Agents 5.6.1.1
  • No functionality has been removed in this release.

Java Agents 5.6.1.0
  • No functionality has been removed in this release.

Java Agents 5.6.0
  • No functionality has been removed in this release.

Chapter 4. Fixes, Limitations, and Known Issues

4.1. Key Fixes

Java Agents 5.6.3
  • AMAGENTS-2060: Allow Configuration for amFilterCDSSORequest Expiration Time

  • AMAGENTS-2863: Missing Binding JAR for SLF4J

  • AMAGENTS-2892: Agent writes to static value /tmp before debug config attributes are initialised.

  • AMAGENTS-2906: Invalid token makes exception in agent debug log

  • AMAGENTS-2981: Java Agent 5 will not redirect to AMPostAuthProcessInterface.POST_PROCESS_LOGIN_SUCCESS_URL value

  • AMAGENTS-3090: JASPA : ACR is missing in JWT while swapping ssotoken -> JWT when custom login is used.

  • AMAGENTS-3106: JASPA : Enable redirect to session's successURL if needed.

  • AMAGENTS-3118: JASPA: Once again it is impossible to change the debugging level.

  • AMAGENTS-3126: JASPA: Incorrect legacy property used for session polling

  • AMAGENTS-3210: Invent the Java Agents equivalent of com.forgerock.agents.public.am.url

  • AMAGENTS-3215: Java Agent implementation for pre-authentication cookie issues

  • AMAGENTS-3223: JASPA: Agent is redirecting to /am/console, when session successURL is not specified.

  • AMAGENTS-3293: JASPA reporting cookie entry for nonce can't be retrieved from pre-authn bookkeeping cookie if authn takes longer than 5 minutes to complete.

  • AMAGENTS-3305: JASPA throws HTTP 400 when agent receives advices in one cookie per an unauthenticated request

  • AMAGENTS-3384: (JASPA) Redirect loop is possible in tracked custom login mode because invalid sso cookie is not removed

  • AMAGENTS-3389: JASPA: id token cookie is not removed after logout in accept.ipdp.token mode

  • AMAGENTS-3449: Enabling self service causes JWTValidator.validate error in Java Agent

Java Agents 5.6.2.1
Java Agents 5.6.2.0
  • AMAGENTS-2770: Consider removing javax packages from agent jars

  • AMAGENTS-2781: Implement NER improvements

  • AMAGENTS-2815: Reintroduce custom handlers

  • AMAGENTS-2829: Java Agents bundle classes from Java SE 8

  • AMAGENTS-2862: Agent throws error if OpenSSOAgentConfiguration.properties is not there when in central config mode.

  • AMAGENTS-2910: Not enforce requests containing particular cookie or header

  • AMAGENTS-2913: Address issues logging out a user possessing an SSO token as well as, or instead of, a JWT

  • AMAGENTS-2932: NPE when exchanging SSO tokens for JWTs

  • AMAGENTS-2950: Custom login will not auto detect the realm when it is not specified

  • AMAGENTS-2953: Address issues with realm retrieval

  • AMAGENTS-2954: SSO->JWT exchange fails to create cookies when a cached SSO token is found

Java Agents 5.6.1.1
Java Agents 5.6.1.0

The following important issues were fixed in this release:

  • AMAGENTS-2416: Resolve conflicts for depentent external libraries

  • AMAGENTS-2648: Space characters in UID aren't encoded

  • AMAGENTS-2666: It is not possible to login when "Invert Not Enforced URIs" property is set

Java Agents 5.6.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-896: When using local configuration for Agent and setting log level to be message we do not get any output in debug.out

  • AMAGENTS-988: Java Agent 5 should not have a value for com.sun.identity.client.notification.url property in OpenSSOAgentConfiguration.properties

  • AMAGENTS-1035: JASPA initialises data members corresponding to properties it no longer uses.

  • AMAGENTS-1036: com.sun.identity.agents.config.cdsso.enable is ignored for JASPA 5 and should be deleted from OpenSSOAgentConfiguration.properties file

  • AMAGENTS-1578: Java Agent makes error messages when NEU property is empty

  • AMAGENTS-2369: JASPA does not handle token expiry if notifications are disabled, not working, or slow

  • AMAGENTS-2416: resolve conflicts for depentent external libraries

  • AMAGENTS-2431: JASPA: When specifying any agent profile realm, the agent dies on startup

4.2. Limitations

Java Agents 5.6.3
  • There are no new known limitations in this release.

Java Agents 5.6.2.1
  • Remote Audit Logging May Decrease Throughput

    Testing has found that use of remote audit logging may impact performance throughput due to the large number of requests sent from the web agent to AM.

Java Agents 5.6.2.0
  • There are no known limitations in this release.

Java Agents 5.6.1.1
  • There are no known limitations in this release.

Java Agents 5.6.1.0
  • There are no known limitations in Java Agents 5.6.1.0, other than those identified in Java Agents 5.6.0.

Java Agents 5.6.0

The following limitations and workarounds apply to Java Agents 5.6.0:

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

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

4.3. Known Issues

Java Agents 5.6.3
  • There are no new known issues in this release.

Java Agents 5.6.2.1
  • There are no new known issues in this release.

Java Agents 5.6.2.0
  • There are no new known issues in this release.

Java Agents 5.6.1.1
  • There are no known issues in this release.

Java Agents 5.6.1.0
  • There are no known issues in Java Agents 5.6.1.0, other than those identified in Java Agents 5.6.0.

Java Agents 5.6.0
  • AMAGENTS-2585: When uninstalling and reinstalling the Java Agent on windows, we get a message saying "Agent Configuration JVM option ...FAILED"

  • AMAGENTS-2589: The --acceptLicense parameter does not accept license permanently for java agent installer

  • AMAGENTS-2590: The Installer and the Agent Debug Logs should be updated so that the do not refer to Tomcat Agent v 6.0

  • AMAGENTS-2599: Uninstalling Java agent makes fake Failure message

  • AMAGENTS-2616: Java agent installer makes warning messages when JDK 11 is used

Chapter 5. Documentation Updates

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

Documentation Change Log
DateDescription
2020-05-21

Initial release of Java Agents 5.6.3.

The following documentation changes occurred:

  • Updated the documentation with new properties for aliased properties: com.forgerock.agents.public.am.url and org.forgerock.agents.sso.token.exchange.am.url. For more information, see org.forgerock.agents.public.am.url in the User Guide.

2020-02-04

Initial release of Java Agents 5.6.2.1.

2019-11-05

Initial release of Java Agents 5.6.2.0.

The following documentation changes occurred:

  • Updated the documentation with new properties for allowing use of SSO tokens, which can be exchanged for JWTs. These allows 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 documentation about 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.

  • Removed mentions to the INSTALL_GLOBAL_WEB_XML variable from the silent Apache install procedure. Java Agents 5.x do not require this variable.

2019-08-02

Initial release of Java Agents 5.6.1.1.

2019-07-04

Initial release of Java Agents 5.6.1.0.

The following documentation updates were made for this release:

2019-03-29

Initial release of Java Agents 5.6.0.


Appendix A. 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 :