Incompatible changes

By default, PingGateway now listens for HTTP administrative requests on port 8085 and omits the deprecated /openig path prefix from the paths to administrative endpoints.

You can change the default behavior by using the admin.json adminConnector setting.

Examples in the documentation reflect the new default settings.

The ClientRegistration skipSignatureVerification setting now defaults to true meaning PingGateway now validates OpenID Connect ID token signatures by default.

The OAuth2ResourceServerFilter optional realm setting no longer sets an HTTP authentication realm by default.

The useDeprecatedIssuerRepository settings for the AuthorizationCodeOAuth2ClientFilter and Issuer configurations are now false by default.

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 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:

Learn more in 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:

Learn more in 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. Learn about migration in Migrate from web container mode to standalone mode.

Because the default secret service has been removed, you must configure a secretsProvider for the following:

Groovy scripts used in the IG configuration must now use the UTF-8 character set. In previous releases, Groovy files referenced in 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 setting of an 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-2025.3.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-2025.3.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.

A new exposePrivateSecrets property 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.

Learn more in the documentation about 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>. Learn more in the documentation for 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. Learn more in 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 org.forgerock.openig.jwt package to the org.forgerock.openig.session.jwt package.

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

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: