PingGateway now describes how to use Bouncy Castle FIPS to help with FIPS 140–3 compliance without requiring an HSM using a PKCS#11 interface.

Learn more in FIPS 140–3 compliance.

ClientTlsOptions and ServerTlsOptions now support an optional offloadHandshake setting (default: false).

When processing a TLS handshake with revocation checks enabled, the handshake process can take an extended amount of time, blocking the event thread from processing other requests. When this option is true, PingGateway processes the TLS handshake in a separate worker thread. The event thread continues to process other requests.

PingGateway now supports options to help close connections more gracefully.

Use the new "connectionTimeToLive" and "connectionShutdownGracePeriod" settings for connections to servers and from client applications.

The KerberosIdentityAssertionPlugin now supports customzing the HTTP 401 Unauthorized responses with an optional unauthorizedResponseHandler.

When a browser can’t supply a Kerberos token and isn’t configured to deal appropriately with HTTP 401 Unauthorized, the default response can leave the user stuck on an unauthorized page. Use the unauthorizedResponseHandler provide an appropriate response to resolve this issue.

OpenTelemetry support is no longer a technology preview. It is now a supported feature.

The feature has Evolving interface stability. It is subject to change without notice, even in a minor or maintenance release.

PingGateway now supports gathering device profile data from the user-agent and including the profile data in PingOne Protect risk evaluation requests.

Learn more in PingOne Protect integration.

The AuthorizationCodeOAuth2ClientFilter and ClientRegistration configurations now support RFC 7636: Proof Key for Code Exchange by OAuth Public Clients (PKCE).

PKCE is enabled by default and recommended. To disable it, set "pkce_method": "none" or "pkceMethod": "none" as described in the reference documentation.

The stop.sh and stop.bat scripts now accept additional arguments to change how long the script waits before forcing the PingGateway process to terminate.

Learn more in Graceful shutdown.

The CrossDomainSingleSignOnFilter now has a "lifetime" setting to configure the duration after which PingGateway removes the initial CDSSO authentication session state.

PingGateway now supports a ClientHandler and ReverseProxyHandler "propagateDisconnection" setting to reset the connection to the protected application when the user-agent disconnects and PingGateway is in streaming mode.

PingGateway now supports a derCertificate(string) function to convert a base64-encoded DER-format string into a certificate.

A new "idleTimeoutUpdate": "INCREASE_ONLY_THEN_ALWAYS" setting for AmSessionIdleTimeoutFilters lets you enforce the longest timeout of either the idle timeout from the current filter or the tracking token, and then set the tracking token timeout to the idle timeout of the filter.

PingGateway uses the updated tracking token on the next interaction with an AmSessionIdleTimeoutFilter. The next AmSessionIdleTimeoutFilter filter can use a different "idleTimeoutUpdate" setting, for example, to enforce a shorter idle timeout.

This release adds the ability to push traces to an OpenTelemetry service.

Learn more in the following documentation:

With the new FileSystemSecretStore versionSuffix setting you can have multiple versions of a secret with the same ID.

Learn more in FileSystemSecretStore.

Use the new HeaderFilter replace setting to replace headers instead of removing then adding them.

Learn more in HeaderFilter.

The new runtimeExceptionCondition setting lets you restrict which runtime exceptions lead to retries.

Learn more in ClientHandler and ReverseProxyHandler.

The new securityProvider setting lets you choose the Java security provider to use when loading a keystore.

Learn more in KeyStoreSecretStore.

The new delayRouteMetrics setting lets you defer creation of route metrics until a request passes through the route. This can improve startup times for deployments with many routes.

Learn more in Router.

PingGateway now lets you configure a separate endpoint for administrative connections. PingGateway is expected to require a separate administrative endpoint in a future release.

Learn more in AdminHttpApplication (admin.json).

The documentation now includes an example showing how to protect a web application with help from PingOne Authorize.

Learn more in PingOne Authorize integration.

When you omit the deprecated target setting from a FileAttributesFilter or an SqlAttributesFilter, PingGateway reads the file or performs the SQL query asynchronously when calling the filter. Place the filter immediately before the entity reading the data from the context.

Product names changed when ForgeRock became part of Ping Identity. PingGateway was formerly known as ForgeRock Identity Gateway. Learn more about the name changes in New names for ForgeRock products.

You can now use PingOne Protect risk evaluations to help protect web applications. Configure PingGateway routes to react dynamically to risk scores from PingOne Protect.

