Incompatible changes

Following a performance improvement, the Prometheus output shows many new WebSocket proxy metrics with 0.0 values.

This could affect existing dashboards and reports.

The Router handler now checks the directory you specify in its configuration is an existing directory PingGateway can read. If not, PingGateway throws an exception.

To enable OpenID Connect ID token signature validation and the provider uses HMAC-based signatures, ClientRegistration configurations now require settings to access the client secret used for signature validation:

For details, refer to ClientRegistration.

The Issuer for AuthorizationCodeOAuth2ClientFilter now uses asymmetric signature validation by default.

When you enable OpenID Connect ID token signature validation, update these properties of your Issuer configurations:

For details, refer to Issuer.

The Issuer for AuthorizationCodeOAuth2ClientFilter now uses asymmetric signature validation by default.

The IG .war file is no longer created. It was deprecated in IG 6 and stopped being delivered in IG 2023.2. For information about migration, refer to Migrate from web container mode to standalone mode.

Because the default secret service has been removed, configuration of secretsProvider has changed from optional to required for the following properties:

Groovy scripts used in the IG configuration must now use the UTF-8 character set. In previous releases, Groovy files referenced from the IG configuration could rely on default encoding or system properties.

IG no longer supports Java 11. You must upgrade to Java 17.

Upgrade to Vert.x 4.5 renames and removes Vert.x options used by WebSocket connections to AM and accessed through the vertx attribute of AmService.

Learn more about Vert.x changes in 4.5.0 Deprecations and breaking changes.

Use the Vert.x options described in VertxOptions.

IG now fails an HTTP response promise when:

In previous releases, IG completed the response promise but the response was unreadable.

The following filters must now be configured with a SecretsProvider and signature or encryption:

When verificationSecretId in CrossDomainSingleSignOnFilter is configured, IG uses it to verify the signature of AM session tokens. When verificationSecretId isn’t configured, IG discovers and uses the AM JWK set to verify the signature of AM session tokens.

From this release, if verificationSecretId isn’t configured and IG can’t use the AM JWK set, the CrossDomainSingleSignOnFilter fails to start.

In previous releases, the CrossDomainSingleSignOnFilter accepted unsigned tokens.

To prevent confusion during upgrade, PingGateway-2024.11.0.zip now unpacks to a directory containing the IG version number. For example, this release unpacks to /path/to/identity-gateway-2024.3.0.

In previous releases, PingGateway-2024.11.0.zip unpacked to /path/to/identity-gateway.

HTTP 500 errors are no longer computed in Handlers or Filters. Instead, they fail the response promise with the Runtime exception that caused the failure.

In previous releases, other objects in a configuration could refer to an inline object through its name property. Inline objects can no longer be referenced by other objects; only named heap objects can be referenced by other objects.

For HTTP/2, PingGateway pseudo-headers and host response headers are now lowercase.

This isn’t a breaking change. RFC 2616, 4.2 Message Headers explains, "Field names are case-insensitive."

Some applications expect case-sensitive header names, such as Host, however. Update these applications to accept case-insensitive headers.

The new property exposePrivateSecrets is available in JwkSetHandler to safeguard against the accidental exposure of private keys in a JWK set.

The property is false by default to prevent exposure of private keys. To expose private keys, you must now explicitly set the property to true.

To improve security, IG now runs scripts only from an absolute path, or from a path relative to the base script directory. Routes that refer to scripts otherwise, such as through a URL, fail to deploy.

For more information, refer to the file property of scripts.

ScriptableResourceUriProvider accepts returned values only as a String. In previous releases, it accepted returned values as a String or Promise<String>. For more information, see ScriptableResourceUriProvider in PolicyEnforcementFilter.

AM 5.x.x has reached product end of life and is no longer supported. The default value of the AmService property version has changed to 6. For more information, refer to Product Support Lifecycle Policy | PingGateway and Agents.

For better security, the keyType for CapturedUserPasswordFilter is now required, and the use of DES is deprecated.

Classes related to JWT stateless sessions have moved from the package org.forgerock.openig.jwt to org.forgerock.openig.session.jwt.

Classes and functions used to validate a JWT, used with a JwtValidatorCustomizer in a JwtValidationFilter, have moved from the package org.forgerock.openig.tools.jwt to org.forgerock.openig.tools.jwt.validation.

The IG scripting engine has been updated to incorporate the changes automatically.

To improve privacy, browsers have recently changed third-party cookie policies to require the following settings for session cookies: SameSite=None, Secure=True.

Depending on your deployment and route configuration, configure session cookies as follows: