PingGateway

What’s new

What’s new in PingGateway 2024.9

OpenTelemetry capabilities

This release adds the ability to push traces to an OpenTelemetry service.

These capabilities are available in Technology preview. They aren’t yet supported, may be functionally incomplete, and are subject to change without notice.

Learn more in the following documentation:

Multiple versions of a secret with FileSystemSecretStore

With the new FileSystemSecretStore versionSuffix setting you can have multiple versions of a secret with the same ID.

For details, refer to FileSystemSecretStore.

Replace setting for HeaderFilter

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

For details, refer to HeaderFilter.

Runtime exception condition for retries

The new runtimeExceptionCondition setting lets you restrict which runtime exceptions lead to retries.

Learn more in ClientHandler and ReverseProxyHandler.

Security provider setting for keystores

The new securityProvider setting lets you choose the Java security provider to use when loading a keystore.

Learn more in KeyStoreSecretStore.

Delayed route metrics creation

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.

Separate endpoint for administration

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).

New PingOne Authorize example

The documentation now includes an example showing how to protect a web application with help from PingOne Authorize.

What’s new in PingGateway 2024.6

IG becomes PingGateway

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.

PingOne Protect integration

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.

PingOne Protect integration is available in Technology preview. It isn’t yet supported, may be functionally incomplete, and is subject to change without notice.

Learn more from PingOne Protect integration.

Changes to the Prometheus Scrape Endpoint

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.

New 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.

PingOneApiAccessManagementFilter now supported

The PingOneApiAccessManagementFilter is now supported for general use.

Hardened security for OpenID Connect ID tokens

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:

  • ClientRegistration:

    • skipSignatureVerification

    • clientSecretUsage

    In addition, use the clientSecretId and secretsProvider properties for HMAC-based signature validation.

  • Issuer:

    • issuer

    • secretsProvider

    • idTokenVerificationSecretId

    • idTokenSkewAllowance

Learn more from ClientRegistration configurations and Issuer configurations in Incompatible changes.

What’s new in IG 2024.3

Local authentication on behalf of PingOne Advanced Identity Cloud and Kerberos validation

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 of caches

Monitoring metrics are now available at the Prometheus Scrape Endpoint and Common REST Monitoring Endpoint for the caches described in Caches.

Use of secrets in Studio

IG now uses secrets instead of deprecated passwords. Learn about how IG manages migration in Upgrade from an earlier version of Studio.

Use of Splunk or ElasticSearch audit event handlers in 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.

Hardened security for secrets

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.

IssuerRepository

An IssuerRepository is provided as a default object. Learn more from Default objects.

Dedicated filter for PingOne’s API Access Management (Technology preview)

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.

The PingOneApiAccessManagementFilter is available in Technology preview. It isn’t yet supported, may be functionally incomplete, and is subject to change without notice.

What’s new in IG 2023.11.1

IG 2023.11.1 is a maintenance version to fix issues listed in Fixed in 2023.11.1. It contains no new features.

What’s new in IG 2023.11

Harden OAuth 2.0 access token requests

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.

Include key ID in JWT header

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

Local processing on behalf of PingOne Advanced Identity Cloud (Technology preview)

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:

The IdentityAssertionHandlerTechPreview, ScriptableIdentityAssertionPluginTechPreview, and IdentityAssertionPluginTechPreview are available in Technology preview. They aren’t yet supported, may be functionally incomplete, and are subject to change without notice.
Secret format JwkPropertyFormat

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

More flexible use of CA-certificates in mutual TLS

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.

Safeguard against accidental exposure of private keys with JwkSetHandler

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.

SAML

Prevention of redirect loops when session cookies are not present in the SAML flow

In SamlFederationFilter, the new property redirectionMarker is enabled by default to prevent redirect loops when a session cookie isn’t present in the SAML flow.

When the marker is present in the request query parameters, the request isn’t redirected for authentication.

What’s new in IG 2023.9

Revocation of access tokens initiated by OAuth 2.0 Resource Servers

The following new properties have been added in AuthorizationCodeOAuth2ClientFilter and Issuer:

  • AuthorizationCodeOAuth2ClientFilter:revokeOauth2TokenOnLogout

  • Issuer:revocationEndpoint

In OpenID Connect, use these properties to revoke access and refresh tokens issued by Authorization Servers during login.

Logout initiated by OpenID Connect relying parties

The following new properties have been added in AuthorizationCodeOAuth2ClientFilter and Issuer:

  • AuthorizationCodeOAuth2ClientFilter:openIdEndSessionOnLogout

  • Issuer:endSessionEndpoint

In OpenID Connect, use these properties to initiate logout from Authorization Servers.

Option to require the Authorization Server to prompt the end-user to reauthenticate and consent

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.

Improved error handling for AuthorizationCodeOAuth2ClientFilter

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.

New context for use with AuthorizationCodeOAuth2ClientFilter to retrieve the original target URI for a request

In AuthorizationCodeOAuth2ClientFilter, retrieve the original target URI for a request from the new context IdpSelectionLoginContext.

Improved security for CrossDomainSingleSignOnFilter

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.

What’s new in IG 2023.6

Large JWT session cookies are automatically split

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.

JWT session cookies not compressed by default

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

Startup allowed if there is an existing PID file

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:

  • By the new property pidFileMode in AdminHttpApplication.

  • With the new configuration token ig.pid.file.mode.

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.

Prevention of redirect loops when session cookies are not present in the CDSSO flow

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.

Regex-based alias selection in KeyStoreSecretStore and HsmSecretStore

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.

Entity of StaticResponseHandler can be an array of strings

To improve readability, the entity property of a StaticResponseHandler can now be defined as an array of strings or as a string.

Maximum size for the sum of all request headers

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.

Support for unencoded policy advices

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.

Configure forward proxies for WebSocket connections

websocket:proxyOptions is a new property in ReverseProxyHandler to provide a dedicated WebSocket reverse proxy.

Improved control of WebSocket connections to AM

The following properties are now available in AmService to improve control of WebSocket connections to AM:

  • notifications:connectionTimeout

  • notifications:idleTimeout

  • notifications:vertx

What’s new in IG 2023.4

Authentication of IG agent to PingOne Advanced Identity Cloud and 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.

Policy advices from PingOne Advanced Identity Cloud and AM available in a header

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.

SAML

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.

WebSocket connection renewal

