What’s New

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, see Incompatible Changes.

For more information, see AdminHttpApplication (admin.json) 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, see 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, see 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, see 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, see 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.

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, see 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, see 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, see Secrets.

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, see "kid" (Key ID) Parameter.

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

Filter to Rebase Requests Scheme, Host Name, and Port

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.

For more information, see ForwardedRequestFilter.

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, see 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, see TimerDecorator.

Log for Tested and Succesful 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, see 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, see 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, see 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, see 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, see 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, see 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, see Supported System Properties.