Learn more in PingOne Protect integration.

To facilitate consumption of Prometheus metrics, the format of some metrics has been updated and the new format is available on the new endpoint …​/openig/metrics/prometheus/0.0.4.

The old format and endpoint are deprecated, but for backward compatibility, they are enabled and available by default.

The new property serveDeprecatedPrometheusEndpoint in AdminHttpApplication is available to deliver Prometheus metrics in the deprecated format. It is enabled by default.

Learn more in Metrics at the Prometheus Scrape Endpoint.

Startup and Websocket metrics are now available at the Prometheus Scrape Endpoint. Learn more in Startup metrics at the Prometheus Scrape Endpoint and WebSocket metrics at the Prometheus Scrape Endpoint.

The PingOneApiAccessManagementFilter is now supported for general use.

PingGateway now supports OpenID Connect ID token validation according to the OpenID Connect specifications.

For this release, signature validation is optional. The next major release is expected to make ID token signature validation required.

The following new properties enable validation of the ID token signatures and the iss, aud, exp, iat, and nonce claims:

Learn more about ClientRegistration configurations and Issuer configurations in Incompatible changes.

The following new objects are available for local processing on behalf of PingOne Advanced Identity Cloud as part of an PingOne Advanced Identity Cloud journey:

These objects exist alongside the Technical Preview objects, IdentityAssertionHandlerTechPreview, ScriptableIdentityAssertionPluginTechPreview, and IdentityAssertionPluginTechPreview, introduced in the last release.

Monitoring metrics are now available at the Prometheus Scrape Endpoint and Common REST Monitoring Endpoint for the caches described in Caches.

Learn more in Cache metrics at the Prometheus Scrape Endpoint.

IG now uses secrets instead of deprecated passwords. Learn how IG manages migration in Upgrade from an earlier version of Studio.

IG Studio no longer uses the deprecated Splunk or ElasticSearch audit event handlers. Learn how IG manages migration in Upgrade from an earlier version of Studio.

With PingOne Advanced Identity Cloud and from AM 7.5, passwords hardcoded in the identity provider configuration can optionally be managed by the identity provider’s secret service. These passwords include the IG agent passwords and OAuth 2.0 client passwords.

An IssuerRepository is provided as a default object. Learn more in Default objects.

PingOneApiAccessManagementFilter is a new filter dedicated to PingOne’s API Access Management. Use this filter with API Access Management to evaluate HTTP requests and responses.

The following new properties have been added in AuthorizationCodeOAuth2ClientFilter and Issuer:

In OpenID Connect, use these properties to revoke access and refresh tokens issued by Authorization Servers during login.

The following new properties have been added in AuthorizationCodeOAuth2ClientFilter and Issuer:

In OpenID Connect, use these properties to initiate logout from authorization servers.

A new property prompt is available in AuthorizationCodeOAuth2ClientFilter.

Use the property in OIDC flows to require the authorization server to prompt the end user to reauthenticate and consent.

When an OAuth 2.0 authorization operation fails, the AuthorizationCodeOAuth2ClientFilter injects the error and error description into the OAuth2FailureContext. In previous releases, OAuth2FailureContext was used only for the OAuth2TokenExchangeFilter.

In AuthorizationCodeOAuth2ClientFilter, retrieve the original target URI for a request from the new IdpSelectionLoginContext.

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

In earlier releases, IG didn’t verify the tokens when verificationSecretId in CrossDomainSingleSignOnFilter wasn’t configured.

To minimize the risk of CDSSO token tampering, always configure verificationSecretId in CrossDomainSingleSignOnFilter.

In stateless sessions, when the JWT session cookie exceeds 4 KBytes, IG automatically splits it into multiple cookies.

If your JWT session size is too close to the value of connectors:maxTotalHeadersSize in AdminHttpApplication, IG can block your next request containing split JWT session cookies. Consider increasing the value of connectors:maxTotalHeadersSize.

To improve security, JWT session cookies are no longer compressed by default.

IG can now start up when there is an existing PID file. When activated, IG removes the existing PID file and creates a new one during startup. In previous releases, if there was an existing PID file during startup, the startup failed.

Activate the feature in the following ways:

In CrossDomainSingleSignOnFilter, the new redirectionMarker property is enabled by default to prevent redirect loops when the session cookie isn’t present in the CDSSO flow.

When the marker is present in the request query parameters, the request isn’t redirected for authentication.