IG can now automatically renew WebSocket connections to AM after a defined delay. For more information, refer to the notifications.renewalDelay property of AmService.

Limit side effects when backend applications are slow

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.

Route ID included access audit events

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.

What’s new in IG 2023.2

Session eviction

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.

This feature requires AM 7.3, which will be available after the IG 2023.2 release.
Preserve POST data during authentication

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.

Prevent unnecessary session expiry

When the AmService property sessionIdleRefresh is enabled, IG now requests session refresh:

  • The first time IG gets an SSO token from AM, irrespective of the age of the token

  • When sessionIdleRefresh.interval has elapsed

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.

CapturedUserPasswordFilter supports secret rotation

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 allows unprotected KeyStores

KeyStoreSecretStore can now use KeyStores that are not password-protected. In previous releases, KeyStores had to be password-protected.

Delay destroying HttpClientHandlerHeaplets during shutdown

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.

Automatic reload of FileSystemSecretStore and KeystoreSecretStore

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.

Groovy 4

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

Expression binding now

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

What’s new in IG 7.2

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:

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.

Filters to support OAuth 2.0 client authentication

When processing requests or responses, IG can require access to systems such as the PingOne Advanced 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

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.

Stop scripts for IG in standalone mode

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

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.

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.

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.

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 timeout.

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.

What’s New in IG 7.1.2

Support for 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.

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

Improved logging

Exception logging when looking for client certificates in ChfApplicationWebHandler has been improved.

When IG detects that AMCtxId is not available in a session, it now checks that notifications are enabled before logging an error. When notifications are disabled, there is no need to make AMCtxId available.

What’s New in IG 7.1.1

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, refer to the vertx object in admin.json, and Monitoring VertX metrics.

Additional Logging for a BadRequestException During Policy Evaluation Requests

To help with troubleshooting, a debug message is 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.

What’s New in IG 7.1

Non-blocking processing and data streaming

Bi-directional asynchronous streaming of the HTTP entity (HTTP/1.1 and HTTP/2)

streamingEnabled is a new property in admin.json for standalone mode to stream the content of HTTP requests and responses. When this property is true, the evaluation of runtime expressions that consume streamed content must be deferred.

This feature introduces changes that can impact your migration from a previous version of IG. For more information, refer to Incompatible changes.

For more information, refer to AdminHttpApplication and runtime expression.

Deferred evaluation of runtime expressions

The evaluation of runtime expressions can be deferred until all of the content of the request or response is available. To prevent blocked threads, use deferred evaluation for runtime expressions that consume streamed content.

For more information, refer to runtime expression.

API security

Retention of URI fragments during authentication

FragmentFilter is a new filter that enables URI fragments to be retained during authentication with the SingleSignOnFilter, CrossDomainSingleSignOnFilter, OAuth2ClientFilter, and PolicyEnforcementFilter. Previously, when an unauthenticated requested a resource that contained a URI fragment, the fragment was lost in the eventual redirect.

For more information, refer to FragmentFilter.

Customized claim checks in IdTokenValidationFilter

Some OAuth 2.0 providers allow roles, groups, and custom properties to be defined in a JWT. The customizer property, previously available in the JwtValidationFilter, has been added to the IdTokenValidationFilter. Use this property to validate customized properties for a JWT, while still validating the existing constraints in the IdTokenValidationFilter.

For more information, refer to IdTokenValidationFilter.

JwtValidationFilter applies constraints for claim comparison and pattern match

In JwtValidationFilter, the set of validation constraints for JWT claims and sub-claims now includes the following additional constraints:

  • Claims comparisons, to check that a claim value compares to another value or the value of another claim as follows: isGreaterOrEqualTo, isGreaterThan, isLessOrEqualTo, or isLessThan.

  • Regex match, to check that the claim value matches a specified regular expression.

For more information, refer to the customizer property in JwtValidationFilter.

Secrets

Support for PEM-encoded secrets

PemPropertyFormat is a new format for secrets used in mappings in FileSystemSecretStore and SystemAndEnvSecretStore. Use PemPropertyFormat to read a Privacy-Enhanced Mail (PEM) file.

For more information, refer to PemPropertyFormat.

Support for SAML 2.0 signing and encryption with secrets

IG can now use the Commons Secrets Service when acting as a SAML 2.0 service provider, when signing and/or encryption is enabled in the IDP or SP configuration in AM.

For more information, refer to SamlFederationHandler.

Expose cryptographic keys as a JWK set

JwkSetHandler is a new handler that exposes cryptographic keys as JWK set. Use this handler so that a downstream application can reuse the exposed keys for their assigned purpose.

For more information and an example of use, refer to JwkSetHandler.

Support for lease expiry in secret stores

leaseExpiry is a new property for the following SecretStores, to define the time that secrets can be cached before they must be refreshed:

  • SystemAndEnvSecretStore

  • FileSystemSecretStore

  • KeystoreSecretStore

  • HsmSecretStore

  • JwkSetSecretStore

For more information, refer to Secrets object and secret stores.

Key ID header available for JwtBuilderFilter and JwtSession

The key ID header, kid, used to match a specific key, is now present in JWTs built by JwtBuilderFilter and JwtSession.

For information about kid, refer to "kid" (Key ID) Parameter.

Stability

Limit on connection attempts prevents stalled requests and timeouts

initialConnectionAttempts is a new property in AmService to limit the number of times IG attempts to open a WebSocket connection before failing to deploy the route. Use this feature to prevent stalled requests and timeouts. For more information, refer to AmService.

Monitoring

TimerDecorator available for AccessTokenResolvers.

The TimerDecorator can now record the time to process requests and responses as they pass through AccessTokenResolvers.

For more information, refer to TimerDecorator.

Log for tested and successful route conditions.

A new logger is available to log the routes for which IG evaluates a condition, and the route that matches a condition and treats a request.

For more information, refer to the condition property of Route.

Other

SAML 2.0 requests processed with original URI value

useOriginalUri is a new property in SamlFederationHandler to prevent errors that occur when a baseUri decorator applies to the whole route. This change forces the handler to use the original URI instead of the rebased URI when validating RelayState and Assertion Consumer Location URLs.

For more information, refer to SamlFederationHandler.

New methods to get and set URL-encoded form data in scripts

Entity.getForm() and Entity.setForm(Form) are new methods available for use in scripts, with the content type application/x-www-form-urlencoded.

Limit on size to which a JWT can be decompressed

org.forgerock.json.jose.jwe.compression.max.decompressed.size.bytes is a new system property to limit the maximum size to which a compressed JWT can be decompressed. This property reduces the risk of a decompressed JWT consuming too much available memory.

For more information, refer to Provided Properties.

Temporary storage directory

By default, the TemporaryStorage object now stores temporary files in $HOME/.openig/tmp instead of a directory defined by the system property java.io.tmpdir.

For more information, refer to TemporaryStorage.

Redirection marker can be disabled or renamed

redirectionMarker is a new property in SingleSignOnFilter to limit the number of authentication redirects.

When there is no SSO session due to, for example, SSO cookie name misconfiguration, an authentication request fails and is redirected back to IG. The scenario can result in infinite authentication redirects.

For more information, refer to SingleSignOnFilter.

Log entry for number of retries

When a runtime error occurs during the execution of a request to a remote server, IG retries the request until the allowed number of retries is reached or the execution succeeds. The retries are now logged by default.

For more information, refer to the retries property of ClientHandler.

System property to decode invalid characters without error

org.forgerock.http.util.ignoreFormParamDecodingError is a new Java system property to ignore form encoding errors caused by invalid characters. Encoded values are used instead.

For more information, refer to Supported system properties.

What’s new in IG 7.0.2

Filter to rebase the scheme, host name, and port of requests

The ForwardedRequestFilter has been added to rebase a request URI with a computed scheme, host name, and port. Use this filter to configure redirects when the request is forwarded by an upstream application such as a TLS offloader.

What’s new in IG 7.0.1

AmService automatically obtains SSO token header name from AM

