Token exchange filter
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
OAuth2ClientFilter renamed as AuthorizationCodeOAuth2ClientFilter.
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 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
ResourceOwnerOAuth2ClientFilter for services to access resources protected by OAuth 2.0.
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.
Filters to support OAuth 2.0 client authentication
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:
OAuth 2.0 session sharing across routes
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.
JwtBuilderFilter produces encrypted JWT
The JwtBuilderFilter now produces encrypted JWTs, in addition to unsigned JWTs, signed JWTs, and signed then encrypted JWTs.
JwtSession cookie compression
useCompression has been added to JwtSession.
When a session stores large items, such as tokens, use the default value
to reduce size of the cookie that stores the JWT.
Windows start script for IG in standalone mode
A script is now provided to start IG in standalone mode on Windows. For information, see Install IG in standalone mode.
Stop scripts for 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 environment variables for startup
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
For more information, see Define environment variables for startup, runtime, and stop.
Support for samesite cookies in standalone mode
sameSite is a new subproperty of
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.
SNI to serve different certificates for TLS Connections to different server names
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.
IG proxies all WebSocket subprotocols by default
In previous releases, for IG in standalone mode it was necessary to list
the WebSocket subprotocols that were proxied by IG, with the
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.
Configurable conditions for retries in ClientHandler and ReverseProxyHandler
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.
User ID in audit logs
Audit logs can now include a user ID. Example scripts and setup information is provided in Recording user ID in audit events.
Tracking ID logged in access audit events
In routes containing an OAuth2ResourceServerFilter, OAuth 2.0 token tracking IDs are now logged in access audit events.
Transformation from string to placeholder string
$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.
Use expressions to configure paths in UriPathRewriteFilter
mapping object in UriPathRewriteFilter now uses configuration expressions
to define the
toPath. In previous releases, the
object was a static JSON map.
For more information, see UriPathRewriteFilter.
New EL functions for better pattern matching
matchesWithRegex are added to use as
replacements for the deprecated function
findGroups is added to use as a
replacement for the deprecated function
For more information, see Functions.
Additional logging for a BadRequestException during policy evaluation requests
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.
PolicyDecisionContext includes actions from the policy decision response
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.
AmService detects AM version
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 is used only if AmService cannot discover the AM
Certificate issued by a trusted CA for any hostname or domain is accepted for a connection to any domain
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
Product information in startup logs
Key product information, such as the product version and build number, is now included in the startup logs.
Improved error handling in ScriptableFilter and ScriptableHandler
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.
AmService Websocket connections protected from timeout
A heartbeat can be configured on the AmService WebSocket notification service to prevent Websocket connections from being closed for timeout.
Timeout of idle AM sessions
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.