The new mappings:aliasesMatching property in KeyStoreSecretStore and HsmSecretStore is available to map all aliases that match a regular expression to a secret ID.

Some KeyStores, such as a global Java TrustStore, can contain hundreds of valid certificates. Use this property to map multiple aliases to a secret ID without listing them all in the mapping.

To improve readability, you can now define the entity property of a StaticResponseHandler as an array of strings or as a string.

The new connectors:maxTotalHeadersSize property in AdminHttpApplication defines the maximum size in bytes for the sum of all headers in a request. This property replaces the deprecated Vert.x properties maxHeaderSize and initialSettings:maxHeaderListSize.

To support SDK in legacy installations, a new useLegacyAdviceEncoding property in the PolicyEnforcementFilter is available to provide unencoded advices. By default, advices are encoded with the encoder used by the AM version.

The use of this property is deprecated and should be used only to support SDK in legacy installations.

websocket:proxyOptions is a new property in ReverseProxyHandler to provide a dedicated WebSocket reverse proxy.

The following properties are now available in AmService to improve control of WebSocket connections to AM:

IG agents automatically authenticate to PingOne Advanced Identity Cloud and AM with a non-configurable authentication module. Authentication chains and modules are deprecated and replaced by nodes, trees, and journeys.

You can now authenticate IG agents 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.

By default, when PingOne Advanced Identity Cloud or AM denies a request with advices, IG returns a redirect response with advices as parameters.

When the request includes the x-authenticate-response header with the value header, IG now returns the response with the advices in a WWW-authentication header.

Use this method for SDKs and single page applications. Placing advices in a header gives these applications more options for handling the advices.

Use the new authenticateResponseRequestHeader property in PolicyEnforcementFilter to configure the x-authenticate-response header name.

The SamlFederationHandler is deprecated and replaced by the SamlFederationFilter.

The SamlFederationFilter can be used in a route protect a downstream application in the same way as other authentication-triggering filters like a SingleSignOnFilter or CrossDomainSingleSignOnFilter.

When triggered, the SamlFederationFilter can initiate the login or logout of a SAML service provider with a SAML identity provider.

IG can now automatically renew WebSocket connections to AM after a defined delay.

ClientHandler and ReverseProxyHandler have a new waitQueueSize property to set the maximum number of outbound requests allowed to queue when no downstream connections are available. Use this property to limit memory use when there is a backlog of outbound requests, for example, when the protected application or third-party service is slow.

In previous releases, the queue size was unlimited. It is now limited to the square of the value of the connections property by default.

The name and ID of a route is now included by default in access audit events.

AM 7.3 can be configured to invalidate sessions based on user ID and send a notification with the topic /agent/session.v2 to IG. IG can now use the notification to evict all sessions bound to the user.

The DataPreservationFilter triggers POST data preservation when an unauthenticated client posts HTML form data to a protected resource.

When the AmService property sessionIdleRefresh is enabled, IG now requests session refresh:

In previous releases, IG requested session refresh only after sessionIdleRefresh.interval elapsed. If IG got an SSO token close to its maximum idle time, the token could expire before sessionIdleRefresh.interval elapsed and IG triggered a refresh.

When relying on a SecretsProvider to retrieve the shared key required by the CapturedUserPasswordFilter, you can now rotate a secret without reloading the filter if the underlying secret store supports secret rotation.

KeyStoreSecretStore can now use KeyStores that aren’t password-protected. In previous releases, KeyStores had to be password-protected.

When IG is cleanly shut down, the destruction of HttpClientHandlerHeaplets is now delayed until all other IG heaplets are destroyed. This change allows the other IG heaplets to use HttpClientHandlerHeaplets during shutdown. For example, AmService can now call logout on any agent tokens it has allocated, which can help to reduce the build up of tokens in AM.

ClientHandlers and ReverseProxyHandlers are examples of HttpClientHandlerHeaplets.

A new autoRefresh property is available in FileSystemSecretStore and KeyStoreSecretStore settings to configure automatic reloaded of the secret store when a file or a keystore is edited or deleted.

IG now uses Groovy 4 for scripting. Learn more in the Release notes for Groovy 4.0

The expression binding now gives the time since epoch at the instant the expression is evaluated.

OAuth2TokenExchangeFilter is a new filter to exchange a client’s access token or ID token for a new token with increased or reduced scopes, while preserving the original token subject.

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: