Incompatible changes

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

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

For details, refer to 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. For information about migration, refer to Migrate from web container mode to standalone mode.

Because the default secret service has been removed, configuration of secretsProvider has changed from optional to required for the following properties:

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

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.

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.

For more information, refer to 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>. For more information, see 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. For more information, refer to 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 package org.forgerock.openig.jwt to org.forgerock.openig.session.jwt.

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

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:

IG has upgraded the version of Logback from 1.2.7 to 1.2.9. For more information, refer to the Logback News for Logback 1.2.8 and Logback 1.2.9.

When IG is in standalone mode, proxying Websocket traffic can produce errors where requested subprotocols not supported. To prevent these error, you must now list the subprotocols that are proxied by IG in the vertx property of admin.json.

In the Prometheus output, information for the default TimerDecorator is always included as name="gateway.timer".

In previous releases, information is included in the Prometheus output as follows:

For more information, see TimerDecorator.

To prevent IG from blocking executing threads, write runtime expressions that consume streamed content with # instead of $. This ensures that IG does a deferred evaluation.

For IG in standalone mode, when the new streamingEnabled property in admin.json is true, expressions that consume streamed content must be written with # instead of $.

For more information, refer to runtime expression.

APIs that read the entity content have been updated to execute scripts asynchronously.

Before AM 7.1, the sub claim of OAuth 2.0 access_tokens and id_tokens contained only the username. From AM 7.1, the username is contained in the subname claim. The sub claim includes additional information.

Update scripts and expressions in IG that use the sub claim.

Secrets from FileSystemSecretStore, HsmSecretStore, KeyStoreSecretStore, and SystemAndEnvSecretStore, now expire after a default of five minutes, or after the time specified in the property leaseExpiry. In the previous release, secrets from these secret stores never expired or had other expiry times.

The Entity.toString() function no longer returns the entity content as a string. Instead, it returns only metadata. This change prevents buffering of the entity content during logging, which, when the entity is big, can impede asynchronous operation.

To return the entity content as a string, replace request.entity.toString() and response.entity.toString() functions with request.entity.string and response.entity.string.

To faciltate asynchronous processing in this release, when the CaptureDecorator property captureEntity is false, the decorator does not capture the message entity, and writes nothing to the logs.

In previous releases, when captureEntity was false, the decorator wrote [entity] in the log to show that there was an entity but that capture was not configured.

For security, RFC 7518 - Digital Signature with RSASSA-PKCS1-v1_5 requires that RSA keys must be 2048 bits or larger. Smaller keys are now rejected.

To prevent redirects to malicious web sites, IG now validates the goto query parameter in requests to OAuth2ClientFilter /login and /logout endpoints.

The goto URL must use the same scheme, host, and port as the original URI, or be a relative URI (just the path). Otherwise, the request fails with an error.

To redirect a request to a site that does not meet the goto URL criteria, change the original URI by using a ForwardedRequestFilter.

For more information, refer to the reference pages for OAuth2ClientFilter and ForwardedRequestFilter.

When entity is used in the StaticResponseHandler, Content-Type is a required header. In previous releases, Content-Type was optional.

IG 7.0 requires Java 11. Java 8 is not supported.

DS is now secure by default. Connections between IG and DS must therefore be configured for TLS.

IG now supports Groovy 3.0. Some Groovy feature may have been deprecated/removed. Refer to the Release notes for Groovy 3.0.

JwtSessionFactory is no longer an alternative type for JwtSession

The default skew allowance in JwtSession has been reduced from 2 minutes to zero. A property to configure the skew allowance has been added in JwtSession.

Oracle recommends the use of PKCS12 keystores. From Java 9, Oracle has provided more support for PKCS12. From Java 11, Oracle has changed the default keystore to PKCS12.

Following this lead, the default type for KeyStore and KeyStoreSecretStore is now based on the keystore extension. If the keystore extension is not recognized, the default type is PKCS12. In previous releases, the default type was the one used by the platform.

To ensure backward-compatibility, where keys are generated using a non-PKCS12 type (for example, JKS), specify type in KeyStore or storeType in KeyStoreSecretStore.

In previous releases, after an access_token resolver validated an access_token, the OAuth2ResourceServerFilter checked that the access_token was not expired. From this release, the OAuth2ResourceServerFilter considers any token returned by an AccessTokenResolver as valid, and checks only that the required scopes are present.

When the ScheduledExecutorService property gracefulStop is true, the service now removes submitted jobs and attempts to end running jobs after respecting the gracePeriod. In previous releases, it did not remove or end jobs.

