What’s new

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

IG provides several client authentication filters, which protect resources by using different types of information and credentials. To make it easier to differentiate between these filters, the OAuth2ClientFilter has been renamed as AuthorizationCodeOAuth2ClientFilter. For backward compatibility, the name OAuth2ClientFilter can still be used in routes.

The following client authentication filters are available to authenticate clients:

The ClientCredentialsOAuth2ClientFilter can now obtain a client’s access token, using the token endpoint authentication method client_secret_post. In previous releases, it could use only client_secret_basic.

Client authentication is now provided by the endpointHandler property of ClientCredentialsOAuth2ClientFilter, which uses ClientSecretBasicAuthenticationFilter or ClientSecretPostAuthenticationFilter. In previous releases, it was provided by the now deprecated properties clientId and clientSecretId.

A new filter ResourceOwnerOAuth2ClientFilter is available for services to access resources protected by OAuth 2.0, using the Resource Owner Password Credentials grant type. For an example of use, see Using OAuth 2.0 resource owner password credentials.

When processing requests or responses, IG can require access to systems such as the Identity Cloud to query user information. The following filters have been added to faciliate OAuth 2.0 client authentication to these systems, where IG is the client:

Use these filters with the following objects:

The property oAuth2SessionKey has been added to AuthorizationCodeOAuth2ClientFilter to allow multiple applications to share the same OAuth 2.0 session.

After a resource owner gives one application protected by IG consent to use its data, they don’t need to give consent for another application protected by IG.

In previous releases, the OAuth 2.0 session was bound to the full URI of the client callback, containing the IG hostname. So it was not possible to use the same OAuth 2.0 session to access different applications.

CircuitBreakerFilter is a new filter to monitor for failures. When the failures reach a specified threshold, the CircuitBreakerFilter prevents further calls to downstream filters and returns a runtime exception.

OPENIG-6517 A new property circuitBreaker has been added to ClientHandler and ReverseProxyHandler to provide a circuit breaker service when the number of failures reaches a configured threshold.

The JwtBuilderFilter now produces encrypted JWTs, in addition to unsigned JWTs, signed JWTs, and signed then encrypted JWTs.

The property useCompression has been added to JwtSession. When a session stores large items, such as tokens, use the default value true to reduce size of the cookie that stores the JWT.

A script is now provided to start IG in standalone mode on Windows. For information, see Install IG in standalone mode.

Scripts are now provided to stop IG in standalone mode, on Unix/OS X and Windows. For information, see Install IG in standalone mode.

IG_OPTS is a new environment variable to separate Java runtime options for IG startup and stop scripts with IG in standalone mode. Use IG_OPTS instead of JAVA_OPTS for all options that are not shared with the stop script.

For more information, see Define environment variables for startup, runtime, and stop.

sameSite is a new subproperty of session in admin.json, to manage the circumstances in which a cookie is sent to the server. Use this property to reduce the risk of cross-site request forgery (CSRF) attacks when IG is in standalone mode.

In ServerTlsOptions, sni is a new property to serve different secret key and certificate pairs for TLS connections to different server names in the deployment. In previous releases, only the keyManager property was available to serve the same secret key and certificate pair for TLS connections to all server names.

Use this property when IG is acting server-side, to front multiple services or websites on the same port of a machine.

For an example, see Serve different certificates for TLS connections to different server names.

Vert.x metrics are now available by default for IG in standalone mode, to provide metrics for HTTP, TCP, and the internal component pool. The metrics provide low-level information about requests and responses, such as the number of bytes, duration, the number of concurrent requests, and so on.

Metrics are provided at the Prometheus Scrape Endpoint and Common REST Monitoring Endpoint endpoints.

For more information, see the vertx object in AdminHttpApplication (admin.json), and Monitoring Vert.x metrics.

In previous releases, for IG in standalone mode it was necessary to list the WebSocket subprotocols that were proxied by IG, with the vertx property of admin.json.

From this release, IG proxies all WebSocket subprotocols by default; it is not neccessary to specify protocols. If you do specify protocols, IG supports only those protocols and no others.

condition is a new property in the retries configuration of ClientHandler and ReverseProxyHandler. Use this property to configure a condition on which to trigger a retry. In previous releases, a retry could be triggered only for runtime exceptions.

Audit logs can now include a user ID. Example scripts and setup information is provided in Recording user ID in audit events.

In routes containing an OAuth2ResourceServerFilter, OAuth 2.0 token tracking IDs are now logged in access audit events.

The $string transformation has been added to facilitate the transformation from a string to a placeholder string, which is not encoded. Use this transformation for placeholder strings that that must not be encrypted, for example, when they reference a secret value.

For more information, see string in Token Transformation.

The mapping object in UriPathRewriteFilter now uses configuration expressions to define the fromPath and toPath. In previous releases, the mapping object was a static JSON map.

For more information, see UriPathRewriteFilter.

The functions find and matchesWithRegex are added to use as replacements for the deprecated function matches.

The function findGroups is added to use as a replacement for the deprecated function matchingGroups.

For more information, see Functions.

To help with troubleshooting, a debug message is now also logged when a BadRequestException occurs during policy evaluation requests. In previous releases, the original error was not logged, IG just returned an HTTP 401 Unauthorized.

Actions from the AM policy decision response are now available in the PolicyDecisionContext, and available for use.

The resource value that was used when making the policy request is now available in PolicyDecisionContext.

PolicyDecisionContext.

AmService now reads the AM version from the AM endpoint, and uses the discovered version instead of the value configured in the AmService property version.

The property version is used only if AmService cannot discover the AM version.

When IG is acting as a WebSocket proxy, and the downstream application is on HTTPS, the WebSocket configuration host can now allow a certificate issued by a trusted CA for any hostname or domain to be accepted for a connection to any domain. For information, see the hostnameVerifier property of ClientTlsOptions.

Key product information, such as the product version and build number, is now included in the startup logs.

The ScriptableFilter and ScriptableHandler now propagate script exceptions as runtime exceptions in the promise flow. In previous releases, they replaced the exception with a response, with HTTP status 500. Users didn’t know if the response was from the requested endpoint or caused by an exception in the chain.

A heartbeat can be configured on the AmService WebSocket notification service to prevent Websocket connections from being closed for timeout.

A new filter AmSessionIdleTimeoutFilter is available to force the revocation of AM sessions that have been idle for a specified timeouot.

Use this filter in front of a SingleSignOnFilter or CrossDomainSingleSignOnFilter, to manage idle timeout for client sessions in AM.

A new ProxyOptions heaplet is available to define a proxy to which a ClientHandler or ReverseProxyHandler can submit requests, and an AmService can submit Websocket notifications.

A new global ProxyOption heap object is provided.