PingGateway release notes

Incompatible changes

Incompatible changes are changes affecting existing functionality and migration from a previous release. Before you upgrade, make appropriate changes to your scripts and plugins.

2026.3

  • The PingGateway-2026.3.0.zip now unpacks to a directory named ping-gateway-version instead of identity-gateway-version.

    For example, this release unpacks to /path/to/ping-gateway-2026.3.0.

  • The directories used in the PingGateway Dockerfile have also been renamed:

    Description Old location New location Environment variable

    PingGateway binaries

    /opt/ig

    /opt/gateway

    INSTALL_DIR

    PingGateway configuration

    /var/ig

    /var/gateway

    IG_INSTANCE_DIR
    You should use the environment variables in your Dockerfiles instead of the directory paths.

  • The default session cookie name for administrative connections has changed.

    The default name for administrative session cookies is now IG_ADMIN_SESSIONID. The default name for all other connections remains IG_SESSIONID.

    By default, PingGateway no longer shares the session manager between administrative and non-administrative connections. If you have a session manager configured with the "session" property only in admin.json, also configure a session manager with the "session" property in config.json. Use different cookie names for each session manager.

  • If any components defined in config.json or admin.json fail to load, PingGateway now fails to start and logs an appropriate startup error.

    Previously, if a component failed to load, PingGateway would start successfully but would respond to subsequent requests with a 500 Internal Server Error.

    When the failOnRouteError router setting is set to true, any invalid routes loaded by that router prevents the router component from starting. If there are nested routers and they’re all configured with failOnRouteError, the failure cascades up and prevents PingGateway from starting.

  • The stop.sh and stop.bat scripts now let the PingGateway process terminate gracefully by default.

    Each script now takes at most two optional arguments:

    1. The PingGateway instance directory

    2. A time limit specifying how long to wait before forcing the process to terminate

    Learn more in Forcible shutdown.

  • When rotating audit files, PingGateway continues to add a timestamp as the rotation filename suffix by default.

    Previously, the timestamps reflected local time. The timestamps now reflect Coordinated Universal Time (UTC) instead. This can cause an offset of several hours in the timestamps depending on your time zone. Newly rotated audit files can temporarily have timestamps earlier than existing files.

  • The JSON log message format for the base PingGateway Docker image has changed.

    For example, log messages now show:

    • Timestamps in milliseconds and a separate "nanoseconds" field.

    • Stack traces as JSON objects rather than strings.

    Adapt your log processing to accommodate these changes.

  • When configuring the openDuration property in the CircuitBreakerFilter, the maximum permitted duration is now 1 day.

    Previously, there wasn’t a maximum duration.

2025.11

No new incompatible changes.

2025.9

No new incompatible changes.

2025.6

No new incompatible changes.

2025.3

New default port and paths for administrative endpoints

When you don’t explicitly define admin.json settings, PingGateway now listens for HTTP administrative requests on port 8085 and omits the deprecated /openig path prefix from the paths to administrative endpoints.

Examples in the documentation reflect these new default settings.

You can change the port and related settings by configuring an adminConnector in admin.json.

Prometheus Scrape Endpoint changes

  • The /metrics/prometheus endpoint is no longer served by default. If possible, use /metrics/prometheus/0.0.4 instead.

    The admin.json serveDeprecatedPrometheusEndpoint setting now defaults to false. Set it to true and restart PingGateway if you must use the old endpoint.

  • The metric ig_jvm_free_used_memory_bytes has been renamed ig_jvm_free_memory_bytes.

PingGateway now validates ID token signatures by default

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

OAuth2ResourceServerFilter no longer sets a realm by default

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

useDeprecatedIssuerRepository is now false by default

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

2024.11

No new incompatible changes.

2024.9

Zero-valued Prometheus metrics

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

This could affect existing dashboards and reports.

2024.6

Router now checks for directory

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

ClientRegistration configurations

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:

  • "skipSignatureVerification": must be false to enable ID token signature validation

  • "clientSecretUsage": must be ID_TOKEN_VALIDATION_AND_CLIENT_AUTHENTICATION or ID_TOKEN_VALIDATION_ONLY

  • "clientSecretId": must identify the client secret

  • "secretsProvider": must provide for the client secret for signature validation

Learn more in ClientRegistration.

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

Issuer configurations

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

  • "issuer": must match the iss claim value in the ID token (required unless it’s obtained from the provider’s well-known configuration URL)

  • "idTokenVerificationSecretId": (optional) identifies the provider’s public key for signature validation

  • "secretsProvider": (optional) provides the public key for signature validation

  • "idTokenSkewAllowance": (optional) permits clock skew during signature validation

Learn more in Issuer.

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

2024.3

IG .war file

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.

secretsProvider property changes from optional to required

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

Scripts

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.

Java 17

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

Vert.x

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.

Handling of failed HTTP responses

IG now fails an HTTP response promise when:

  • Streaming is disabled by the streamingEnabled property of admin.json. This is the default setting.

  • The response provides response headers but not the entire response body.

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

JWT must be signed or encrypted

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

Improved security for CrossDomainSingleSignOnFilter

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.

IG .zip file

To prevent confusion during upgrade, PingGateway-2026.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-2026.3.0.zip unpacked to /path/to/identity-gateway.

Treatment of HTTP 500 errors

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.

Inline objects can’t be referenced from the configuration

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.

2023.11

Change to host header capitalization for HTTP/2

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.

Safeguard against accidental exposure of private keys with JwkSetHandler

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.

2023.9

No new incompatible changes.

2023.6

Improved security for scripts

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.

2023.4

No new incompatible changes.

2023.2

The IG .war file is no longer delivered.

7.2

ScriptableResourceUriProvider accepts returned values only as a String

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 EOL

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 Ping Identity End of Life (EOL) Software Tracker.

keyType for CapturedUserPasswordFilter is required

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

JWT classes relocated to new packages

Classes related to JWT-based 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.

CDSSO requires session cookies with SameSite=None, Secure=True

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: