Notes on prerequisites, fixes, and known issues for the ForgeRock® Identity Gateway.

Preface

ForgeRock Identity Platform™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

Chapter 1. What's New

1.1. Maintenance Releases

IG 5.5.2

ForgeRock maintenance releases contain a collection of fixes and minor RFEs that have been grouped together and released as part of our commitment to support our customers. For general information on ForgeRock's maintenance and patch releases, see Maintenance and Patch Availability Policy.

  • IG 5.5.2 is the latest release targeted for IG 5.5, and 5.5.1 deployments and can be downloaded from the ForgeRock Backstage website. To view the list of fixes in this release, see Key Fixes in IG 5.5.2.

    The release can be deployed as an initial deployment or updated from an existing 5.5 or 5.5.1 deployment.

1.2. New Features

What's New in IG 5.5.2
  • There are no new features in this release.

What's New in IG 5.5.1
  • There are no new features in this release.

IG 5.5

IG 5.5 includes the following new features:

IG Studio

IG Studio has been updated to include the following features:

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

Creation of Different Filter Types

The following filter types and scripts can now be created in IG 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 IG Studio. Routes not created in IG Studio can be viewed in the backend configuration.

Route Editing

The IG Studio editor ca nbe used to edit routes that were created in IG 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

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

Search

IG Studio now includes a search feature to search for routes.

OAuth 2.0

OAuth 2.0 has been updated to include the following features:

OAuth 2.0 Token Introspection

IG now supports the token introspection endpoint, /oauth2/introspect to resolve OAuth2 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.

For information about the token introspection endpoint, see RFC-7662, OAuth 2.0 Token Introspection.

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.

For information, see ClientRegistration(5) in the Configuration Reference.

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(5) in the Configuration Reference.

Support for IG JBoss EAP

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

For information, see "JBoss EAP For IG" in the Gateway Guide.

Audit Event Handlers

Support has been added for the Splunk Audit Handler. For information, see SplunkAuditEvenHandler(5) in the Configuration Reference.

1.3. Product Improvements

IG 5.5.2
  • There are no major improvements to existing functionality other than bug fixes.

IG 5.5.1
  • There are no major improvements to existing functionality other than bug fixes.

IG 5.5

IG 5.5 includes the following improvements:

Default cookie name is IG_SESSIONID

Most web containers use JSESSIONID as the default cookie name. To prevent invalid session IDs when a protected application uses the same cookie name as the IG web container, IG now uses IG_SESSIONID as its default cookie name.

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.

For information, see "Supporting UMA Resource Servers" in the Gateway Guide and UmaService(5) in the Configuration Reference.

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.

For information, see StaticRequestFilter(5) in the Configuration Reference.

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.

For information, see the proxy property of ClientHandler(5) in the Configuration Reference.

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.

For information, see DispatchHandler(5) in the Configuration Reference.

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(5) in the Configuration Reference.

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.

For information, see reference in the Configuration Reference and AdminHttpApplication(5) in the Configuration Reference.

Audit Event Fields Case-Insensitive For Filtering

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

For information, see AuditService(5) in the Configuration Reference.

Support for "scope" in Dynamic Client Registration

As required by RFC 7591, OAuth 2.0 Dynamic Client Registration Protocol, the metadata property of OAuth2ClientFilter now supports scope.

Dynamic client registration with versions of AM earlier than 5.5 must use the scopes property.

Dynamic client registration with AM 5.5 can use the scopes or scope property.

For the option to dynamically register with a wider range of identity providers, you can use both scope and scopes at the same time.

1.4. Security Advisories

ForgeRock issues security advisories in collaboration with our customers and the open source community to address any security vulnerabilities transparently and rapidly. ForgeRock's security advisory policy governs the process on how security issues are submitted, received, and evaluated as well as the timeline for the issuance of security advisories and patches.

For details of all the security advisories across ForgeRock products, see Security Advisories in the Knowledge Base library.

Chapter 2. Before You Install

This chapter describes the requirements for running IG.

Tip

If you have a special request to support a component or combination not listed here, contact ForgeRock at info@forgerock.com.

2.1. Downloading IG Software

Download the following product software from the ForgeRock BackStage download site:

  • IG .war file, IG-5.5.2.war

  • Web application for testing IG configurations, IG-sample-application-5.5.2.jar

2.2. JDK Version

IG runs with the following JDKs:

  • Oracle JDK 8

  • OpenJDK 1.8

    If you are using IG on Tomcat with SSL enabled, use OpenJDK 1.8.0_121 or later versions to prevent mismatch between client side ciphers and server side ciphers.

For the latest security fixes, ForgeRock recommends that you use the most recent update.

If you install an AM policy agent in the same container as IG, you must use a Java release that is also supported by that policy agent.

2.3. Web Application Containers

IG runs in the following web application containers:

  • Apache Tomcat 7, 8, or 8.5.x

  • Jetty 8 (8.1.13 or later), or 9

  • JBoss EAP 7

Important

Support for Tomcat 7 and Jetty 8 (8.1.13 or later) will be removed in a future release.

Deploy IG to the root context of the container. Deployment in other contexts causes unexpected results, and is not supported.

For information about setting up a web application container see "Configuring Deployment Containers" in the Gateway Guide.

2.4. Features Supported With ForgeRock Access Management

This section describes the IG features that are supported with AM:

Features Supported With AM
FeatureSupported in AM Version

AM password capture and replay, as described in "Getting Login Credentials From Access Management" in the Gateway Guide

OpenAM 13.5.x, and AM 5.0 and later versions

AM policy enforcement, as described in "Enforcing Policy Decisions and Supporting Session Upgrade" in the Gateway Guide

OpenAM 13.5.x, and AM 5.0 and later versions

OpenID Connect dynamic registration and discovery, as described in "Using OpenID Connect Discovery and Dynamic Client Registration" in the Gateway Guide

OpenAM 13.5.x, and AM 5.0 and later versions

Token transformation, as described in "Transforming OpenID Connect ID Tokens Into SAML Assertions" in the Gateway Guide.

OpenAM 13.5.x, and AM 5.0 and later versions

User Managed Access 2.x, for IG 5.5 and later versions, as described in "Supporting UMA Resource Servers" in the Gateway Guide

AM 5.5

User Managed Access 1.x, for IG 5.0.x and earlier versions

AM 5.1.x and earlier versions

Single sign-on, as described in SingleSignOnFilter(5) in the Configuration Reference.

AM 5 and later


2.5. ForgeRock Access Management Policy Agents

When installing an AM policy agent in the same container as IG, use AM Java EE Policy Agent 3.5. Earlier versions might not shut down properly with the web application container.

Make sure that the container version is supported both for IG and the AM Java EE Policy Agent that you install alongside IG.

AM Java EE Policy Agent 3.5.1 and earlier versions do not support Tomcat 8.5.x or Jetty 9.

Chapter 3. Compatibility With Other Releases

This chapter describes major changes to existing functionality, deprecated functionality, and removed functionality.

3.1. Important Changes to Existing Functionality

IG 5.5.2

The following functionality is changed in IG 5.5.2:

  • There are no important changes in functionality in this release.

IG 5.5.1

The following functionality is changed in IG 5.5.1:

  • There are no important changes in functionality in this release.

IG 5.5

The following functionality is changed in IG 5.5:

Support for Java 7

Support for Java 7 has been removed. Before you update to IG 5.5, install the latest version of Java 8.

If you are using IG on Tomcat with SSL enabled, use OpenJDK 1.8.0_121 or later versions to prevent mismatch between client side ciphers and server side ciphers.

Default cookie name is IG_SESSIONID

Most web containers use JSESSIONID as the default cookie name. To prevent invalid session IDs when a protected application uses the same cookie name as the IG web container, IG now uses IG_SESSIONID as its default cookie name.

Configuration of Jetty for HTTPS

The way to configure HTTPS for Jetty has changed in Jetty 9.4.

For information about Jetty 9.4, see "Configuring Jetty For HTTPS (Server-Side)" in the Gateway Guide. For general information about Jetty and HTTPS, see http://www.eclipse.org/jetty/documentation/current/configuring-ssl.html#configuring-sslcontextfactory.

Support for "scope" in Dynamic Client Registration

As required by RFC 7591, OAuth 2.0 Dynamic Client Registration Protocol, the metadata property of OAuth2ClientFilter now supports scope.

Dynamic client registration with versions of AM earlier than 5.5 must use the scopes property.

Dynamic client registration with AM 5.5 can use the scopes or scope property.

For the option to dynamically register with a wider range of identity providers, you can use both scope and scopes at the same time.

3.2. Deprecated Functionality

The following functionality is deprecated in IG 5.5. Deprecation is defined in "ForgeRock Product Interface Stability" in the Configuration Reference.

IG 5.5.2
  • No functionality has been deprecated in this release, other than those identified in IG 5.5.

IG 5.5.1
  • No functionality has been deprecated in this release, other than those identified in IG 5.5.

IG 5.5
HeapClientRegistrationRepository

The class HeapClientRegistrationRepository is deprecated and will be removed in a future release. Declare client registrations in the registrations attribute of OAuth2ClientFilter.

Deprecated Configuration Settings
Configuration Object Deprecated Settings Newer Evolving Settings
OAuth2ResourceServerFilter cacheExpiration (deprecated in IG 5.5.1, and the values of zero and unlimited are not supported)

Replaced by cache and its sub-properties enabled, defaultTimeout, and maxTimeout.

If cacheExpiration is configured and cache is not configured, the cache is enabled and the value of cacheExpiration is used as maxTimeout.

The following values for cacheExpiration, supported in previous releases, are not supported in this release: zero, unlimited.

For more information, see OAuth2ResourceServerFilter(5) in the Configuration Reference.

OAuth2ResourceServerFilter tokenInfoEndpoint and providerHandler

Replaced by configuration properties of OpenAmAccessTokenResolver, TokenIntrospectionAccessTokenResolver, and ScriptableAccessTokenResolver.

For more information, see OAuth2ResourceServerFilter(5) in the Configuration Reference.

OAuth2ClientFilter tokenEndpointUseBasicAuth

Replaced by tokenEndpointAuthMethod.

"tokenEndpointAuthMethod": "client_secret_post" is equivalent to "tokenEndpointUseBasicAuth": false

"tokenEndpointAuthMethod": "client_secret_basic" is equivalent to "tokenEndpointUseBasicAuth": true


3.3. Removed Functionality

The following functionality is removed in IG 5.5. Removed is defined in "ForgeRock Product Interface Stability" in the Configuration Reference.

IG 5.5.2
  • No features or functionality have been removed in this release.

IG 5.5.1
  • No features or functionality have been removed in this release.

IG 5.5
Support for UMA 1

Support for UMA 1.x is removed in this release. Features and functionality have been upgraded to support new UMA standards.

Finalize Method Removed for HTTP messages

To reduce memory consumption, the finalize() method has been removed for HTTP messages (requests and responses). Consequently, requests are not automatically closed at garbage collection time.

Consider the following compatibility points:

  • After creating a new request object, you must now explicitly close it after use. For example, the following Java code was used in the previous release:

    ThrottlingRate rate = datasource.lookup(new RootContext(), new Request()).get();

    In this release, the equivalent Java code includes a final close operation:

    ThrottlingRate rate = datasource.lookup(new RootContext(), request)
           .thenAlways(request::close)
           .get();

  • In scripts, the client binding automatically closes the request that is provided as a parameter. Therefore, it is not necessary to manually close the request for scripts.

    After the request is automatically closed, the request entity is empty and can't be accessed. Response callbacks that try to access the request entity will fail.

    You can workaround this behavior in the following ways:

    • Keep the request open by using the client.sendNoClose() method instead of client.send(). This method to prevents closure of requests after send. If you use this method, remember to manually close the request.

    • Access the request entity before the request is closed, for example by including the request.entity.string assignment before calling the client.send() with the request.

