What’s new

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.

PingGateway now supports AM policy decision AuthenticateToTreeConditionAdvice responses.

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.

For details, refer to FileSystemSecretStore.

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

For details, refer to 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.

For details, refer to 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.

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

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 from 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 remain 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 from Metrics at the Prometheus Scrape Endpoint.

Startup and Websocket metrics are now available at the Prometheus Scrape Endpoint. Learn more from 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 from 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 from Cache metrics at the Prometheus Scrape Endpoint.

IG now uses secrets instead of deprecated passwords. Learn about 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 about 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 from 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.

GrantSwapJwtAssertionOAuth2ClientFilter is a new filter to transform requests for OAuth 2.0 access tokens into secure JWT bearer grant type requests.

Use this filter with PingOne Advanced Identity Cloud or AM to increase the security of less-secure grant-type requests such as Client credentials grant or Resource owner password credentials grant.

For more information, refer to Secure the OAuth 2.0 access token endpoint.

The new property includeKeyId is available in JwtBuilderFilter to include the ID of the signature key in the header of a built JWT.

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:

JwkPropertyFormat is a new secret format. Use it with FileSystemSecretStore to decode JSON Web Key (JWK) formatted keys into secrets.

The new property certificateVerificationSecretId is available in SecretsTrustManager to facilitate the use of CA-certificates in mutual TLS. In previous releases, the use of CA-signed certificates was more restricted.

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.

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 context 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 did not 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, if 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 might block your next request containing split JWT session cookies. Consider increasing the value of connectors:maxTotalHeadersSize.

For more information, refer to Stateless sessions.

To improve security, JWT session cookies are no longer compressed by default. For more information, refer to the useCompression property of JwtSession.

Startup can now be allowed 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:

For more information, refer to Allow startup when there is an existing PID file in the Installation guide and ig.pid.file.mode in the Deployment guide.

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

When the marker is present in the request query parameters, the request is not redirected for authentication.

The new property mappings:aliasesMatching 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, the entity property of a StaticResponseHandler can now be defined as an array of strings or as a string.

The new property connectors:maxTotalHeadersSize in AdminHttpApplication defines the maximum size in bytes of 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 property useLegacyAdviceEncoding 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 are automatically authenticated to PingOne Advanced Identity Cloud and AM by a non-configurable authentication module. Authentication chains and modules are deprecated in PingOne Advanced Identity Cloud and AM. They are replaced by 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 in a future release.

For more information, refer to Authenticate an IG agent to PingOne Advanced Identity Cloud and Authenticate an IG agent to AM.

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

From this release, when the request includes the x-authenticate-response header with the value header, IG 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.

For information about how the header is used in policy enforcement, refer to Deny requests with advices in a header.

The x-authenticate-response header name can be configured by the new property authenticateResponseRequestHeader in PolicyEnforcementFilter.

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, such as the 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. For more information, refer to the notifications.renewalDelay property of AmService.

ClientHandler and ReverseProxyHandler have a new property waitQueueSize 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. In this release, by default it is limited to the square of the value of the connections property.

The name and ID of a route is now included by default in access audit events. For more information about auditing, refer to Auditing your deployment.

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.

For more information, refer to DataPreservationFilter and POST data preservation.

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 that was 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 are not 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 after all other IG heaplets are destroyed. This change allows the other IG heaplets to use HttpClientHandlerHeaplets during shut down. 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 property autoRefresh is available in FileSystemSecretStore and KeyStoreSecretStore to configure automatic reloaded of the secret store when a file in the filesystem is edited or deleted, or a keystore is edited or deleted.

IG now uses Groovy 4 for scripting. For more information, refer to Release notes for Groovy 4.0

The expression binding now gives the time since epoch at the instant the expression is evaluated. For more information, refer to Dynamic bindings.