What's New

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

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.

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.

For information about migrating from IG in web container mode to IG in standalone mode, see Migration. For information about installing in standalone mode, see "Downloading and Starting IG in Standalone Mode".

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.

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.

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

ForgeRock provides an unsupported base Docker image for IG, available in ForgeRock’s public Docker registry. For information about using the Docker image, see the Deployment Guide.

The IG .zip file now provides a Dockerfile that you can use to build a Docker image. For information, see the Deployment Guide.

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

For more information, see "SingleSignOnFilter" and "CrossDomainSingleSignOnFilter".

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

CorsFilter is a new filter to configure policies to allow user agents to make requests across domains. For more information, see "CorsFilter".

CsrfFilter is a new filter to harden protection against CSRF attacks. For more information, see Protecting Against CSRF Attacks and "CsrfFilter".

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. For more information, see "AllowOnlyFilter".

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

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

For information, see "AdminHttpApplication (admin.json)".

In OpenID Connect with multiple client registrations, the same clientId can now be used for multiple client registrations if 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,

For more information, see "OAuth2ClientFilter" and "ClientRegistration", "Issuer".

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

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

For information, see "StatelessAccessTokenResolver".

CacheAccessTokenResolver is a new object to enable and configure caching of OAuth 2.0 access_tokens, based on Caffeine. For more information, see "CacheAccessTokenResolver".

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 ForgeRock's 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.

For more information, see "CertificateThumbprintFilter", "ConfirmationKeyVerifierAccessTokenResolver", and "Validating Certificate-Bound Access Tokens".

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 information, see "ClientCredentialsOAuth2ClientFilter".

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.

For more information, see "OAuth2ClientFilter", and the example in "Discovering and Dynamically Registering With OpenID Connect Providers".

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.

For information, see "SecretsProvider".

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.

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 "Packing Data Into a JWT Signed With a Symmetric Key".

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

For information, see the properties verificationSecretId and secretsProvider in "CrossDomainSingleSignOnFilter".

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.

For more information, see "Algorithms for Elliptic Curve Digital Signatures".

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. For information, see "JwtSession".

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.

For information, see the authCookie property of "CrossDomainSingleSignOnFilter", or the cookie property of "JwtSession".

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

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 information, see sessionProperties in "AmService".

The SingleSignOnFilter has been adapted to prevent an infinite loop when a final redirect is returned without an AM session cookie name.

For information, see "SingleSignOnFilter", and "CrossDomainSingleSignOnFilter".

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

For information, see "JwtSession".

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.

For information about how to protect against cross-site scripting, see "General Security Considerations".

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 Guide, the endpoint is at http://openig.example.com:8080/openig/ping.

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.

For information, see "Changing the Global Log Level".

Freeform Designer has moved from Technology Preview to Stable, as defined in Release Levels and Interface Stability.

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

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

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

For more information, see "Safelisting Audit Event Fields for the Logs".

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

For an example of how to configure custom audit events, see "Recording Custom Audit Events". For information about auditing, see Audit Framework.

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

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

For information, see "SplunkAuditEventHandler".

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, "NoOpAuditService".

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. For more information, see "UriPathRewriteFilter".

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

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 a the new profile for an IG agent in AM.

The toJson function has been added for expressions.

For information, see "toJson".

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, see "JdbcDataSource".

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.

For information, see "SingleSignOnFilter".

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

For information, see "CrossDomainSingleSignOnFilter".

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.

For more information, see "CaptureDecorator".

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.

For more information, see "Using a Non-Transient NameID Format".

(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 information, see "CacheAccessTokenResolver", and the cache property of "OAuth2ResourceServerFilter".

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

For information, see "ipMatch".

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.

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

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. For more information, see "Configuration Options for the Sample Application".

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.

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.

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

For information, see "encodeBase64url" and "decodeBase64url".

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.

For an example of how to disable the ConnectionFactory heartbeat, see "Authenticate to an LDAP Server".

A new property in admin.json lets you 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.

For information, see preserveOriginalQueryString in "AdminHttpApplication (admin.json)".

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.

For information, see "ClientHandler" or "ReverseProxyHandler".

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.

For more information, see "join".