Release notes
|
These release notes cover multiple versions of Java Agent software. They are designed to make it easier to upgrade, especially when you are skipping releases. Ping Identity supports and maintains versions according to the Ping Identity Product Support Lifecycle Policy | PingGateway and Agents. Some older Java Agent versions have reached End of Life (EOL). Release notes for EOL versions are available in the documentation sets for those versions. If you are still running an EOL version, upgrade as soon as possible to an actively maintained version. |
Name changes for ForgeRock products
Product names changed when ForgeRock became part of Ping Identity.
The following name changes have been in effect since early 2024:
| Old name | New name |
|---|---|
ForgeRock Identity Cloud |
PingOne Advanced Identity Cloud |
ForgeRock Access Management |
PingAM |
ForgeRock Directory Services |
PingDS |
ForgeRock Identity Management |
PingIDM |
ForgeRock Identity Gateway |
PingGateway |
Learn more about the name changes in New names for ForgeRock products in the Knowledge Base.
Requirements
Ping Identity 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.
Supported clients
Java Agent supports the latest stable versions of web browsers that support JavaScript 5 and later.
AM requirements
-
Java Agent supports AM 7.2 and later versions.
-
Java Agent requires the WebSocket protocol to communicate with AM. Both the Java container and the network infrastructure must support the WebSocket protocol.
Read your network infrastructure and Java container documentation for more information about WebSocket support.
Java platform requirements
Java Agent runs in a Java container and requires a Java Development Kit. For the best security, use the most recent supported Java update.
Java platform requirements Java Agent 2025.3
| Vendor | Version | Comment |
|---|---|---|
Oracle Java |
11(1) |
|
17 |
|
|
OpenJDK |
11(1) |
|
17 |
|
(1) Support to be discontinued in a future release.
Java platform requirements Java Agent 2024.11.x
| Vendor | Version | Comment |
|---|---|---|
Oracle Java |
11(1) |
|
17 |
|
|
OpenJDK |
11(1) |
|
17 |
|
(1) Support to be discontinued in a future release.
Jakarta platform requirements
Jakarta platform requirements Java Agent 2025.3
Java Agent supports Jakarta EE 9+.
| Operating systems (OS) | OS versions | Web application containers & minimum supported versions |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(1) Support to be discontinued in a future release.
Jakarta platform requirements Java Agent 2024.11.x
Java Agent supports Jakarta EE 9+.
| Operating systems (OS) | OS versions | Web application containers & minimum supported versions |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(1) Support to be discontinued in a future release.
Jakarta platform requirements Java Agent 2023.11.x
Java Agent supports Jakarta EE 9+.
| Operating systems (OS) | OS versions | Web application containers & minimum supported versions |
|---|---|---|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
(1) Support to be discontinued in a future release.
(2) Doesn’t support JDK 17.
Jakarta platform requirements Java Agent 5.10
Java Agent supports Jakarta EE 9+, with JDK 11.
| Operating systems (OS) | OS versions | Web application containers & minimum supported versions |
|---|---|---|
|
|
|
|
|
|
|
|
|
(1) Support to be discontinued in a future release.
Java EE platform requirements
Java EE platform requirements Java Agent 2025.3
| Operating systems (OS) | OS versions | Web application containers & minimum supported versions |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(1) Support to be discontinued in a future release.
(2) Version 14.1.1 doesn’t support JDK 17 but 14.1.2 does.
Java EE platform requirements Java Agent 2024.11.x
| Operating systems (OS) | OS versions | Web application containers & minimum supported versions |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(1) Support to be discontinued in a future release.
(2) Doesn’t support JDK 17.
Java EE platform requirements Java Agent 2023.11.x
| Operating systems (OS) | OS versions | Web application containers & minimum supported versions |
|---|---|---|
|
|
|
|
||
|
|
|
|
|
|
|
|
|
(1) Support to be discontinued in a future release.
(2) Doesn’t support JDK 17.
Java EE platform requirements Java Agent 5.10
| Operating systems (OS) | OS versions | Web application containers & minimum supported versions |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
(1) Doesn’t support JDK 11.
(2) Support to be discontinued in a future release.
What’s new
Java Agent 2025.3
Java Agent 2025.3 is a major release that introduces new features, functional enhancements, and fixes.
FIPS 140-3 support
We’ve made changes to Java Agent to support Bouncy Castle FIPS 2.x, which is a FIPS 140-3 compliant security provider.
Learn more in Integrate with the Bouncy Castle FIPS provider.
Java Agent 2024.11
Java Agent 2024.11 is a minor release that introduces new features, functional enhancements, and fixes.
URL handling
We’ve made changes to the Java Agent to improve the security of handling incoming request URLs.
|
These changes may affect the agent’s behavior in your environment. You should review these settings and make sure they are suitable for your requirements. In particular, consider that not-enforced rules and AM policies are evaluated against normalized paths with the path parameters removed. |
By default, the agent will now reject an incoming request URL with an HTTP 400 in the following scenarios:
-
One or more of the following characters exist in the URL path or path parameters:
-
%2E(encoded period character) -
%2F(encoded forward slash) -
%3B(encoded semicolon) -
%5C(encoded backslash) -
\(unencoded backslash)
-
-
The incoming URL path contains encoded control characters. These are characters in the range
%00to%1Finclusive, and%7F. -
The incoming URL path contains invalid encodings, such as
%G1. -
The incoming URL path doesn’t conform with the rules in the Jakarta Servlet Specification Request URI Path Processing section.
Encoded characters are case-insensitive. For example, %2E and %2e are handled in the same way.
|
Learn more in Path traversal attempts.
Corresponding new properties are available to control this behavior if you need to make any changes:
Additionally, a new Control
Handling of Path Traversal Attempts property lets you reject incoming URLs that contain .., or
combinations of . and %2E as a path segment.
By default, this property is set to false and the agent doesn’t reject URLs with these path segments.
JWT signature validation
A new Enable internal checking of JWT signature property controls how the JWT signature is validated. By default, the property is set to false, which doesn’t change JWT signature validation.
Set this property to true to validate the JWT signature internally.
The agent caches the AM public keys used for JWT signing when the JWT signature is validated internally. Configure this cache using the following new properties:
| When the JWT signature is validated internally, there is an expected performance impact. |
List properties
We’ve made changes to let you update list properties in bulk rather than individually.
You do this by specifying @ in the index location and entering the value as comma-separated values.
For example, property[@]=one,two,three is the equivalent of setting the following properties individually:
property[]=one
property[]=two
property[]=threeLearn more in List properties.
Java Agent 2024.9
Java Agent 2024.9 is a minor release that introduces new features, functional enhancements, and fixes.
URL validation and path normalization
Raw URL path invalidation regex list is a new property that lets you define regular expressions to match invalid or undesired characters or strings during URL validation.
Incoming URLs are evaluated against this property before path normalization and rejected with an HTTP 400 if a match is found.
Additionally, %5C is no longer converted to / during path normalization. If required, %5C can be added to the new property as an invalid string.
Temporary files
A new temporary files directory (/tmp) has been created in /path/to/java_agents/agent_type/Agent_n.
This /tmp directory is used by Prometheus monitoring for any temporary files.
Additionally, the /pdp directory used by default for POST data preservation (PDP) data when POST data is saved to files has moved to this /tmp directory. You can change the default directory using the existing POST Data Preservation File Directory property.
Changes to Prometheus metrics
Metrics output from the Prometheus endpoint now uses the Prometheus 0.0.4 format. As a result, some metric names have been updated:
-
Metric names ending
_totalnow end_sum. -
ja_jvm_thread_statemetrics ending_countnow end_result. -
Other metric names ending
_countno longer include the_countsuffix. -
The
agent-exceptiondecision for deniedja_requestmetrics has been replaced bybad-requestandunexpected-exceptiondecisions depending on the reason. -
The following WebSocket metric names have been updated to include a
_totalsuffix:-
ja_websocket_config_change_processed -
ja_websocket_config_change_received -
ja_websocket_policy_change_processed -
ja_websocket_policy_change_received -
ja_websocket_session_logout_processed -
ja_websocket_session_logout_received
-
The sort order has also changed, and metrics are now ordered by sum and then count. Previously, they were ordered by count and then sum.
Learn more in Monitor services.
Java Agent 2024.6
Java Agent 2024.6 is a minor release that introduces new features, functional enhancements, and fixes.
Commons Audit Framework
To improve security, the audit handling code is deprecated and replaced by the Commons Audit Framework. Sensitive information, such as cookies and some headers, is no longer audited by default.
New properties are available to define the audit log directory and include or exclude elements from audit logs. Learn more from Deprecated and Incompatible changes.
Offline agent password encryption
A new option, --raw-encrypt, is available in
agentadmin
to encrypt the agent password before agent installation.
Java Agent 2024.3
Java Agent 2024.3 is a major release that introduces new features, functional enhancements, and fixes.
Hardened security
With PingOne Advanced Identity Cloud and from AM 7.5, the agent profile password can optionally be managed through the identity provider’s secret service. If the identity provider finds a matching secret in a secret store, it uses that secret instead of the hard-coded agent password.
Learn more from Create agent profiles in AM and Create an agent profile in PingOne Advanced Identity Cloud.
Jetty Java Agent 12
Installation of Java Agent with Jetty 12 is supported.
For installation on Jetty 12, you can use Javax EE8, Jakarta EE9, or Jakarta EE10. However, Java Agent can protect applications in only one EE environment at a time.
Java Agent on Jetty 12 runs on Java 17.
Learn more from Install Jetty Java Agent.
Java Agent 2023.11.x
Java Agent 2023.11.2
Java Agent 2023.11.2 is a maintenance release that introduces security enhancements and fixes.
URL handling
We’ve made changes to the Java Agent to improve the security of handling incoming request URLs.
|
These changes may affect the agent’s behavior in your environment. You should review these settings and make sure they are suitable for your requirements. In particular, consider that not-enforced rules and AM policies are evaluated against normalized paths with the path parameters removed. |
By default, the agent will now reject an incoming request URL with an HTTP 400 in the following scenarios:
-
One or more of the following characters exist in the URL path or path parameters:
-
%2E(encoded period character) -
%2F(encoded forward slash) -
%3B(encoded semicolon) -
%5C(encoded backslash) -
\(unencoded backslash)
-
-
The incoming URL path contains encoded control characters. These are characters in the range
%00to%1Finclusive, and%7F. -
The incoming URL path contains invalid encodings, such as
%G1. -
The incoming URL path doesn’t conform with the rules in the Jakarta Servlet Specification Request URI Path Processing section.
Encoded characters are case-insensitive. For example, %2E and %2e are handled in the same way.
|
Learn more in Path traversal attempts.
Corresponding new properties are available to control this behavior if you need to make any changes:
Additionally, a new Control
Handling of Path Traversal Attempts property lets you reject incoming URLs that contain .., or
combinations of . and %2E as a path segment.
By default, this property is set to false and the agent doesn’t reject URLs with these path segments.
URL validation and path normalization
Raw URL path invalidation regex list is a new property that lets you define regular expressions to match invalid or undesired characters or strings during URL validation.
Incoming URLs are evaluated against this property before path normalization and rejected with an HTTP 400 if a match is found.
Additionally, %5C is no longer converted to / during path normalization. If required, %5C can be added to the new property as an invalid string.
Changes to Prometheus metrics
Metrics output from the Prometheus endpoint now uses the Prometheus 0.0.4 format. As a result, some metric names have been updated:
-
Metric names ending
_totalnow end_sum. -
ja_jvm_thread_statemetrics ending_countnow end_result. -
Other metric names ending
_countno longer include the_countsuffix. -
The
agent-exceptiondecision for deniedja_requestmetrics has been replaced bybad-requestandunexpected-exceptiondecisions depending on the reason. -
The following WebSocket metric names have been updated to include a
_totalsuffix:-
ja_websocket_config_change_processed -
ja_websocket_config_change_received -
ja_websocket_policy_change_processed -
ja_websocket_policy_change_received -
ja_websocket_session_logout_processed -
ja_websocket_session_logout_received
-
The sort order has also changed, and metrics are now ordered by sum and then count. Previously, they were ordered by count and then sum.
Learn more in Monitor services.
Java Agent 2023.11
Java Agent 2023.11 is a minor release that introduces new features, functional enhancements, and fixes.
Improved error reporting for authentication failures
The agent uses pre-authentication cookies to track authentication requests to AM. During authentication, if the pre-authentication cookie has expired or doesn’t contain a required one-time code, the agent now logs a message to describe the failure.
Improved management of infinite authentication loops
When a user has insufficient credentials to access a requested resource, AM can return policy advice requiring the user to authenticate at a higher level.
If there is an error in the AM configuration, an infinite authentication loop can occur, where the user is repeatedly asked to authenticate.
The following new properties are available to manage infinite authentication loops:
Deployment with Docker
A Dockerfile is now provided to deploy Tomcat Java Agent to extend and protect an application. For more information, refer to Deploy Java Agent with Docker.
Integration with Bouncy Castle FIPS provider
Use of the FIPS Java API module from the Legion of the Bouncy Castle Inc is now supported. For more information, refer to Integrate with Bouncy Castle FIPS provider.
Java Agent 2023.9
Java Agent 2023.9 is a minor release that introduces new features, functional enhancements, and fixes.
Continued improvement to drop-in software update
Procedures for drop-in software update are simplified and testing is now automated. For information about changes to drop-in software update, refer to Incompatible changes.
Java Agent 2023.6
Java Agent 2023.6 is a minor release that introduces new features, functional enhancements, and fixes.
Authentication of Java Agent to PingOne Advanced Identity Cloud and AM
Java Agent agents are automatically authenticated to PingOne Advanced Identity Cloud and AM by a non-configurable authentication module. Authentication chains and modules are deprecated and replaced by nodes, trees, and journeys.
You can now authenticate Java Agent to PingOne Advanced Identity Cloud and AM 7.3 with a journey. The procedure is currently optional, but will be required when authentication chains and modules are removed in a future release.
For more information, refer to Authenticate agents to PingOne Advanced Identity Cloud and Authenticate agents to AM.
Override alternate host, port, and protocol in constructed URLs
Retain previous override behavior is a new property to force use of the following properties when constructing URLs for not-enforced rule evaluation, or policy evaluation:
-
Alternative Agent Host Name -
Alternative Agent Port Number -
Alternative Agent Protocol
For backward compatibility, the property is true by default; the override
properties are not used to construct URLs.
Java Agent 2023.3
Java Agent 2023.3 is a major release that introduces new features, functional enhancements, and fixes.
Conditional redirect of unauthenticated requests based on request query parameters
Query parameters can now be used in the property OAuth Login URL List
to create rules that evaluate request URLs for login redirect.
Previously, the rules were based only on the request domain, path, and header.
Invalidation of sessions on logout
Always invalidate sessions is a new property to invoke the AM REST logout endpoint.
If Conditional Logout URL List
is set to a URL that does not perform a REST logout to AM, set
Always invalidate sessions to true so the agent additionally invokes the AM REST logout endpoint to invalidate the session.
DENY keyword for not-enforced rules
The new DENY keyword immediately denies access to matching resources.
Access is always denied.
A not-enforced rule with the DENY keyword is not inverted by the NOT keyword
or by the following properties Invert Not-Enforced IPs or Invert Not-Enforced URIs.
For information, refer to Deny access.
Java Agent 5.10.x
Java Agent 5.10.4
Java Agent 5.10.4 is a maintenance release that introduces security enhancements.
URL handling
We’ve made changes to the Java Agent to improve the security of handling incoming request URLs.
|
These changes may affect the agent’s behavior in your environment. You should review these settings and make sure they are suitable for your requirements. In particular, consider that not-enforced rules and AM policies are evaluated against normalized paths with the path parameters removed. |
By default, the agent will now reject an incoming request URL with an HTTP 400 in the following scenarios:
-
One or more of the following characters exist in the URL path or path parameters:
-
%2E(encoded period character) -
%2F(encoded forward slash) -
%3B(encoded semicolon) -
%5C(encoded backslash) -
\(unencoded backslash)
-
-
The incoming URL path contains encoded control characters. These are characters in the range
%00to%1Finclusive, and%7F. -
The incoming URL path contains invalid encodings, such as
%G1. -
The incoming URL path doesn’t conform with the rules in the Jakarta Servlet Specification Request URI Path Processing section.
Encoded characters are case-insensitive. For example, %2E and %2e are handled in the same way.
|
Learn more in Path traversal attempts.
Corresponding new properties are available to control this behavior if you need to make any changes:
Additionally, a new Control
Handling of Path Traversal Attempts property lets you reject incoming URLs that contain .., or
combinations of . and %2E as a path segment.
By default, this property is set to false and the agent doesn’t reject URLs with these path segments.
Java Agent 5.10.1
Invalidation of sessions on logout
Always invalidate sessions is a new property to invoke the AM REST logout endpoint.
If
Conditional Logout URL List
is set to a URL that does not perform a REST logout to AM, set
Always invalidate sessions
to true so that the agent additionally invokes the AM REST logout endpoint to
invalidate the session.
Java Agent 5.10
Support for Jakarta EE standard
Java Agent now supports the Jakarta EE 9+ standard, with JDK 11. For information about supported operating systems Jakarta, refer to Jakarta EE platform requirements.
Matching FQDNs to URL patterns
A file globbing pattern (containing * and ?) can now be used to match a
hostname, in
FQDN Map. Use this feature
to map requests with virtual, invalid, or partial hostnames to URLs that contain
a correct FQDN.
Detect the path of a resource loaded by classloader
To help with troubleshooting, a new property
-Ddisplay.classpath.mode.enabled=true is available to help locate .jar files
that contain outdated classes. For more information and an example, refer to
Detect the path of a resource loaded by classloader.
Logback
Log messages in Java Agent and third-party dependencies are now recorded using the Logback implementation of the Simple Logging Facade for Java (SLF4J) API. For more information, refer to Logging.
POST data can be preserved in files
The following new properties are available to configure the storage of POST data to files instead of to the in-memory cache:
For more information, refer to POST data preservation.
Encoding for extended characters in not-enforced rules
By default, Java Agent uses UTF-8 to encode extended characters in the resource paths of not-enforced rules.
The following new properties are available to change the character encoding in the resource paths and HTTP query parameters of not-enforced rules:
For more information, refer to Not-enforced rules.
Limitation on the size to which a JWT can be decompressed
Maximum Decompression Size is a new property to limit the maximum size to which a compressed JWT can be decompressed. This property reduces the risk of memory exhaustion DOS attacks by reducing the risk of a decompressed JWT consuming too much available memory.
Signing of pre-authentication cookies
To improve protection against tampering, pre-authentication and POST data preservation cookies can now be signed. When the value of Pre-Authn and Post Data Preservation Cookie Signing Value is a non-zero length, its value is used to generate a signing key.
During installation, the path to a file that contains the signing value can be provided interactively or in the installation response file. Cookies are not signed if:
-
The path is not provided
-
The path to an empty file is provided
-
The value found in the file is too short
The signing value is stored in the AgentKey.properties file.
Retrieval of agent password
A new option is available in agentadmin to reveal the agent profile password.
Fixes
|
Fixes in are cumulative chronologically, by release date. An issue fixed in a maintenance release, such as Java Agent 2023.11.1, isn’t included in a major release, such as Java Agent 2024.3, if the major release was issued before the minor release. |
Fixes in Java Agent 2025.3
-
AMAGENTS-7034: Uninstalling Weblogic agent doesn’t work
-
AMAGENTS-6809: Monitoring endpoint doesn’t work for Jakarta builds
Fixes in Java Agent 2024.11
-
AMAGENTS-6860: The count for the number of allowed by policy requests also counts the redirection to authentication callback
Fixes in Java Agent 2024.9
-
AMAGENTS-6612: Java Agent in accept SSO token mode with custom login false writes JWT tokens to iPlanetDirectoryPro
Fixes in Java Agent 2024.6
-
AMAGENTS-6588: agentadmin writes a log file every time it is started
-
AMAGENTS-6258: Enforce agent’s Logback configuration isolation
Fixes in Java Agent 2024.3
-
AMAGENTS-6131: Tomcat Agent uninstall fails when done a second time
-
AMAGENTS-6119: Menu for uninstall options has number 11 at start rather than 1
-
AMAGENTS-6118: Install help has error in the output
Fixes in Java Agent 2023.11.x
Fixes in Java Agent 2023.9
-
AMAGENTS-5999: Cannot initialize logback when invoking classes in the agent SDK
-
AMAGENTS-5928: Remove META-INF/services/javax.servlet.ServletContainerInitializer from the distribution
-
AMAGENTS-5798: Oracle WebLogic admin console fails after patch upgrade
-
AMAGENTS-3798: The AM Conditional Login URL should check that the entry has a | in it
Fixes in Java Agent 2023.6
-
AMAGENTS-5797: java.lang.NullPointerException in org.forgerock.agents.util.UrlParamNormaliser
-
AMAGENTS-5685: JPA: Address bug in cache thawing
-
AMAGENTS-5654: JPA conditional login does not work in case when specific header should match any value
-
AMAGENTS-5600: JPA: Enabling pathinfo and using URL encoding raises exception
-
AMAGENTS-5236: JPA does not respect port/protocol overrides for Not Enforced Rules and Policy Evaluation
Fixes in Java Agent 2023.3
-
AMAGENTS-5550: Changing the log level at runtime stops logging altogether
-
AMAGENTS-5497: Avoid use of the "Agent Tree" for JPA login
-
AMAGENTS-5089: agentadmin --encrypt Agent_Id <password-file> throws error
-
AMAGENTS-4816: Do not invoke rest logout for some special cases
-
AMAGENTS-3912: Avoid displaying a huge stacktrace to the user when the bootstrap properties file cannot be opened
Fixes in Java Agent 5.10.x
Java Agent 5.10.2
-
AMAGENTS-5550: Changing the log level at runtime stops logging altogether
-
AMAGENTS-5497: Avoid use of the "Agent Tree" for JPA login
Removed
Removed is defined in Release levels and interface stability.
| Removed in | Decription | Replaced by | Deprecated in |
|---|---|---|---|
2025.3 |
- |
- |
- |
2024.11 |
- |
- |
- |
2024.9 |
- |
||
2024.6 |
- |
- |
- |
2024.3 |
5.9 |
||
- |
5.6 |
||
- |
5.6 |
||
5.6 |
|||
- |
5.6 |
||
- |
5.6 |
||
- |
5.6 |
||
- |
5.6 |
||
Logback, as described in Logging |
- |
||
- |
|||
- |
|||
- |
|||
- |
|||
- |
|||
|
Licence is never displayed during installation. |
- |
|
2023.11.2 |
- |
||
2023.9 |
- |
- |
- |
2023.6 |
- |
- |
- |
2023.3 |
JDK 8 support |
Support for Java 11 |
- |
WebSphere Java Agent |
WebSphere Java Agent does not support JDK 11, which is the minimum JDK version supported in this release. Consequently, WebSphere Java Agent is not supported in this release. To use WebSphere Java Agent, you are required to use Java Agent 5.10 or earlier versions. |
- |
|
|
Reset cookie domain map, to map specified cookies to a domain. |
- |
|
5.10 |
- |
- |
- |
Incompatible changes
Incompatible changes refer to changes that impact existing functionality and may affect your migration from a previous release. Before you upgrade, review these lists and make the appropriate changes to your scripts and plugins.
Changes in Java Agent 2024.11
URL handling
To improve security, we’ve made changes to how the agent handles incoming URLs. These changes may affect the agent’s behavior because not-enforced rules and AM policies are evaluated against normalized paths with the path parameters removed.
Learn more about these changes in URL handling.
Changes in Java Agent 2024.9
Monitoring
The common REST monitoring endpoint has been removed. Use the Prometheus endpoint for monitoring your deployment.
Changes in Java Agent 2024.6
Commons Audit Framework
To improve security, the audit handling code is deprecated and replaced by the Commons Audit Framework.
To prevent logging of sensitive data for an audit event, the Commons Audit Framework uses a safelist to specify which audit event fields appear in the logs.
By default, only safelisted audit event fields are included in the logs. To include and exclude elements from JSON audit events, use Audit Log Include Paths and Audit Log Exclude Paths.
Changes in Java Agent 2023.11
There are no incompatible changes in this release or the Java Agent 2023.11.1 maintenance release.
Java Agent 2023.11.2
URL handling
To improve security, we’ve made changes to how the agent handles incoming URLs. These changes may affect the agent’s behavior because not-enforced rules and AM policies are evaluated against normalized paths with the path parameters removed.
Learn more about these changes in URL handling.
Monitoring
The common REST monitoring endpoint has been removed. Use the Prometheus endpoint for monitoring your deployment.
Changes in Java Agent 2023.9
Tomcat Java Agent software update
The agent.jar isn’t required for drop-in software update to
Java Agent 2023.9. If the file is present in the container, delete it as
described in Tomcat Java Agent software update.
JBoss and WildFly Java Agent software update
You must now provide the full path to
jee-agents-sdk-version.jar
in the module.xml file for drop-in software update to Java Agent 2023.9.
The following libraries are no longer required:
-
agent.jar -
jee-agents-jboss-common-version.jar -
tyrus-standalone-client-version.jar
For more information, refer to JBoss and WildFly Java Agent software update.
Changes in Java Agent 2023.3
JDK 11 with WebLogic 12c Java Agent and WebSphere Java Agent
WebLogic 12c Java Agent and WebSphere Java Agent do not support JDK 11, which is the minimum JDK version supported in this release. Consequently, these platforms are not supported in this release. Use Java Agent 5.10 or an earlier version for these platforms.
Changes in Java Agent 5.10
There are no incompatible changes in the Java Agent 5.10.1, 5.10.2 or 5.10.3 maintenance releases.
Java Agent 5.10.4
URL handling
To improve security, we’ve made changes to how the agent handles incoming URLs. These changes may affect the agent’s behavior because not-enforced rules and AM policies are evaluated against normalized paths with the path parameters removed.
Learn more about these changes in URL handling.
Java Agent 5.10
Logback
Log messages in Java Agent and third-party dependencies are now recorded using the Logback implementation of the Simple Logging Facade for Java (SLF4J) API.
From this release, TRACE is the highest log level. In previous releases,
ON was the highest log level.
From this release, when the log level is ON, TRACE level logs are written to
file. In previous releases, TRACE level logs were written to the standard output.
Deprecated
Deprecated is defined in Release levels and interface stability.
| Deprecated in | Description | Replaced by | Removed in |
|---|---|---|---|
2025.3 |
- |
- |
- |
2024.11 |
- |
- |
- |
2024.9 |
- |
- |
- |
2024.6 |
Local audit handling with Local Audit Log Filename |
Commons Audit Framework, using: Sensitive information, such as cookies and some headers, is no longer audited by default. Learn more from Incompatible changes. |
Not yet removed |
2024.3 |
AM 6.5 support |
Later versions of AM |
Not yet removed |
Java 11 support |
Java 17 support |
Not yet removed |
|
- |
Not yet removed |
||
2023.11 |
- |
- |
- |
2023.9 |
- |
- |
- |
2023.6 |
- |
- |
- |
2023.3 |
- |
- |
- |
5.10 |
- |
- |
- |
Known issues
Java Agent 2025.3
| Issue | Comment |
|---|---|
AMAGENTS-6838: JPA will create a JWT cookie in SSO Token Acceptance mode |
Unresolved |
AMAGENTS-6615: agentadmin option "--getEncryptKey" does not work on Windows |
Unresolved |
AMAGENTS-6603: JPA: Change all file access to use UTF-8, in JPA itself, and in the installer |
Unresolved |
Java Agent 2024.11
| Issue | Comment |
|---|---|
AMAGENTS-6838: JPA will create a JWT cookie in SSO Token Acceptance mode |
Unresolved |
AMAGENTS-6809: Monitoring endpoint doesn’t work for Jakarta builds |
Fixed in 2025.3 |
AMAGENTS-6615: agentadmin option "--getEncryptKey" does not work on Windows |
Unresolved |
AMAGENTS-6603: JPA: Change all file access to use UTF-8, in JPA itself, and in the installer |
Unresolved |
Java Agent 2024.9
| Issue | Comment |
|---|---|
AMAGENTS-6838: JPA will create a JWT cookie in SSO Token Acceptance mode |
Unresolved |
AMAGENTS-6809: Monitoring endpoint doesn’t work for Jakarta builds |
Fixed in 2025.3 |
AMAGENTS-6615: agentadmin option "--getEncryptKey" does not work on Windows |
Unresolved |
AMAGENTS-6603: JPA: Change all file access to use UTF-8, in JPA itself, and in the installer |
Unresolved |
Java Agent 2024.6
| Issue | Comment |
|---|---|
AMAGENTS-6615: agentadmin option "--getEncryptKey" does not work on Windows |
Unresolved |
AMAGENTS-6612: Java Agent in accept SSO token mode with custom login false writes JWT tokens to iPlanetDirectoryPro |
Fixed in 2024.9 |
AMAGENTS-6603: JPA: Change all file access to use UTF-8, in JPA itself, and in the installer |
Unresolved |
Java Agent 2024.3
| Issue | Comment |
|---|---|
AMAGENTS-6258: Enforce Agent’s Logback configuration isolation |
Fixed in 2024.6, 2023.11.1 |
AMAGENTS-6078: JPA does not remove the pre-authn cookie in all circumstances |
Won’t fix |
Java Agent 2023.11
| Issue | Comment |
|---|---|
AMAGENTS-6258: Enforce Agent’s Logback configuration isolation |
Fixed in 2024.6, 2023.11.1 |
AMAGENTS-6131: Tomcat Agent uninstall fails when done a second time |
Fixed in 2024.3, 2023.11.1 |
AMAGENTS-6119: Menu for uninstall options has number 11 at start rather than 1 |
Fixed in 2024.3 |
AMAGENTS-6118: Install help has error in the output |
Fixed in 2024.3 |
AMAGENTS-6078: JPA does not remove the pre-authn cookie in all circumstances |
Won’t fix |
Java Agent 2023.9
| Issue | Comment |
|---|---|
AMAGENTS-6131: Tomcat Agent uninstall fails when done a second time |
Fixed in 2024.3, 2023.11.1 |
AMAGENTS-6119: Menu for uninstall options has number 11 at start rather than 1 |
Fixed in 2024.3 |
AMAGENTS-6118: Install help has error in the output |
Fixed in 2024.3 |
AMAGENTS-6078: JPA does not remove the pre-authn cookie in all circumstances |
Won’t fix |
Java Agent 2023.6
| Issue | Comment |
|---|---|
AMAGENTS-5999: Cannot initialize logback when invoking classes in the agent SDK |
Fixed in 2023.9 |
AMAGENTS-5928: Remove META-INF/services/javax.servlet.ServletContainerInitializer from the distribution |
Fixed in 2023.9 |
AMAGENTS-5798: Oracle WebLogic admin console fails after patch upgrade |
Fixed in 2023.9 |
AMAGENTS-4984:Setting samesite cookie to lax will cause the agent auth flow to fail if we are using different sites - |
Duplicates AMAGENTS-5996 |
AMAGENTS-3798: The AM Conditional Login URL should check that the entry has a | in it |
Fixed in 2023.9 |
Java Agent 2023.3
| Issue | Comment |
|---|---|
AMAGENTS-5999: Cannot initialize logback when invoking classes in the agent SDK |
Fixed in 2023.9 |
AMAGENTS-5928: Remove META-INF/services/javax.servlet.ServletContainerInitializer from the distribution |
Fixed in 2023.9 |
AMAGENTS-5798: Oracle WebLogic admin console fails after patch upgrade |
Fixed in 2023.9 |
AMAGENTS-5797: java.lang.NullPointerException in org.forgerock.agents.util.UrlParamNormaliser |
Fixed in 2023.6 |
AMAGENTS-5685: JPA: Address bug in cache thawing |
Fixed in 2023.6 |
AMAGENTS-5654: Conditional login does not work in case when specific header should match any value |
Fixed in 2023.6 |
AMAGENTS-5631: Encrypt-in-place does not overwrite existing password |
Fixed in 2023.6 |
AMAGENTS-5602: Pathinfo stripping is only done for not-enforced rules |
Won’t fix |
AMAGENTS-5601: NotEnforcedRuleHelper instantiates a metrics object, but never uses it. |
Not a defect |
AMAGENTS-5600: Enabling pathinfo and using URL encoding raises exception |
Fixed in 2023.6 |
AMAGENTS-4984: Setting samesite cookie to lax will cause the agent auth flow to fail if we are using different sites |
Duplicates AMAGENTS-5996 |
AMAGENTS-3798: The AM Conditional Login URL should check that the entry has a | in it |
Fixed in 2023.9 |
Java Agent 5.10
| Issue | Comment |
|---|---|
AMAGENTS-5999: Can’t initialize logback when invoking classes in the agent SDK |
Fixed in 2023.9 |
AMAGENTS-5928: Remove META-INF/services/javax.servlet.ServletContainerInitializer from the distribution |
Fixed in 2023.9 |
AMAGENTS-5590: JPA version is not set in config files |
Fixed in 5.10.3 |
AMAGENTS-5798: Oracle WebLogic admin console fails after patch upgrade |
Fixed in 2023.9 |
AMAGENTS-4984: Setting samesite cookie to lax will cause the agent auth flow to fail if we are using different sites |
Duplicates AMAGENTS-5996 |
AMAGENTS-4816: The agent does not invalidate session before redirecting to logout |
Fixed in 2023.3, 5.10.1 |
AMAGENTS-3798: The AM Conditional Login URL should check that the entry has a | in it |
Fixed in 2023.9 |
AMAGENTS-3912: Avoid displaying a huge stacktrace to the user when the bootstrap properties file cannot be opened |
Fixed in 2023.3 |
Limitations
The following limitations are inherent to the design, not bugs to be fixed.
Java Agent on Jetty 12
For installation on Jetty 12, you can use Javax EE8, Jakarta EE9, or Jakarta EE10. However, Java Agent can protect applications in only one EE environment at a time.
Java Agent on Jetty 12 runs on Java 17.
Learn more from Eclipse Jetty: Operations Guide.
CDSSO domain list restrictions
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 JWT Cookie Domain List with more than one cookie domain may result in redirection loops.
To work around this issue, perform the following steps:
-
Go to Realms > Realm Name > Applications > Agents > Java > Agent Name > SSO.
-
Remove all cookie domains from the
JWT Cookie Domain List. -
Go to Realms > Realm Name > Applications > Agents > Java > Agent Name > Global.
-
Configure any required entries in the Agent Root URL for CDSSO. The agent sets the cookie domain based on the requested resource.
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 JWT Cookie Domain List can result in the following issues:
-
Java Agent 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) ...bash
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
JWT Cookie Domain Liststart with a number or a letter. For example:Valid configuration
org.forgerock.agents.jwt.cookie.domain.list[0]=example.com org.forgerock.agents.jwt.cookie.domain.list[1]=123company.comnoneInvalid configuration
org.forgerock.agents.jwt.cookie.domain.list[0]=.example.com org.forgerock.agents.jwt.cookie.domain.list[1]=.mycompany.comnone
The agentadmin command shows warning messages
The agentadmin command may show warning messages similar to the following:
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 releaseYou can safely ignore these messages.
Appendix A: Release levels and interface stability
You can find information about release levels in the Ping Identity Product Support Lifecycle Policy | PingGateway and Agents.
Product stability labels
Ping Identity Platform software supports many features, protocols, APIs, GUIs, and command-line interfaces. Some of these are standard and very stable. Others offer new functionality that is continuing to evolve.
Ping Identity acknowledges you invest in these features and interfaces and so need to understand when they are expected to change. For that reason, we define stability labels and use these definitions in Ping Identity Platform products.
| Stability Label | Definition |
|---|---|
Stable |
This documented feature or interface is expected to undergo backwards-compatible changes only for major releases. Changes may be announced at least one minor release before they take effect. |
Evolving |
This documented feature or interface is continuing to evolve and so is expected to change, potentially in backwards-incompatible ways even in a minor release. Changes are documented at the time of product release. While new protocols and APIs are still in the process of standardization, they are Evolving. This applies, for example, to recent Internet-Draft implementations and to newly developed functionality. |
Legacy |
This feature or interface has been replaced with an improved version, and is no longer receiving development effort from Ping Identity. You should migrate to the newer version, however the existing functionality will remain. Legacy features or interfaces will be marked as Deprecated if they are scheduled to be removed from the product. |
Deprecated |
This feature or interface is deprecated, and likely to be removed in a future release. For previously stable features or interfaces, the change was likely announced in a previous release. Deprecated features or interfaces will be removed from Ping Identity products. |
Removed |
This feature or interface was deprecated in a previous release, and has now been removed from the product. |
Technology Preview |
Technology previews provide access to new features that are considered as new technology that is not yet supported. Technology preview features may be functionally incomplete, and the function as implemented is subject to change without notice. DO NOT DEPLOY A TECHNOLOGY PREVIEW INTO A PRODUCTION ENVIRONMENT. Customers are encouraged to test drive the technology preview features in a non-production environment, and are welcome to make comments and suggestions about the features in the associated forums. Ping Identity does not guarantee that a technology preview feature will be present in future releases, the final complete version of the feature is liable to change between preview and the final version. Once a technology preview moves into the completed version, said feature will become part of Ping Identity Platform. Technology previews are provided on an “AS-IS” basis for evaluation purposes only, and Ping Identity accepts no liability or obligations for the use thereof. |
Internal/Undocumented |
Internal and undocumented features or interfaces can change without notice. If you depend on one of these features or interfaces, contact support to discuss your needs. |
Getting support
Ping Identity provides support services, professional services, training, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.pingidentity.com.
Ping Identity has staff members around the globe who support our international customers and partners. For details on Ping Identity’s support offering, visit https://www.pingidentity.com/support.
Ping Identity publishes comprehensive documentation online:
-
The Ping Identity Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage Ping Identity Platform software.
While many articles are visible to everyone, Ping Identity customers have access to much more, including advanced information for customers using Ping Identity Platform software in a mission-critical capacity.
-
Ping Identity 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.
Security advisories
Ping Identity issues security advisories in collaboration with our customers to address any security vulnerabilities transparently and rapidly.
Ping Identity’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.
You can find security advisories in the Knowledge Base.
Release timeline
| Release date | Java Agent version | Release type(1) |
|---|---|---|
March 2025 |
2025.3 |
Major |
January 2025 |
5.10.4 |
Maintenance |
December 2024 |
2023.11.2 |
Maintenance |
November 2024 |
2024.11 |
Minor |
September 2024 |
2024.9 |
Minor |
July 2024 |
2023.11.1 |
Maintenance |
June 2024 |
2024.6 |
Minor |
April 2024 |
5.10.3 |
Maintenance |
March 2024 |
2024.3 |
Major |
November 2023 |
2023.11 |
Minor |
September 2023 |
2023.9 |
Minor |
June 2023 |
2023.6 |
Minor |
March 2023 |
2023.3 |
Major |
February 2023 |
5.10.2 |
Maintenance |
December 2022 |
5.10.1 |
Maintenance |
June 2022 |
5.10 |
Minor |
January 2022 |
5.9.1 |
Maintenance |
September 2021 |
5.9 |
Minor |
February 2021 |
5.8 |
Minor |
August 2020 |
5.7 |
Minor |
April 2019 |
5.6 |
Minor |
October 2018 |
5.5 |
Minor |
December 2017 |
5 |
Major |
February 2015 |
3.5 |
Minor |
November 2013 |
3.3 |
Minor |
February 2013 |
3.1-Xpress |
Minor |
February 2010 |
3 |
Major |
(1) You can find details about the scope of expected changes for different release types in Ping Identity Product Support Lifecycle Policy | PingGateway and Agents.