Removed Configuration Settings
Configuration Object Removed Settings Newer Evolving Settings
UmaService clientId and clientSecret Not replaced. IG uses the PAT to create an UMA resource.For information, see "Supporting UMA Resource Servers" in the Gateway Guide and UmaService(5) in the Configuration Reference.


Chapter 4. Fixes, Limitations, and Known Issues

IG issues are tracked at https://bugster.forgerock.org/jira/browse/OPENIG. This chapter covers the status of key issues and limitations at this release.

4.1. Key Fixes

Key Fixes in IG 5.5.2

The following important issues have been fixed in IG 5.5.2:

Key Fixes in IG 5.5.1

The following important issues have been fixed in IG 5.5.1:

  • OPENIG-3256: Getting user_info on google fails because of returned different scopes than expected

  • OPENIG-3226: StaticFilterRequest: request leak

  • OPENIG-3219: When using scan feature in logback.xml the ig.instance.dir property is lost on reload

  • OPENIG-3187: Backport httpOnly change in HTTP Session cookie to IG 5.5.x

  • OPENIG-3159: Backport httpOnly change in JWT Session cookie to IG 5.5.x

  • OPENIG-2571: OAuth2ResourceServerFilter requireHttps=true applies to rebased request URI

  • OPENIG-2243: AM 6 default CSRF Protection switch breaks Policy Enforcement Filter

  • OPENIG-2004: OAuth2ResourceServerFilter cache configuration can lead to unexpected results if tokens expire early

Key Fixes in IG 5.5

The following important issues have been fixed in IG 5.5:

  • OPENIG-1876: SingleSignOnFilter throws NullPointerException if cookieName config item is not provided

  • OPENIG-1674: UMA examples might not work with Chrome and Safari

  • OPENIG-1152: Facebook Social Authentication not working when OpenAM is proxied behind OpenIG

  • OPENIG-1924: Investigate removing finalize() method implementation from CHF classes

4.2. Limitations

IG 5.5.2
  • OPENIG-221: Cannot specify which certificate to present to server if server requires mutual authentication in https

  • OPENIG-234: Federation doesn't work if we used incomplete user in IDP

  • OPENIG-291: Class cast exception when using SAML federation & policy agent together

  • OPENIG-458: CookieFilter is not JwtSession compatible

  • OPENIG-813: auditService : fileRotation may overwrite existing audit file

  • OPENIG-1557: UI: Unable to deploy route when custom router is configured

  • OPENIG-3273: Persists UMA Shares

  • OPENIG-3274: IG Scripts Can Access Anything in Their Environment

  • OPENIG-3275: SamlFederationHandler Doesn't Support Filtering

IG 5.5.1
  • There are no limitations in functionality in this release.

IG 5.5

The following important limitations are included in this release:

Persists UMA Shares (OPENIG-3273)

Shared resources cannot be persisted when IG restarts. They must be shared each time that IG restarts. For more information, see "Supporting UMA Resource Servers" in the Gateway Guide.

Cannot Use Custom config.json in IG Studio (OPENIG-1557)

When a customized config.json is configured in IG Studio, IG Studio cannot deploy routes.

PolicyEnforcementFilter Cache Can Become Outdated

The PolicyEnforcementFilter can keep policy decisions in the cache after a user has logged out and the session has become invalid. Because the PolicyEnforcementFilter does not listen to AM notifications, it is not aware that a user has logged out, and is therefore not aware that the policy decision should be evicted from the cache.

Log File of Audit Events Can be Overwritten (OPENIG-813)

The log file of audit events can be overwritten when the log file is rotated.

When CsvAuditEventHandler is used to log audit events, the log file is overwritten if it is rotated before the file suffix, rotationFileSuffix, changes. By default, rotationFileSuffix is defined as a date in the format _yyyy-MM-dd.

