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

Preface

ForgeRock Identity Platform™ is the only offering for access management, identity management, user-managed access, directory services, and an identity gateway, designed and built as a single, unified platform.

The platform includes the following components that extend what is available in open source projects to provide fully featured, enterprise-ready software:

  • ForgeRock Access Management (AM)

  • ForgeRock Identity Management (IDM)

  • ForgeRock Directory Services (DS)

  • ForgeRock Identity Gateway (IG)

Chapter 1. What's New in This Release

IG 5.5 provides many new features and improvements.

1.1. New Features

This release of IG 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 Section 2.1.4, "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.2. Product Improvements

This release of IG 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 Chapter 10, "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.

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.0.war

  • Web application for testing IG configurations, IG-sample-application-5.5.0.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 Section 2.1, "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:

Table 2.1. Features Supported With AM
FeatureSupported in AM Version

AM password capture and replay, as described in Chapter 4, "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 Chapter 5, "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 Section 8.8, "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 Chapter 9, "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, as described in Chapter 10, "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


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

This release of IG includes the following important change:

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 Section 2.1.3.2, "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

This section lists deprecated functionality. Deprecation is defined in Section A.2, "ForgeRock Product Interface Stability" in the Configuration Reference.

HeapClientRegistrationRepository

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

Table 3.1. Deprecated Configuration Settings
Configuration Object Deprecated Settings Newer Evolving Settings
OAuth2ResourceServerFilter tokenInfoEndpoint and providerHandler

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

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


3.3. Removed Functionality

This section lists removed functionality. Removed is defined in Section A.2, "ForgeRock Product Interface Stability" in the Configuration Reference.

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.

Table 3.2. 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 Chapter 10, "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

This release of IG fixes the following important issues:

  • 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

This release of IG includes the following limitations:

Support for UMA Is Experimental

IG provides experimental support for building a UMA resource server, with the capability and limitations described in Chapter 10, "Supporting UMA Resource Servers" in the Gateway Guide.

For IG Studio, Custom config.json Must Contain Main Router Named _router

IG Studio deploys and undeploys routes through a main router named _router, which is the name of the main router in the default configuration. If you use a custom config.json, make sure that it contains a main router named _router.

For information, see Section 11.4, "Creating Routes Through IG Studio " in the Gateway Guide.

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

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, Client Certificate Must Be First in KeyStore

For HTTPS, IG can check server certificates. However, mutual authentication, where IG presents its client certificate, is not supported if the client certificate is not the first certificate in the ClientHandler keystore.

IG Scripts Can Access Anything in Their Environment

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

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

This release of IG includes the following known issues:

  • 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

This release of IG includes the following change to the documentation:

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, classes 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, visit https://www.forgerock.com, or send an email to ForgeRock at info@forgerock.com.

Read a different version of :