To prevent logging of sensitive data for an event, the Common Audit Framework now uses an allow-list to specify which event fields appear in logs. Compared to previous releases, different event fields are included by default in the logs.

The AuditService includeIf property has been implemented to include deny-listed event fields in the logs.

In OAuth2ClientFilter, registrations are now identified by the ClientRegistration property clientId instead of name. In this release, IG automatically rewrites OAuth2Session tokens that use name to use clientId. Registration by name is deprecated.

When a user initiates a login with the OAuth2ClientFilter, the login endpoint uses the ClientRegistration property clientId:

In previous releases, the login endpoint used the ClientRegistration property name:

Similarly, the login endpoint in Nascar pages uses client_id instead of name.

To prevent redirects to malicious websites, IG now validates the goto query parameter in requests to OAuth2ClientFilter /login and /logout endpoints.

The goto URL must use the same scheme, host, and port as the original URI, or be a relative URI (just the path). Otherwise, the request fails with an error.

When IG uses AM federation libraries generated from AM 6.5.2 or earlier, add the following lines to the FederationConfig.properties file:

By default, the JwtCookieSession cookie and CrossDomainSingleSignOnFilter authentication cookie and are now flagged as HttpOnly.

CrossDomainSingleSignOnFilter has additional properties to set or unset cookie flags for HttpOnly and secure.

The agent property of AmService is now mandatory. The agent defines the credentials of an AM Java agent that acts on behalf of IG to authenticate with AM, request policy decisions from AM, and communicate WebSocket notifications from AM to IG.

This is a breaking change for all filters that use AmService, and for the following filters where agent replaces properties that are removed in this release:

When a route containing an AmService is reloaded, or when an AmService is stopped, the agent session is logged out.

When the WebSocket notification service is disconnected, by default the session cache and policy enforcement cache is cleared. In previous releases, the caches were not cleared.

DS 6.5 has updated its client API for establishing SSL connections. The SslContextBuilder class has been removed and related usages have been integrated into SslOptions.

This has an impact on existing scripts that are using IG’s LdapClient for connecting to a secure LDAP server.

Previously working script:

New API:

New features have been added to the technology preview of Freeform Studio. Routes created in Freeform Studio in IG 6.0 are automatically transitioned into JSON editor routes.

By default, after installation IG is now in production (immutable) mode instead of development (mutable) mode. To use Studio and manage routes through Common REST, you must switch to development mode.

The chain in routes created in Studio now ends with a ReverseProxyHandler instead of a ClientHandler.

It is now mandatory to register an AM Java agent in order to use the PolicyEnforcementFilter.

The tokens issued by AM for an agent have an unlimited lifetime (unless configured otherwise), and all appropriate permissions, making them a perfect fit for an application needing to ask for policy decisions.

By default, the ClientHandler now verifies the hostname for outgoing SSL connections. By default, in previous releases the hostname was not verified.

For more information, refer to the hostnameVerifier property in ClientHandler.

The filename of a route cannot be default.json, and the route’s name property and route ID cannot be default.

This release supports servlet 3.x. Servlet 2.x is no longer supported.

By default, when the CaptureDecorator property captureEntity is true, up to 512 KB of an entity can be captured. Before this release, IG tried to capture the entire entity.

The CaptureDecorator property maxEntityLength has been added to limit the maximum size of captured entities, and so prevent excessive memory use or OutOfMemoryError.

The default ApiProtectionFilter now protects the /openig/api endpoint. Before this release, it protected the /openig endpoint.

The plus character (+) is now a reserved character in names. It is no longer allowed in object namrs and route names.

The timestamp in route logs now includes the date, and is compliant with ISO 8601. The following examples show the impact of this change on log parsing:

Support for Java 7 has been removed. Before you update to IG 5.5, install the latest version of Java 8.

If you are using IG on Tomcat with SSL enabled, use OpenJDK 1.8.0_121 or later versions to prevent mismatch between client side ciphers and server side ciphers.

Most web containers use JSESSIONID as the default cookie name. To prevent invalid session IDs when a protected application uses the same cookie name as the IG web container, IG now uses IG_SESSIONID as its default cookie name.

The way to configure HTTPS for Jetty has changed in Jetty 9.4. For general information about Jetty and HTTPS, see the Jetty documentation.

As required by RFC 7591, OAuth 2.0 Dynamic Client Registration Protocol, the metadata property of OAuth2ClientFilter supports scope.

Dynamic client registration with versions of AM earlier than 5.5 must use the scopes property. Dynamic client registration with AM 5.5 can use the scopes or scope property.

For the option to dynamically register with a wider range of identity providers, you can use both scope and scopes at the same time.