Log files are rotated when one of the following limits is reached: maxFileSize, rotationInterval, or rotationTimes.

Set the log rotation parameters so that the log is not likely to rotate before rotationFileSuffix changes.

For Mutual Authentication in HTTPS Cannot Specify Which Certificate to Present (OPENIG-221)

IG can check server certificates for HTTPS. However, for mutual authentication, the client certificate must be the first certificate in the KeyStore.

IG Scripts Can Access Anything in Their Environment (OPENIG-3274)

IG scripts are not sandboxed, but instead have access to anything in their environment. You must make sure that the scripts that IG loads are safe.

SamlFederationHandler Doesn't Support Filtering (OPENIG-3275)

The SamlFederationHandler does not support filtering. Do not use a SamlFederationHandler as the handler for a Chain.

More generally, do not use this handler when its use depends on something in the response. The response can be handled independently of IG, and can be null when control returns to IG. For example, do not use this handler in a SequenceHandler where the postcondition depends on the response.

4.3. Known Issues

IG 5.5.2
  • OPENIG-659: CryptoHeaderFilter - error on handling header value with incorrect length

  • OPENIG-3221: OpenIG is decoding special character ' while sending to the backend which is causing issues

  • OPENIG-3403: ContentTypeHeader quoted directives should be maintained

IG 5.5.1
  • OPENIG-3221: OpenIG is decoding special character ' while sending to the backend which is causing issues

  • OPENIG-3113: Not possible to use token substitutions within a monitor decorator of a Route

IG 5.5
  • OPENIG-2004: OAuth2ResourceServerFilter cache configuration can lead to unexpected results if tokens expire early

  • OPENIG-1628: Script update referenced in route, not taken into account

  • OPENIG-1557: UI: Unable to deploy route when custom router is configured

  • OPENIG-1325: Cannot specify realm in UmaService

  • OPENIG-816: The UmaResourceServerFilter returns with wrong as_uri

  • OPENIG-813: auditService : fileRotation may overwrite existing audit file

  • OPENIG-659: CryptoHeaderFilter - error on handling header value with incorrect length

  • OPENIG-458: CookieFilter is not JwtSession compatible

  • OPENIG-291: Class cast exception when using SAML federation & policy agent together

  • OPENIG-234: Federation doesn't work if we used incomplete user in IDP

  • OPENIG-221: Cannot specify which certificate to present to server if server requires mutual authentication in https

  • OPENAM-9112: Audit logging outputs errors in debug log under high load

Chapter 5. Documentation Changes

The following table tracks changes to the documentation set following the release of IG 5.5:

Documentation Change Log
DateDescription
2020-04-15

Minor correction in routes for SAML with multiple service providers.

2019-11-21

Release of IG 5.5.2, maintenance release.

2019-05-28

Minor correction in SingleSignOnFilter.

2018-12-28

Release of IG 5.5.1, maintenance release.

2018-01-30

Noted that cached policy decisions remain in the cache even after a user logs out of OpenAM. For information, see PolicyEnforcementFilter(5) in the Configuration Reference.

2017-10-31

Release of IG 5.5:


Chapter 6. Getting Support

This chapter includes information and resources for IG and ForgeRock support.

6.1. Accessing Documentation Online

ForgeRock publishes comprehensive documentation online:

  • The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

    While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

  • ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

6.2. How to Report Problems or Provide Feedback

If you find issues or reproducible bugs, report them in https://bugster.forgerock.org.

When requesting help with a problem, include the following information:

  • Description of the problem, including when the problem occurs and its impact on your operation

  • Description of the environment, including the following information:

    • Machine type

    • Operating system and version

    • Web server or container and version

    • Java version

    • Patches or other software that might affect the problem

  • Steps to reproduce the problem

  • Relevant access and error logs, stack traces, and core dumps

6.3. Getting Support and Contacting ForgeRock

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details on ForgeRock's support offering, including support plans and service level agreements (SLAs), visit https://www.forgerock.com/support.

Read a different version of :