To reduce configuration errors, and simplify configuration, AmService no longer uses the default value, iPlanetDirectoryPro, for ssoTokenHeader. If ssoTokenHeader is not provided, IG queries the AM /serverinfo/* endpoint for the header name or cookie name of the SSO token.

What’s new in IG 7.0.0

IG as a standalone Java executable

IG is now delivered as a .zip file, for installation in standalone mode. In standalone mode, IG provides a simple unzip installation path, a classes directory for support, a startup script, and support for custom extensions.

A Vert.x-specific configuration block is available in the connector property of admin.json, and in the websocket property of ClientHandler and ReverseProxyHandler.

Support for HTTP/2 when IG is client-side

In standalone mode, IG can use HTTP/2 or HTTP/1.1 to send requests to a proxied application, or request services from a third-party application.

No additional configuration is required to use HTTP/2 over non-TLS. The Application Layer Protocol Negotiation ALPN extension is used for HTTP/2 over TLS.

The protocol is negotiated according to the configuration of IG’s admin.json, the alpn property in ClientTlsOptions, and by the new properties protocolVersion and http2PriorKnowledge in the ClientHandler and ReverseProxyHandler.

Support for HTTP/2 when IG is server-side

IG in standalone mode provides a new object, ServerTlsOptions, to configure server-side properties of the the TLS-protected connector. Use ServerTlsOptions in admin.json.

Support for patching

For IG installed in standalone mode, classes is a new directory in the classpath for patches from support.

Docker

Evaluation Docker image

An unsupported base Docker image is provided for IG, available in a public Docker registry.

IG .zip provides Dockerfile

The IG .zip file now provides a Dockerfile that you can use to build a Docker image.

Api security - separating API security concerns from business concerns

Policies with new options for more flexibility
  • sessionIdleRefresh is a new property of AmService, to periodically refresh AM sessions.

    When the SingleSignOnFilter is used for authentication with AM, AM can view the session as idle even though the user is interacting with IG. The user session eventually times out and the user must re-authenticate.

Authenticate through AM authentication trees and chains

A new property, authenticationService, in SingleSignOnFilter and CrossDomainSingleSignOnFilter lets users authenticate to AM by using AM’s authentication trees and chains.

Adding basic authentication to outgoing requests

HttpBasicAuthenticationClientFilter is a new filter for service-to-service contexts, where IG needs to access remote resources that are protected by HTTP Basic Authentication.

CORS to enable APIs, and control cross-origin access

CorsFilter is a new filter to configure policies to allow user agents to make requests across domains.

Declarative authorization, for local evaluation of authorization rules

AllowOnlyFilter is a new filter to authorize only requests that satisfy a set of rules based on the provenance, destination, and additional conditions of the request. When the rules are not satisfied, the request is rejected.

Financial API grade security

FapiInteractionIdFilter is a new filter to track the interaction ID of requests, according to the Financial-grade API (FAPI) WG.

DateHeaderFilter is a new filter to insert the server date in an HTTP date header on the response.

SetCookieUpdateFilter to update cookie attributes

SetCookieUpdateFilter is a new filter to update cookie attributes. Use SetCookieUpdateFilter for legacy applications, where cookies do not conform to requirements for newer browsers.

Temporary storage files in custom directory

By default, IG writes temporary files to $HOME/.openig/tmp. You can now change the directory by setting the temporaryDirectory property in admin.json.

Skew allowance in StatelessAccessTokenResolver

The property skewAllowance has been added to the StatelessAccessTokenResolver to manage the validity period of access_tokens.

OAuth 2.0, to separate API security concerns from business concerns

Caching OAuth 2.0 access tokens

CacheAccessTokenResolver is a new object to enable and configure caching of OAuth 2.0 access_tokens, based on Caffeine.

mTLS through HTTP headers for certificate-bound access tokens

IG 7 adds support for draft 12 of the OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens specification, a key component of our Open Banking and Revised Payment Services Directive (PSD2) support.

CertificateThumbprintFilter is a new filter to verify of certificate-bound access_tokens. ConfirmationKeyVerifierAccessTokenResolver is a new access token resolver to verify that certificate-bound OAuth 2.0 bearer tokens presented by clients use the same mTLS-authenticated HTTP connection.

Use these objects when IG is running behind a TLS termination point, such as a load balancer or other ingress point.

OAuth 2.0 client credentials filter

ClientCredentialsOAuth2ClientFilter is a new filter to authenticate a client, using the client’s OAuth 2.0 credentials. Use this filter in a service-to-service context, where a service needs to access resources protected by OAuth 2.0.

The filter obtains an access_token from an authorization server, and injects the access_token into the inbound request as a Bearer Authorization header, and refreshes the access_token as required. For more information, refer to ClientCredentialsOAuth2ClientFilter.

Discovery and dynamic registration using private_key_jwt

The private_key_jwt authentication method can now be used for authentication during discovery and dynamic registration with an OpenID Connect provider. In previous releases, only client_secret_basic and client_secret_post authentication methods could be used.

Secrets

SecretsProvider provides improved control over where to search for secrets

SecretsProvider is an updated heap object to specify a secrets service to resolve secrets for IG configuration objects, using the property secretsProvider.

For backward compatibility, if SecretsProvider is not configured, objects use the global secrets service, which searches for keys across the whole configuration. If multiple keys have the same label, there is a bigger risk that the wrong key is used.

New secret stores

JwkSetSecretStore is a new secret store for JSON Web Keys (JWK) in a JWK Set.

Base64EncodedSecretStore is a new secrets store for generic secrets, such as passwords or simple shared secrets, whose base64-encoded values are hard-coded in the route. Use this store for testing or evaluation only. In production, use an alternative secret store.

Secret formats

SecretsKeyPropertyFormat is to define the format and algorithm used for the secrets.

Use this object with FileSystemSecretStore or SystemAndEnvSecretStore, when symmetric keys are provided in files, environment variables, or system properties, by external secret management systems, such as Kubernetes Secrets or Docker Secrets. In previous releases, symmetric keys had to be declared in a KeystoreSecretStore.

KeyManager and TrustManager provided as secrets

SecretsKeyManager is available for IG in standalone mode to provide secrets for KeyManager. Use with ClientTlsOptions and ServerTlsOptions to prove the identity of the local peer during TLS handshake.

SecretsTrustManager is available for IG in standalone mode to provide secrets for TrustManager. Use with ClientTlsOptions and ServerTlsOptions to manage trust material for peer credentials.

Secrets in FileSystemSecretStore or SystemAndEnvSecretStore for signing and encryption

Secrets stored in a FileSystemSecretStore or SystemAndEnvSecretStore can now be used for symmetric signing keys and symmetric encryption keys. In previous releases, keys had to be declared in a KeystoreSecretStore.

For more information, see the mappings property of FileSystemSecretStore and JwtBuilderFilter.

Secrets in CDSSO

IG can now verify the signature of signed CDSSO tokens in cross-domain single sign-on.

For more information, refer to the properties verificationSecretId and secretsProvider in CrossDomainSingleSignOnFilter.

Deterministic ECDSA for JWT signatures

When elliptic curve keys are used for signing, and Bouncy Castle is installed, and, by default, JWTs are signed with a deterministic ECDSA. In previous releases, JWTs were signed with a non-deterministic ECDSA, which is less secure.

The new system property org.forgerock.secrets.preferDeterministicEcdsa is by default true. To use the less secure algorithm, set the property to false.

HTTP sessions

Authenticated encryption for stateless sessions

JWT tokens can now be secured by authenticated encryption with symmetric keys. There is now no need to sign these JWTs as a separate step, leaving more space for session data. Before this release, JWT tokens could only be encrypted and then signed.

SetCookieUpdateFilter

SetCookieUpdateFilter is a new filter to change the attributes of generated cookies.

Stability

Session attributes retrieved without AM session properties whitelist

IG can now retrieve specified session properties or all session properties from AM, without relying on AM’s Session Properties Whitelist. Properties with a value are returned; properties with a null value are not returned.

In previous releases, only whitelisted session properties were returned, irrespective of whether they had a value.

For more information, refer to sessionProperties in AmService.

Skew allowance in JwtSession

A new property skewAllowance has been added to JwtSession to manage small differences in system clocks.

Improved protection from MIME sniffing

To help prevent MIME sniffing of responses from the StaticResponseHandler, the X-Content-Type-Options response header is now set by default to nosniff. In previous releases, the header was not set, allowing the user agent to interpret the response entity as a different content type.

Ping endpoint

A ping endpoint is available after IG startup to check whether IG is available. When IG is installed and running as described in the Getting Started, the endpoint is at http://ig.example.com:8080/openig/ping.

Cloud readiness

Global log level configurable through a variable

To make it easier to deploy IG without modifying the default configuration, the global log level is now defined as a variable in the default logback.xml. To change the global log level, set an environment variable or system property.

Studio

Freeform Designer

Freeform Designer has moved from Technology Preview to Stable, as defined in Product stability labels.

The Studio Welcome page has been replaced by the Routes page.

Global decoration of routes in Studio

The globalDecorators property can now be configured for a route in Studio.

Logs and audits

Allowlisting for audit event fields in logs

To prevent logging of sensitive data for an event, the Common Audit Framework uses an allowlist to specify which event fields appear in logs. By default, only event fields in the list are included in the logs.

Audit of custom events

IG can now record custom audit events as well as access audit events.

AuditClientHandler for Splunk

You can now configure a client handler named AuditClientHandler in the heap, to relay audit events to Splunk.

If a client handler named ElasticsearchClientHandler or SplunkClientHandler is configured in the heap, it is used by priority.

NoOpAuditService provided by default

NoOpAuditService is a new audit service to add an empty audit service to the top-level heap and its child routes. When an AuditService is not defined, auditing is delegated to the parent audit service. For more information, refer to NoOpAuditService.

Core

URI path rewriting

UriPathRewriteFilter is a new filter to rewrite the path of a request URL. Use this filter to expose applications that are on a different path. Continue to use baseURI to override the scheme, host, and port of a request URL. UriPathRewriteFilter does not re-write the content of a message.

ResourceHandler serves static content

ResourceHandler is a new handler to serve static content from a directory. In previous releases, IG could not serve static content so easily. For more information, refer to ResourceHandler.

IG agent in AM

AM now provides a simplified process to create an agent profile for IG. When the IG agent is authenticated, the token can be used for tasks such as getting the user’s profile, making policy evaluations, and connecting to the AM notification endpoint.

Procedures in the Gateway Guide that previously used a Java agent in AM now use the new profile for an IG agent in AM.

Others

JDBC data source configured outside container

JDBC data sources can now be set up independently of the web container configuration. In previous releases, JDBC data sources were configured at the web container level. For more information, refer to JdbcDataSource.

CrossDomainSingleSignOnFilter logout triggered by any aspect of request

New CrossDomainSingleSignOnFilter properties, logoutExpression and defaultLogoutLandingPage, are available to trigger logout of the associated AM session token based on any aspect of a request.

CaptureDecorator for mask header and attribute values

The CaptureDecorator can now be configured to mask the value of headers and attributes in the logs. Use this feature to prevent disclosure of sensitive information in the logs.

Eviction of revoked OAuth 2.0 access tokens

(From AM 6.5.3.) The CacheAccessTokenResolver and OAuth2ResourceServerFilter can now receive a notification when AM revokes an OAuth 2.0 access_token, and can evict the token from the cache.

For more information, refer to CacheAccessTokenResolver, and the cache property of OAuth2ResourceServerFilter.

ipMatch function

The function ipMatch() is added to check whether an IP address matches an IP range.

Class imported automatically for Groovy scripts

The org.forgerock.http.header class is now imported automatically for Groovy scripts.

Enhanced command-line for sample application

When you launch the sample application, new command-line options are available to configure the ports, session timeout, AM URL base for the OpenID provider configuration, and help display.

New functions for URL-safe and filename-safe encoding and decoding

The functions encodeBase64url and decodeBase64url are added to facilitate URL-safe and filename-safe encoding and decoding.

For more information, refer to the functions encodeBase64url and decodeBase64url.

ConnectionFactory heartbeat can be disabled

The heartbeat of the ConnectionFactory used in the org.forgerock.openig.ldap.LdapClient, enabled by default, can now be disabled. In previous releases, it could not be disabled.

Join function can process an iterable string

The join function can now return a string joined with the given separator, from an Iterable value. In previous releases, it used only an array of string values.

What’s new in IG 6.5.4

Protection against cross-site request forgery

CsrfFilter is a new filter to harden protection against CSRF attacks.

What’s new in IG 6.5.3

SAML support for all name ID formats

In SAML SP-initiated SSO, IG can now act as an SP with an IDP that does not support the transient NameID Format. For SP-initiated SSO as well as for IDP-initiated SSO, the NameID Format can be any format supported by the IDP.

In previous releases, for SP-initiated SSO, the NameID Format could be only urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

Spaces maintained in cookie values

As a cookie passes through IG, if the cookie value is not enclosed in quotes, spaces in the cookie value are not removed. In previous releases, spaces were removed.

Option to reuse connections after a request

Not supported for IG in standalone mode.

stateTrackingEnabled is a new property of ClientHandler and ReverseProxyHandler to specify whether a connection can be kept open and reused after a request.

Sample application user passwords updated

The user passwords in the sample application files are updated to align with the new AM password policy.

What’s new in IG 6.5.2

Multiple OIDC providers use same clientID

In OpenID Connect with multiple client registrations, the same clientId can now be used for multiple client registrations if the issuerName for each registration is different.

The clientId must be unique in the context of a single issuer.

In the OAuth2ClientFilter login service URI, specify both the clientId and the issuerName,

Request policy decisions from AM using a configurable resource URL

resourceUriProvider is a new property of the PolicyEnforcementFilter to ease the transition from an agent-based system. Use the property to request AM policy decisions with the original request URL as the resource URL, or with a script to generate the resource URL.

In previous releases, IG could request policy decisions only by using the route baseURI as the resource URL.

Infinite loop prevention in single sign-on

The SingleSignOnFilter has been adapted to prevent an infinite loop when a final redirect is returned without AM session cookie name. The filter now checks the goto query parameter for the presence of the _ig marker parameter.

SingleSignOnFilter logout can be triggered by any aspect of a request

The new SingleSignOnFilter property logoutExpression can trigger logout based on any aspect of a request. Before this improvement, logout could be triggered only when a request matched the URI path.

secure and httpOnly options to the JwtCookieSession cookie config.

secure and httpOnly options on the cookie created for JWT sessions.

Warning if decoded secret starts or ends in a non-ASCII character

IG logs a warning when the decoded value of a BASE64-encoded secret starts or ends with a non-ASCII character.

If a text editor adds a carriage return to the end of a plain string value before it is encoded, non-ASCII characters can be added to the BASE64-encoded value. When the decoded value is used as part of a username/password exchange, it can then cause an authentication error.

Support for SameSite Cookies

sameSite is a new property in CrossDomainSingleSignOnFilter and JwtSession to manage the circumstances in which a cookie is sent to the server. Use this property to manage the risk of cross-site request forgery (CSRF) attacks.

Support for applications using a payload in GET or HEAD requests

The payload body of a GET or HEAD request is now honored. In previous releases, the payload body was removed when the internal Request representation was created. TRACE is the only request that does not support a payload.

Correct maintenance of cookies with sameSite flag

Cookies that arrive at IG with the sameSite flag set are correctly maintained.

Resource exception not logged at error level when AM returns 401

Previously, if the user’s SSO session had expired or become otherwise invalid and was used in a request to IG, calling the AM session info endpoint to get session status would return a 401 response. This 401 response was valid but ended up being logged by IG at Error level, which was misleading, and would generate a large amount of additional logging data.

IG now logs an error message only when the response from an AM session info endpoint is not a 401. IG still logs it as a debug message to show that it was a 401 response.

What’s new in IG 6.5.1

OAuth 2.0 mutual TLS

IG now supports that ability for clients to authenticate AM through OAuth 2.0 mutual TLS (mTLS) and X.509 certificates. You must use self-signed certificates or public key infrastructure (PKI), as per version 12 of the draft OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens.

StatelessAccessTokenResolver can now rely on a SecretsProvider

SecretsProvider is now available to provide a secrets service for the StatelessAccessTokenResolver. It uses specified secret stores to resolve access tokens.

Before this improvement, the StatelessAccessTokenResolver used the global secrets service to resolve access tokens, which searches for keys across the whole configuration. If multiple keys have the same label, there is a bigger risk that the wrong key is used.

For backward compatibility, if SecretsProvider is not configured, the StatelessAccessTokenResolver uses the global secrets service.

Policy enforcement advice

If an AM policy decision denies a request with supported advices, the PolicyEnforcementFilter can now redirect the request to a URL specified in a SingleSignOnFilter, such as the URL of the custom login page. Previously, the filter always redirected the request back to AM.

The URL is passed in a new property, loginEndpoint, in the ssoToken context. To use the redirect, configure loginEndpoint in the SingleSignOnFilter.

New toJSON function to parse strings as JSON

A toJSON function is now available in expressions to parse strings as JSON.

Preserve query strings in URLs

preserveOriginalQueryString in AdminHttpApplication is now available to preserve query strings as they are presented in URLs. Select this option when query strings must not change during processing, for example, in signature verification.

By default, IG tolerates characters that are disallowed in query string URL components, by applying a decode/encode process to the whole query string.

What’s new in IG 6.5

Commons secret service

IG leverages the Commons Secrets Service for the management of passwords and secrets in the following objects: AmService, ClientHandler, ClientRegistration, JwtSession, KeyManager, JwtBuilderFilter, and CapturedUserPasswordFilter.

Managing secrets with the Commons Secrets Service provides the following benefits:

  • Separation from other configuration so that configuration can be moved between environments

  • Storage in different secure backends, including file-based keystores, Hardware Security Modules (HSM), and Key Management Systems (KMS)

  • Provision through environment variables or unencrypted JSON, for deployment simplicity or where host/OS security is considered adequate.

  • Ease of rotation or revocation, regardless of the storage backend.

In this release, routes generated in Studio do not use the Commons Secrets Service. Documentation examples generated with Studio use deprecated properties.

Local validation of stateless access-tokens

The StatelessAccessTokenResolver is now available to validate stateless access tokens without referring to AM. Use StatelessAccessTokenResolver with the access token resolver in OAuth2ResourceServerFilter.

Because IG can validate stateless access tokens locally, without referring AM, this feature provides the following benefits:

  • Improved performance, by reducing the number of network hops required for validation

  • Improved robustness, by validating access tokens even when AM is not available

Supported with OpenAM 13.5, and AM 5 and later versions.

Transactional authorization

IG can now respond to the TransactionConditionAdvice from AM to require users to perform additional actions when trying to access a resource protected by an AM policy.

Performing the additional actions successfully grants a one-time access to the protected resource. Additional attempts to access the resource require the user to perform the additional actions again.

Disconnection strategy WebSocket notification service

IG can now configure what happens to the session cache and policy enforcement cache when the WebSocket notification service is disconnected and then reconnected. By default, the caches are cleared on disconnect.

Dynamic scope evaluation for OAuth2ResourceServerFilter

The OAuth2ResourceServerFilter can now use a script to evaluate which scopes must be provided in an OAuth 2.0 access token to access a protected resource. The script evaluates each request dynamically and returns the scopes that are required for the request to access the protected resource.

Use this feature when protected resources can’t be grouped within a set of static scopes, for example, when one set of URLs require one scope, and another set of URLs require another scope.

JWT encryption with JwtBuilderFilter

A new property, encryption, has been added to the JwtBuilderFilter to configure JWT encryption.

JwtBuilderFilter template declared as expression

The template property of JwtBuilderFilter can now be configured as an expression that evaluates to a map. The referenced map is serialized as a JSON object.

Connection to TLS-Protected endpoints with TlsOptions

A new object, TlsOptions, is available to configure connections to TLS-protected endpoints for the ClientHandler, ReverseProxyHandler, and for WebSocket notifications in AmService.

Increased flexibility for retrieving and caching user profiles from AM

The UserProfileFilter provides new features to retrieve and cache user profile information:

  • User authentication from OAuth 2.0 access tokens with UserProfileFilter

    The UserProfileFilter can now retrieve AM profile attributes for users identified by their username, and can be used in routes that rely on OAuth2ResourceServerFilter and the /oauth2/introspect endpoint to resolve access tokens.

    The filter can use the SsoTokenContext, SessionInfoContext, or OAuth2Context to retrieve profile attributes.

  • Cache for user profile attributes with UserProfileFilter

    The UserProfileFilter can now cache user profile attributes and reuse them without repeatedly querying AM.

    In previous releases, the UserProfileFilter had to query AM for each request to retrieve the required user profile attributes.

Simplified configuration of objects by using AmService

A new property, agent, in AmService defines a Java agent to act on behalf of IG, and simplify configuration of the following filters:

  • SingleSignOnFilter, where agent defines the AM service to use for authentication. Users can authenticate in the same realm as the agent, or in a different realm.

  • PolicyEnforcementFilter, where agent defines the AM agent with the right to request policy decisions from AM. The policy set can be located in the same realm as the agent, or in a different realm.

  • TokenTransformationFilter, where agent defines the AM agent with the right to authenticate IG as an AM REST STS client.

The agent property is now mandatory in AmService and replaces properties in the above filters.

Configuration of WebSocket notifications by using AmService

A new property, notifications, in AmService to disables WebSocket notifications, configures the time between attempts to re-establish lost WebSocket connections, and configures WebSocket connections to TLS-protected endpoints.

UserProfileFilter configuration moved to AmService

To simplify configuration, properties in UserProfileFilter have been deprecated and replaced with properties in AmService.

StudioProtectionFilter to restrict access to studio in development mode

A new filter, StudioProtectionFilter, is available to protect the Studio endpoint when IG is running in development mode.

When IG is running in development mode, by default the Studio endpoint is open and accessible. When StudioProtectionFilter is defined in admin.json, IG uses it to filter access to the Studio endpoint.

New features in Studio

New features have been added to the technology preview of Studio to allow you to:

  • Configure a SplunkAuditEventHandler

  • Upgrade HTTP connections to WebSocket protocol

  • Enable a session cache

  • Evaluate scopes dynamically for OAuth 2.0 authorization

New features in Freeform Studio

New features have been added to the technology preview of Freeform Studio to allow you to:

  • Create new routes that contain a SingleSignOnFilter, a PolicyEnforcementFilter, and an example AmService. Select the objects to configure them.

  • Drag and drop a SingleSignOnFilter, a PolicyEnforcementFilter, or any filter type onto the canvas. Select the filter to configure it. For other filter types, select the type, name the filter, and add the JSON configuration.

  • Define multiple AmService objects that you can choose from for filters.

  • Drag and drop a DispatchHandler onto the canvas, select its input node to connect it to the start element or another object, and select its output node to connect to one or more handlers. Select the connections to define the conditions for the dispatch.

  • Drag any filter into or out of a chain, and drag any filter or handler around the canvas. Select it to delete it.

  • Ctrl-click to select multiple objects, and maneuver or delete them at the same time.

  • View unconnected filters or handlers on the canvas as part of the JSON heap.

  • View the object name on the canvas.

Routes created in previous version of Freeform Studio are automatically transitioned into JSON editor routes.

TimerDecorator publishes metrics to the metric registry

When a TimerDecorator is set to true in a route, the metrics are now written to the Prometheus Scrape Endpoint and the Common REST Monitoring Endpoint.

Audit logging to standard output

Support has been added for an audit handler to send access log messages to standard output.

Default configurations for objects in AdminHttpApplication

AdminHttpApplication now declares default configurations for the following objects: ClientHandler, ReverseProxyHandler, ForgeRockClientHandler, ScheduledThreadPoolExecutor, and TransactionIdOutboundFilter.

WebSocket traffic for TLS connections

IG can now detect requests to upgrade from HTTPS to the WebSocket protocol, and create a secure, dedicated tunnel to send and receive WebSocket traffic.

What’s new in IG 6.1

Proxy WebSocket traffic

IG can now detect requests to upgrade from HTTP to the WebSocket protocol, and create a dedicated tunnel to send and receive WebSocket traffic.

When you create a route in Studio, you can enable a new option to upgrade HTTP connections to WebSocket protocol.

To help with development, the sample app has been updated to include a WebSocket endpoint that exposes a simple WebSocket server.

IG cannot proxy WebSocket traffic for TLS connections, or when it is running in the Jetty application container.
JwtBuilderFilter to pass identity or other runtime info downstream

A new filter, JwtBuilderFilter, collects data at runtime, packs it in a JSON Web Token (JWT), and places the resulting JWT into the JwtBuilderContext. When the JwtBuilderFilter is used with a HeaderFilter, it provides a flexible way for IG to pass identity or other runtime information to the protected application.

To help with development, the sample app has been updated to include a /jwt endpoint that displays the JWT and verifies its signature.

The JWT created by JwtBuilderFilter can be signed but is not encrypted. Carefully consider the security of your configuration when using this filter.
New features in Freeform Studio

New features have been added to the technology preview of Freeform Studio to allow you to:

  • Drag-and-drop filters and handlers onto the canvas.

  • Add, reorder, or remove filters in a chain.

  • Connect a start node to a chain or handler, and connect chains to handlers.

  • Double-click on any node to edit it or rename it.

  • Easily edit SingleSignOnFilters in a dedicated page that hides the JSON representation.

  • Get feedback on structural errors in your route before you deploy it, by simply displaying the route configuration.

  • Routes created in Freeform Studio in IG 6.0 are automatically transitioned into JSON editor routes.

Disable capture

Instead of removing the decorator from the configuration, you can now configure the capture point none to disable capture.

Client connection pool timeToLive is configurable

You can now expire pooled connections after a fixed duration by setting a new property connectionTimeToLive in the ClientHandler and ReverseProxyHandler. To prevent the reuse of connections, set this property in routes for applications where the IP address (baseURI) is not stable or can change.

What’s new in IG 6

ReverseProxyHandler to stream responses from a proxied application to the user agent

When IG fails to connect to a proxied application, the ReverseProxyHandler changes the runtime exception into a 502 Bad Gateway response.

When streaming is enabled, responses are processed as soon as all headers are received. The entity content is downloaded in a background thread. This mode reduces latency, and is mandatory for Server-Sent Events

UserProfileFilter to retrieve profile attributes of an AM user

A new filter, UserProfileFilter, queries AM to retrieve the profile attributes of an AM user. It makes the data available as a new context to downstream IG filters and handlers.

New SessionInfoFilter collects information about the AM session and makes it available to downstream handlers

A new filter, SessionInfoFilter, calls the AM endpoint for session information, and makes the data available as a new context to downstream IG filters and handlers. Session properties that are allowlisted in AM are available.

Support for Cross-Domain Single Sign-On

CrossDomainSingleSignOnFilter, CdSsoContext, and CdSsoFailureContext have been added. Users can authenticate to AM in one domain, and then access resources protected by IG in another domain, without having to re-authenticate.

Updated monitoring

The Prometheus Scrape Endpoint and Common REST Monitoring Endpoint have been added for monitoring.

The endpoints are available in IG, without any configuration. Metrics are available for each router, subrouter, and route in the configuration, and for the defaultHandler of the main router.

By default, everyone has read access to the Prometheus endpoint. No special credentials or privileges are required, but access can be restricted.

AmService heap object to hold configuration information about AM

The AmService heap object can be declared in the IG configuration to hold information about an instance of AM. IG objects that communicate with AM can share AmService, reducing the number of configuration properties in their configuration.

Agentless AM password capture and replay

The new CapturedUserPasswordFilter makes it possible to use AM’s password capture and replay feature without an AM policy agent.

This filter retrieves an AM password, decrypts it, and exposes it in a new context. By using CapturedUserPasswordFilter, you can get login credentials from AM without setting up an AM policy agent.

From AM 6, CapturedUserPasswordFilter can use the stronger algorithm AES to decrypt the AM password.

Introduction of session token cache

AmService provides a shared session service that can cache session token info for improved performance.

IG can now receive notifications from AM on session logout, or when an AM session is modified, closed, destroyed, or times out. IG evicts related entries from the session cache.

SingleSignOnFilter, CrossDomainSingleSignOnFilter, SessionInfoFilter, UserProfileFilter and PolicyEnforcementFilter are using that shared service.

In previous releases, the SingleSignOnFilter called AM to validate the SSO token for every request in a session. The SingleSignOnFilter can now process multiple requests in the same session without calling AM to validate the SSO token.

Eviction from the PolicyEnforcementFilter cache

IG can now capture WebSocket notifications from AM when a policy is created, deleted, or updated, and then clear the PolicyEnforcementFilter cache. To facilitate this feature, the PolicyEnforcementFilter cache has been replaced by a cache based on Caffeine.

More configuration options for caching for OAuth 2.0 access tokens

More options are provided for caching access tokens in OAuth2ResourceServerFilter.

Faster response processing and processing for response sizes over 2 GB

From this release, when streaming is enabled on the ClientHandler or ReverseProxyHandler, IG begins streaming a response to a client as soon as it begins receiving it from the downstream application.

Because IG does not need to buffer the entire content of the response, it can process responses faster, and can proxy applications and APIs that send responses bigger than 2 GB.

If the response flow includes a filter that buffers the entire content of the response, such as capture decorator, processing takes longer and the maximum size of the response is 2 GB.

AM realm containing UMA configuration can be specified

The AM realm that contains the UMA configuration can be specified in UmaService.

The endpoint for the UMA sharing service is now configured by the wellKnownEndpoint property of UmaService instead of authorizationServerUri. authorizationServerUri has been removed.

Support for additional advice types in PolicyEnforcementFilter

The PolicyEnforcementFilter now supports the following AM advice types in addition to AuthLevel:

  • AuthenticateToService

  • AuthenticateToRealm

  • AuthScheme

IG can use system-defined proxy server

IG can now make use of a system-defined proxy server. Use the new systemProxy property of ClientHandler and ReverseProxyHandler to access the feature.

Support for parameterized configuration

Support for parameterized configuration has been added through the introduction of configuration tokens, and the processes of token resolution, JSON evaluation, token substitution, and data transformation.

At startup and when routes are loaded, token resolvers make values available from environment variables, Java system properties, JSON and Java properties files, and route properties. Matching values are substituted in the configuration files as strings, and then transformed as required into different data types.

IG can proxy SSE API

IG can now proxy Server Sent Events (SSE) API.

Captured entity size is limited

The CaptureDecorator property maxEntityLength has been added to limit the number of bytes that can be captured for an entity. Before this release, IG tried to capture the entire entity.

When the CaptureDecorator property captureEntity is true, use this property to prevent excessive memory use or OutOfMemoryError errors.

IG is automatically deployed on the root context in Jetty

To deploy IG in Jetty, it is no longer necessary to rename the IG .war file from ig.war to root.war.

Class import for Groovy scripts

The following additional classes are now imported automatically for Groovy scripts:

  • org.forgerock.http.oauth2.AccessTokenInfo

  • org.forgerock.json.JsonValue

It is no longer necessary to include imports statements for these classes in Groovy scripts.

IG can retry HTTP requests

IG can now retry failed HTTP requests. You can specify the number of times IG retries a failed request, and the delay between retries.

In bootstrap scenarios where IG depends on third-party services, IG can now pause the startup process until the required services are online (for example, OpenID Connect well-know configuration endpoint).

Technology preview of Freeform Studio

Freeform Studio is a new user interface to develop complex routes of filters and handlers. As you design a route, Freeform Studio helps you to visualize the chain of filters and handlers, identify break points, and track the path of requests, responses, and contexts.

Configuration for TokenTransformationFilter

The TokenTransformationFilter can now be configured in Studio.

Use of Arguments in scripts

Scripts for use in the ScriptableFilter and ThrottlingFilter can now be configured with arguments in Studio.

Audit logging with JSON audit event handler and ElasticSearch audit event handler

Audit logging can now be configured in Studio for JSON audit event handler and ElasticSearch audit event handler.

Configuration for stateless sessions

Stateless sessions that do not use a keystore can now be configured in Studio.

Assisted Upgrade for Routes Deployed in Studio

During IG upgrade, routes that were previously created in Studio are automatically transferred to the new version of IG. If extra information is required for compatibility, you are prompted for the required information.

Capture message context in Studio

Studio can now be used to configure the capture of the message context as well as the message body.

What’s new in IG 5.5

Studio improvements
  • Throttling policies

    Grouping policies that apply a throttling rate to a single group containing all requests, or to independent groups of requests. Groups can be defined with a standard or custom grouping policy.

    Mapping policies that allow custom mapping criteria, and multiple mapped rates in mapped throttling policies.

  • Different filter types

    The following filter types and scripts can now be created in Studio: generic filters, scripts, scriptable filters, and scriptable rate policies for throttling filters.

  • Route import

    Routes can now be imported from external .json files into Studio. Routes not created in Studio can be viewed in the backend configuration.

  • Route editing

    The Studio editor ca nbe used to edit routes that were created in Studio, imported from file, or that exist your backend configuration.

  • Route viewing

    A route’s filters can now be viewed in a chain, and reordered in the chain.

    You can view a route’s status to see if it is Undeployed, Deployed, Changes pending, or Out of sync

  • Capture

    Studio can now capture Ping Identity Platform messages as well as messages about requests and responses that are traversing the route.

  • Search

    Studio now includes a search feature to search for routes.

OAuth 2.0 Token Introspection

IG now supports the token introspection endpoint, /oauth2/introspect to resolve OAuth 2.0 access tokens. In previous releases, only the token info endpoint, /oauth2/tokeninfo, was supported.

Use the /oauth2/introspect endpoint to retrieve metadata about a token that is not available at the /oauth2/tokeninfo endpoint, such as the context in which the token was issued.

Client authentication through private_key_jwt

Clients can now authenticate to an OAuth 2.0 authorization server or OpenID provider using the tokenEndpointAuthMethod method private_key_jwt.

With private_key_jwt, you can configure claims to be used for client authentication during access token retrieval.

Scripting to configure OAuth 2.0 token resolution

It is now possible to configure access token resolution by using a script. For information about all configuration options, see the accessTokenResolver property of OAuth2ResourceServerFilter.

Support for IG JBoss EAP

IG can now run in JBoss Enterprise Application Platform (JBoss EAP) version 7.

Audit event handlers

Support has been added for the Splunk audit event handler.

Support for UMA 2.0

Support for UMA 2.0 has been added in this release. Features and functionality have been upgraded to support new UMA standards. Support for earlier versions of UMA has been removed.

Configuration expressions for header name and form parameter name of StaticRequestFilter

Configuration expressions can now be used to create the following properties of the StaticRequestFilter:

  • name field of the property headers

  • param field of the property form

This feature provides the flexibility to assign different header names and form parameters when using the same route in different environments. For example, the name of a cookie header can be different in a production or development environment.

ClientHandler can declare an HTTP web proxy

The ClientHandler can now declare an outgoing proxy server such as Squid to submit requests to other parts of the network.

Runtime expressions for baseURI of DispatchHandler

Runtime expressions can now be used to define the baseURI property of DispatchHandler.

This feature provides the flexibility to change the baseURI according to some request attributes.

Increased flexibility for authentication in SingleSignOnFilter

A new property, loginEndpoint, is added to the SingleSignOnFilter to increase flexibility for authentication. Authentication can be performed through AM or an alternative application, and can include authentication parameters. For information, see the loginEndpoint property of SingleSignOnFilter

Configuration expressions in prefix and the reference configuration object

Configuration expressions can now be used in the definition of prefix and the reference configuration object.

Audit event fields case-insensitive for filtering

A list of audit event fields can be specified to be considered as case-insensitive for filtering.

Copyright © 2010-2024 ForgeRock, all rights reserved.