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.
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.
Before upgrading to Java Agents 5.x, consider the following points:
Java Agents 5.x only support AM 5.5 and later.
Java Agents 5.x 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.
Java Agents 5.x's configuration is considerably different from that of earlier versions. For example, if you were using custom login pages in an earlier version, you must enable a new property for backwards-compatibility.
Read the Release Notes to understand the impact of the changes before upgrading.
1.1. Patch Releases
Java Agents 220.127.116.11 Patch Release
ForgeRock periodically issues patch releases with important fixes to bugs. Java Agents 18.104.22.168 is the latest patch release, targeted for Java Agents 5.0.1 deployments and can be downloaded from the ForgeRock BackStage website. To view the list of fixes in this release, see Java Agents 22.214.171.124.
ForgeRock patch releases are aimed as a fast-track method to provide fixes to existing bugs. These fixes improve the functionality, performance and security of your deployment. No new features have been introduced.
Java Agents 5.0.1 is available for download and can be found at the ForgeRock BackStage website.
1.2. New Features
Java Agents 5.0.1 is a maintenance release containing key fixes and a new feature:
Support for Custom Redirection Login Pages
Starting from 5.0.1, Java Agents introduce a custom redirection login mode that supports:
Environments that already have customized login pages that expect user sessions to be stored in SSO tokens instead of in OIDC JWTs, whether these are XUI login pages or not.
Environments configured so the users cannot access the AM servers directly.
Environments configured so the custom login pages are not part of AM's XUI.
To support the custom redirection login mode, Java Agents 5.0.1 include the following properties:
OpenAM Login URL
com.sun.identity.agents.config.login.url(this property was removed in Java Agents 5, and it has been reinstated)
For more information, see Section 1.4.10, "Redirection and Conditional Redirection" in the User Guide.
Java Agents 5 is a major release that introduces new features, functional enhancements and fixes.
Communication With AM Uses the OAuth 2.0 Authorization Framework
Java agents and AM exchange OpenID Connect JSON web tokens (JWTs) containing the information required to authenticate clients and authorize access to protected resources. The former method of communication, platform lower-level (PLL) calls, is no longer used.
To ensure integrity, AM signs the JWTs with the
testkey alias by default. To change the signing key, see Section 2.2, "Configuring Access Management Servers to Communicate With Java Agents" in the User Guide.
Decoding JWTs into JSON objects is a CPU-intensive operation. To reduce the amount of processing required on each request, Java agents cache decoded JWTs. The following properties control the cache's behavior:
Java Agents 5 also include a new property, JWT Cookie Name (
org.forgerock.openam.agents.config.jwt.name), that specifies the name of the cookie that holds the JWT on the user's browser. By default, this property is set to the value of
am-auth-jwt. For more information, see Profile Properties in the User Guide.
New Container Versions Supported
Java Agents 5 now support the following container versions:
Apache Tomcat 8.5
JBoss Enterprise Application Platform 7
Wildfly 9 and 10.1
The list of supported operating systems has also been updated. For more information on supported containers, see Section 2.1, "Platform Requirements".
Support for JDK 8
Java Agents 5 now support the following JDKs:
Oracle Java 8
IBM Java 8 (WebSphere only)
For more information about supported JDK versions, see Section 2.3, "Java Requirements".
Because Java agents are the first point of contact between users and your business applications, they can collect inbound requests' cookie and header information which an AM server-side authorization script can then process.
For example, you may decide that only incoming requests containing the
InternalNetworkcookie can access the intranet outside working hours.
Java agents introduce two properties related to continuous security:
Continuous Security Cookies (
Continuous Security Headers (
For more information about these properties, see Continuous Security Properties in the User Guide.
New Active Session Cache Timeout Property
Java Agents 5 include a new property,
org.forgerock.openam.agents.config.active.session.cache.ttl.minutes, to specify the time interval in minutes after which an active session in the Java agent's cache expires.
For more information about this property, see Policy Client Service Properties in the User Guide.
1.3. Major Improvements
Improvements to Not-Enforced Rules
Not-Enforced rules now support:
Creating compound rules, specifying not-enforced URI and IP patterns in the same rule
Using netmask or IP range notation when configuring the Not-Enforced Client IP List property
Using regular expressions in not-enforced URI and IP rules
Filtering for HTTP methods in not-enforced URI and IP rules
Improved POST Data Preservation
The POST data preservation feature of the Java agents has improved security. The agent now:
Generates a random unique identifier as the dummy endpoint from which the client recovers the POST data. This identifier is then placed into an encrypted cookie and provided to the client, which protects it from being snooped.
Links the client session and the POST data using a one-time code. During authentication, the client is provided with a cookie containing the one-time code required to access the endpoint and recover the POST data. If the client cannot provide the code (because the cookie is missing) or the code differs from the one stored with the POST data, the Java agent denies access to the endpoint.
Therefore, if a malicious user gets hold of the endpoint string, the agent will deny access to the endpoint to that user unless they can provide the one-time code.
Introduces two new configuration properties to manage the cache and mitigate against DoS attacks: PDP Maximum Number of Cache Entries and PDP Maximum Cache Size.
Improved Notification System
To receive notifications from AM, earlier versions of the Java agent required the administrator to configure bi-directional communication through load balancers, firewalls, and proxy servers. Java Agents 5 simplify the configuration by using the WebSocket protocol to keep long-running connections open with AM.
Listeners defined in the Agent Notification URL property (
com.sun.identity.client.notification.url) are only relevant to the old notification system and can be removed.
Java agents also include a new property, Web Socket Connection Interval, to configure the time interval after which the agent reopens its WebSocket connection to the AM site. This property ensures that WebSocket connections from agents are spread across the AM site.
Improved Audit Logging
Local and remote audit messages now adhere to the log structure common across the ForgeRock Identity Platform and support propagation of the transaction ID across the platform.
For more information, see Section 4.2, "Configuring Audit Logging" in the User Guide.
Improvements in Cross-Domain Single Sign-On
Cross-domain single sign-on (CDSSO) includes the following improvements:
CDSSO now provides single sign-on (SSO) for AM and Java agents configured in the same DNS domain and across DNS domains.
CDSSO is the default and only SSO mode for Java agents, which simplifies the configuration.
AM now provides CDSSO using the OAuth 2.0 protocol and the
oauth2/authorizeendpoint. The former method of providing SSO,
CDCServlet, is no longer used.
Due to these changes, the following properties are no longer used:
CDSSO Servlet URL (
Cross Domain SSO (
CDSSO Trusted ID Provider (
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 126.96.36.199 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 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 email@example.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 require the
agentapp.warapplication to be deployed alongside the agent. In previous versions, deploying the application was optional.
Changes to Alternative Agent Port, Hostname, and Protocol Properties
Configuring an alternative agent port, hostname, or protocol now requires adding an entry in the Agent Root URL for CDSSO property. Failure to do so may result in redirection loops or
Agent Directories Renamed
The following agent directories have been renamed:
Changes to Login, Logout, and Conditional Login Properties
Earlier versions of the Java agent could configure a number of properties to customize the login and logout URLs that the agent uses when redirecting users. Moreover, you could configure conditional login rules to redirect incoming requests from specific domains to specific AM instances.
These properties have changed in Java Agents 5 as follows:
Earlier versions of the Java agent authenticated users using the UI or XUI URL (which could also contain a mention of the
CDCServletin CDSSO flows). Therefore, login properties configured the URL to authenticate the user to a specific realm and a specific user data store. For example:
Logout properties could be configured similarly.
Java Agents 5 authenticate to and log out users from the
oauth2/authorizeendpoint, which is not configurable. Therefore:
To specify the realm or authentication module to which users should authenticate to, or log out from, add a conditional redirection rule. For example:
The following login and logout properties have been removed from Java Agents 5:
OpenAM Login URL,
This property has been reinstated in Java Agents 5.0.1.
Login URL Prioritized,
Login URL Probe,
Login URL Probe Timeout,
OpenAM Logout URL,
Logout URL Prioritized,
Logout URL Probe,
Logout URL Probe Timeout,
Conditional login and logout properties have changed:
OpenAM Conditional Logout URL,
OpenAM Conditional Login URL,
Earlier versions of the Java agent allowed configuring conditional login and logout redirection to several AM instances specified in the same list to balance login and logout operation across instances.
Java Agents 5 allow one redirection URL per rule. Configure the URL of an AM site or, alternatively, a load balancer to balance connections.
Java Agents 5 let you configure conditional login and conditional logout redirection against any service or website in your environment.
Java Agents 5 conditional login and conditional logout properties let you specify domains, subdomains, and paths as the incoming request URL in each rule.
Changes to the Java Agent's Startup Sequence
The following change has been made to the Java agent's startup sequence:
Earlier versions of the Java agent used the bootstrap property
com.iplanet.am.naming.urlto specify the URL of the AM instance(s) the agent connects to. This property could be used to balance agent connections between AM servers in a site.
Java Agents 5 assembles AM's URL from properties, as follows:
The properties used to build AM's URL are configured during agent installation. To balance agent connections to an AM site, specify the load balancer's FQDN when you are prompted for the OpenAM server URL during installation. For example:
... ----------------------------------------------- SUMMARY OF YOUR RESPONSES ----------------------------------------------- JBoss home directory : /path/to/jboss/ JBoss deployment mode: standalone Install agent as global module: true OpenAM server URL : http://openam.loadbalancer.com:8080/openam Agent URL : http://www.example.com:8080/agentapp Agent Profile name : JBossAgent Agent Profile Password file name : /tmp/pwd.txt ...
com.iplanet.am.naming.urlproperty is no longer used.
Java agents now start up when AM is not available, denying all requests to protected and not-enforced resources until AM is available.
3.2. Deprecated Functionality
There is no deprecated functionality in this release.
3.3. Removed Functionality
Removed Support for the Identity Membership Environment Condition in Policies
Java Agents 5 does not support policies configured with the Identity Membership(
AMIdentityMembership) environment condition. Instead, configure the equivalent User & Group (
Identity) subject condition. For more information, see the ForgeRock Access Management Authorization Guide.
Removed Support for Several Container Versions
Java Agents 5 does not support the following container versions:
Apache Tomcat 6
Jboss Application Server 7
IBM WebSphere Application Server 8
Oracle WebLogic Server 11g
For more information on supported containers, see Section 2.1, "Platform Requirements".
Removed Support for Several Operating System Versions
Java Agents 5 do not support the following operating system versions:
RedHat Enterprise Linux 5
Oracle Linux 5
Ubuntu 12.04 LTS
Windows Server 2008
Removed Support for JDK 7 and Earlier
Java Agents 5 require JDK 8. For more information on supported JDK version, see Section 2.3, "Java Requirements".
Removed Support for Configuring the Agent's Encryption Provider
Java Agents 5 remove support for configuring the agent's encryption provider class, which now defaults to
org.forgerock.openam.shared.security.crypto.AESWrapEncryption. Therefore, the Encryption Provider (
com.iplanet.security.encryptor) property is no longer supported.
Removed Support for the Java Authentication and Authorization Service (JAAS)
Defining role-based access control of web resources using Java declarative security is not supported. Therefore:
com.sun.identity.agents.config.filter.modeproperty no longer supports the
The following configuration properties are no longer supported:
Default Privileged Attribute (
Privileged Attribute Type (
Privileged Attributes To Lower Case (
Privileged Session Attribute (
Enable Privileged Attribute Mapping (
Privileged Attribute Mapping (
WebAuthentication Available (
--migrateearly-access option has been removed from the agentadmin command.
To upgrade Java agents, see Chapter 5, "Upgrading Java Agents" in the User Guide.
Java Agents 5 remove support for the following configuration properties:
Agent Notification URL (
CDSSO Clock Skew (
CDSSO Servlet URL (
CDSSO Trusted ID Provider (
Client Polling Period (
Cross Domain SSO (
Default Privileged Attribute (
Encryption Provider (
Login URL Prioritized (
Login URL Probe (
Login URL Probe Timeout (
Logout URL Prioritized (
Logout URL Probe (
Logout URL Probe Timeout (
OpenAM Conditional Login URL,
com.sun.identity.agents.config.conditional.login.url, replaced by
OpenAM Conditional Logout URL
com.sun.identity.agents.config.conditional.logout.url, replaced by
OpenAM Login URL (
OpenAM Logout URL (
Policy Client Clock Skew (
Privileged Attribute Mapping (
Privileged Attribute Type (
Privileged Session Attribute (
Remote Log File Name (
SSO Cache Enabled (
Web Service Authenticator (
Web Service Authorization Error Content File (
Web Service Enable (
Web Service End Points (
Web Service Internal Error Content File (
Web Service Process GET Enable (
Web Service Response Processor (
WebAuthentication Available (
This is a comprehensive list of all the properties removed, some of which are mentioned in other places of these release notes.
The properties are still available when creating a new agent profile in AM 5.5 to provide backwards-compatibility with earlier versions of the Java agent.
Chapter 4. Fixes, Limitations, and Known Issues
4.1. Key Fixes
AMAGENTS-1805: Log level is not hotswappable on java agents 5.0
AMAGENTS-1626: JASPA: Realm parameter set for login url should also be passed into the goto URL
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-1482: Secure Web Sockets does not work on WildFly
The following important issues were fixed in this release:
AMAGENTS-1247: The installer manipulates (i.e. damages) the host-manager web.xml file during install
AMAGENTS-1146: Java agent is confused about secure cookie properties
AMAGENTS-821: Jetty_v7 j2ee agent is not compatible with jetty 9+
AMAGENTS-791: Tomcat installer allows install into Tomcats which don't support websockets
AMAGENTS-783: Some valid special characters set as HTTP_HEADERs are not being encoded
AMAGENTS-409: Cookie reset is failing on Java Agents
AMAGENTS-374: JEE Agent 3.5.1 Install fails with WildFly 10.x and EAP 7
AMAGENTS-364: agents.config.policy.evaluation.realm does not handle realm aliases
AMAGENTS-170: Java agent installer to ignore Tomcat version
AMAGENTS-104: J2EE agent installer uses an old endpoint /identity/authenticate which breaks with OpenAM 13
AMAGENTS-83: When using a site logout page, OpenAM cookies do not get cleared when trying to logout
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 > J2EE > Agent Name > SSO.
Remove all cookie domains from the CDSSO Domain List (
Navigate to Realms > Realm Name > Applications > Agents > J2EE > 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 Apache Tomcat
Apache Tomcat 8.0.x introduced a new cookie processor,
org.apache.tomcat.util.http.Rfc6265CookieProcessor, that became the default cookie processor on Apache 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.
Apache 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 Apache Tomcat server. Refer to the documentation for your version of Apache 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 became available:
Chapter 5. Documentation Updates
The following table tracks changes to the documentation set following the release of Java Agents 5:
|2018-08-03||Release of Java Agents 188.8.131.52 patch release.|
|2018-05-02||Maintenance release of Java Agents 5.0.1|
Patch release of Java Agents 184.108.40.206
Initial release of Java Agents 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.