What’s new
Token exchange
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
Connectivity with OAuth 2.0-protected third-party services
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:
-
AuthorizationCodeOAuth2ClientFilter, using OAuth 2.0 delegated authorization
-
ClientCredentialsOAuth2ClientFilter, using the client’s OAuth 2.0 credentials
-
ResourceOwnerOAuth2ClientFilter, using the resource owner’s password credentials
ClientCredentialsOAuth2ClientFilter uses client_secret_basic
or client_secret_post
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
.
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
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.
Circuit breaking
CircuitBreakerFilter
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.
Circuit breaker in ClientHandler and ReverseProxyHandler
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.
Stability
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
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.
Other
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
stop script.
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 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.
SNI to serve different certificates for TLS Connections to different server names
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
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.
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 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.
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
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.
Use expressions to configure paths in UriPathRewriteFilter
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.
New EL functions for better pattern matching
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.
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
.
The property version
is used only if AmService cannot discover the AM
version.
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
ClientTlsOptions.
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.
Proxy configuration can be created in the heap and used for AM notifications
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.