--- title: Incompatible changes description: Incompatible changes are changes affecting existing functionality and migration from a previous release. Before you upgrade, make appropriate changes to your scripts and plugins. component: pinggateway version: release-notes page_id: pinggateway::changes canonical_url: https://docs.pingidentity.com/pinggateway/release-notes/changes.html revdate: 2026-03-16T18:30:00Z section_ids: 2026_3: 2026.3 2025_11: 2025.11 2025_9: 2025.9 2025_6: 2025.6 2025_3: 2025.3 new_default_port_and_paths_for_administrative_endpoints: New default port and paths for administrative endpoints prometheus_scrape_endpoint_changes: Prometheus Scrape Endpoint changes pinggateway_now_validates_id_token_signatures_by_default: PingGateway now validates ID token signatures by default oauth2resourceserverfilter_no_longer_sets_a_realm_by_default: OAuth2ResourceServerFilter no longer sets a realm by default usedeprecatedissuerrepository_is_now_false_by_default: useDeprecatedIssuerRepository is now false by default 2024_11: 2024.11 2024_9: 2024.9 zero_valued_prometheus_metrics: Zero-valued Prometheus metrics 2024_6: 2024.6 router_now_checks_for_directory: Router now checks for directory clientregistration_configurations: ClientRegistration configurations issuer_configurations: Issuer configurations 2024_3: 2024.3 ig_war_file: IG .war file secretsprovider_property_changes_from_optional_to_required: secretsProvider property changes from optional to required scripts: Scripts java_17: Java 17 vert_x: Vert.x handling_of_failed_http_responses: Handling of failed HTTP responses jwt_must_be_signed_or_encrypted: JWT must be signed or encrypted improved_security_for_crossdomainsinglesignonfilter: Improved security for CrossDomainSingleSignOnFilter ig_zip_file: IG .zip file treatment_of_http_500_errors: Treatment of HTTP 500 errors inline_objects_cant_be_referenced_from_the_configuration: Inline objects can't be referenced from the configuration 2023_11: 2023.11 change_to_host_header_capitalization_for_http2: Change to host header capitalization for HTTP/2 safeguard_against_accidental_exposure_of_private_keys_with_jwksethandler: Safeguard against accidental exposure of private keys with JwkSetHandler 2023_9: 2023.9 2023_6: 2023.6 improved_security_for_scripts: Improved security for scripts 2023_4: 2023.4 2023_2: 2023.2 7_2: 7.2 scriptableresourceuriprovider_accepts_returned_values_only_as_a_string: ScriptableResourceUriProvider accepts returned values only as a String am_5_x_x_eol: AM 5.x.x EOL keytype_for_captureduserpasswordfilter_is_required: keyType for CapturedUserPasswordFilter is required jwt_classes_relocated_to_new_packages: JWT classes relocated to new packages cdsso_requires_session_cookies_with_samesitenone_securetrue: CDSSO requires session cookies with SameSite=None, Secure=True --- # 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](https://docs.pingidentity.com/pinggateway/2026/installation-guide/start-stop.html#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](https://docs.pingidentity.com/pinggateway/2026/reference/AdminHttpApplication.html#AdminHttpApplication-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](https://docs.pingidentity.com/pinggateway/2026/reference/AdminHttpApplication.html#AdminHttpApplication-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](https://docs.pingidentity.com/pinggateway/2026/reference/ClientRegistration.html#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](https://docs.pingidentity.com/pinggateway/2026/reference/OAuth2ResourceServerFilter.html#OAuth2ResourceServerFilter-realm) setting no longer sets an HTTP authentication realm by default. ### useDeprecatedIssuerRepository is now false by default The `useDeprecatedIssuerRepository` settings for the [AuthorizationCodeOAuth2ClientFilter](https://docs.pingidentity.com/pinggateway/2026/reference/AuthorizationCodeOAuth2ClientFilter.html#AuthorizationCodeOAuth2ClientFilter-useDeprecatedIssuerRepository) and [Issuer](https://docs.pingidentity.com/pinggateway/2026/reference/Issuer.html#Issuer-useDeprecatedIssuerRepository) 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](https://docs.pingidentity.com/pinggateway/2026/reference/Handlers.html#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](https://docs.pingidentity.com/pinggateway/2026/reference/MiscellaneousConfigurationObjects.html#ClientRegistration). The Issuer for [AuthorizationCodeOAuth2ClientFilter](https://docs.pingidentity.com/pinggateway/2026/reference/Filters.html#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](https://docs.pingidentity.com/pinggateway/2026/reference/MiscellaneousConfigurationObjects.html#Issuer). The Issuer for [AuthorizationCodeOAuth2ClientFilter](https://docs.pingidentity.com/pinggateway/2026/reference/Filters.html#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](https://docs.pingidentity.com/pinggateway/2024.11/upgrade/upgrade-war-to-zip.html). ### `secretsProvider` property changes from optional to required Because the default secret service has been removed, you must configure a `secretsProvider` for the following: * [AmService](https://docs.pingidentity.com/pinggateway/2026/reference/AmService.html) * [CapturedUserPasswordFilter](https://docs.pingidentity.com/pinggateway/2026/reference/CapturedUserPasswordFilter.html) * [ClientHandler](https://docs.pingidentity.com/pinggateway/2026/reference/ClientHandler.html), `proxy` property * [ClientRegistration](https://docs.pingidentity.com/pinggateway/2026/reference/ClientRegistration.html) * [HsmSecretStore](https://docs.pingidentity.com/pinggateway/2026/reference/HsmSecretStore.html) * [IdentityAssertionHandlerTechPreview](https://docs.pingidentity.com/pinggateway/2024.11/reference/IdentityAssertionHandlerTechPreview.html) * [JdbcDataSource](https://docs.pingidentity.com/pinggateway/2026/reference/JdbcDataSource.html) * [JwkSetHandler](https://docs.pingidentity.com/pinggateway/2026/reference/JwkSetHandler.html) * [JwtBuilderFilter](https://docs.pingidentity.com/pinggateway/2026/reference/JwtBuilderFilter.html) * [JwtSessionFilter](https://docs.pingidentity.com/pinggateway/2026/reference/JwtSessionManager.html) * [KeyManager](https://docs.pingidentity.com/pinggateway/2024.11/reference/KeyManager.html) * [KeyStore](https://docs.pingidentity.com/pinggateway/2024.11/reference/KeyStore.html) * [KeyStoreSecretStore](https://docs.pingidentity.com/pinggateway/2026/reference/KeyStoreSecretStore.html) * [PemPropertyFormat](https://docs.pingidentity.com/pinggateway/2026/reference/PemPropertyFormat.html) * [ResourceOwnerOAuth2ClientFilter](https://docs.pingidentity.com/pinggateway/2026/reference/ResourceOwnerOAuth2ClientFilter.html) * [ReverseProxyHandler](https://docs.pingidentity.com/pinggateway/2026/reference/ReverseProxyHandler.html), `proxy` property * [StatelessAccessTokenResolver](https://docs.pingidentity.com/pinggateway/2026/reference/StatelessAccessTokenResolver.html) ### 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](https://docs.pingidentity.com/pinggateway/2024.11/reference/AmService.html). Learn more about Vert.x changes in [4.5.0 Deprecations and breaking changes](https://github.com/vert-x3/wiki/wiki/4.5.0-Deprecations-and-breaking-changes). Use the Vert.x options described in [VertxOptions](https://vertx.io/docs/4.5.0/apidocs/io/vertx/core/VertxOptions.html). ### Handling of failed HTTP responses IG now fails an HTTP response promise when: * Streaming is disabled by the `streamingEnabled` property of [admin.json](https://docs.pingidentity.com/pinggateway/2026/reference/AdminHttpApplication.html). 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: * [JwtBuilderFilter](https://docs.pingidentity.com/pinggateway/2026/reference/JwtBuilderFilter.html) * [GrantSwapJwtAssertionOAuth2ClientFilter](https://docs.pingidentity.com/pinggateway/2026/reference/GrantSwapJwtAssertionOAuth2ClientFilter.html) ### 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](https://www.rfc-editor.org/rfc/rfc2616#section-4.2) 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](https://docs.pingidentity.com/pinggateway/2023.11/reference/JwkSetHandler.html) 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`. Learn more in the documentation for `ScriptableResourceUriProvider` in [PolicyEnforcementFilter](https://docs.pingidentity.com/pinggateway/7.2/reference/PolicyEnforcementFilter.html). ### 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](https://support.pingidentity.com/s/article/Ping-Identity-EOL-Tracker#pgateway). ### `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: * For in-memory sessions in standalone mode, by[admin.json](https://docs.pingidentity.com/pinggateway/7.2/reference/AdminHttpApplication.html). * For in-memory sessions in web container mode, by the web container: * For Tomcat, learn more in [Configure SameSite for HTTP session cookies in Tomcat](https://docs.pingidentity.com/pinggateway/7.2/installation-guide/install-tomcat.html#tomcat-samesite) and [Configure IG for HTTPS (server-side) in Tomcat](https://docs.pingidentity.com/pinggateway/7.2/installation-guide/install-tomcat.html#tomcat-https). * For Jetty, learn more in [Configure SameSite for HTTP session cookies in Jetty](https://docs.pingidentity.com/pinggateway/7.2/installation-guide/install-jetty.html#jetty-samesite) and [Configure IG for HTTPS (server-side) in Jetty](https://docs.pingidentity.com/pinggateway/7.2/installation-guide/install-jetty.html#jetty-https). * For JBoss, learn more in [Configure SameSite for HTTP session cookies in JBoss](https://docs.pingidentity.com/pinggateway/7.2/installation-guide/install-jboss.html#jboss-samesite) and [Configure IG for HTTPS (server-side) in JBoss](https://docs.pingidentity.com/pinggateway/7.2/installation-guide/install-jboss.html#jboss-https). * For JWT-based sessions in standalone mode and web container mode, by JwtSession.