This release of IG includes the following new features:

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 (SSE) and the support of very large files (bigger than 2 GB).

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

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.

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

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 whitelisted in AM are available.

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

Support for Cross-Domain Single Sign-On

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

For more information, see "About CDSSO Using the CrossDomainSingleSignOnFilter" in the Gateway Guide and CrossDomainSingleSignOnFilter(5) in the Configuration Reference.

Updated Monitoring

The Prometheus Scrape Endpoint and Forgerock 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.

For more information, see "Monitoring" in the Gateway Guide.

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. For a list of IG objects that can use AmService, see "Deprecated Configuration Settings".

For information, see AmService(5) in the Configuration Reference

This release of IG includes the following improvements:

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.

For more information, see "Getting Login Credentials From AM" in the Gateway Guide, and CapturedUserPasswordFilter(5) in the Configuration Reference.

Introduction of Session Token Cache

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

IG can now receive notifications from AM on session log out, or when an AM session is modified, closed, is 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.

For more information, see AmService(5) in the Configuration Reference and "Enable Websocket Notifications" in the Configuration Reference.

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.

For more information, see "Enable Websocket Notifications" in the Configuration Reference. For more information about Caffeine, see the GitHub entry, 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 an UMA sharing service is now configured by the wellKnownEndpoint property of UmaService instead of authorizationServerUri. authorizationServerUri has been removed.

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

Support for Additional Advice Types in PolicyEnforcementFilter

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

• AuthenticateToService

• AuthenticateToRealm

• AuthScheme

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

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.

For more information, see ClientHandler(5) in the Configuration Reference and ReverseProxyHandler(5) in the Configuration Reference.

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.

For more information, see Property Value Substitution in the Configuration Reference.

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.

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

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-6.0.0.war to root.war.

For more information, see "Installing and Starting IG" in the Getting Started Guide.

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 On Connection Failure

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 bootstrapping scenarios where IG depends on third-party services, IG can now pause the startup process until the required services are online (ex: OpenID Connect well-know configuration endpoint).

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

Studio

Studio has been updated to include the following features:

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.

Freeform Studio is offered as Technology Preview, as defined in "Release Levels and Interface Stability".

For more information and some pointers for getting started with Freeform Studio, see "Technology Preview of Freeform Studio" in the Getting Started Guide.

Configuration for TokenTransformationFilter

The TokenTransformationFilter can now be configured in Studio.

For an example configuration, see "To Set Up IG For Token Transformation" in the Gateway Guide.

Use of Arguments in Scripts

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

For an example configuration, see " Configuring a Scriptable Throttling Filter " in the Gateway Guide.

Audit Logging With JSON Audit Event Handler and ElasticSearch Audit Handler

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

For more information, see "Recording Audit Events in JSON" in the Gateway Guide.

Configuration for Stateless Sessions

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

For more information, see "To Create a Route With Advanced Options" in the Getting Started Guide and JwtSession(5) in the Configuration Reference.

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.

For more information, see  Compatibility update required in the "Route Status" in the Getting Started Guide.

Capture Message Context in Studio

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

For information, see "Capturing Log Messages for Routes" in the Gateway Guide

This release of IG includes the following important change:

Production Mode by Default

By default, after installation IG is now in production (immutable) mode instead of development (mutable) mode. To use Studio and manage routes through Common REST, you must switch to development mode.

For information about modes and switching to development mode, see "Switching Between Production Mode and Development Mode" in the Getting Started Guide.

Introduction of ReverseProxyHandler

The chain in routes created in Studio now ends with a ReverseProxyHandler instead of a ClientHandler.

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

PolicyEnforcementFilter Credentials Must Be Registered as Java Agent

It is now mandatory to register an AM Java agent in order to use the PolicyEnforcementFilter.

The tokens issued by AM for an agent have an unlimited lifetime (unless configured otherwise), and all appropriate permissions, making them a perfect fit for an application needing to ask for policy decisions.

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

ClientHandler Verifies the Hostname for Outgoing SSL Connections

By default, the ClientHandler now verifies the hostname for outgoing SSL connections. By default, in previous releases the hostname was not verified.

For more information, see the hostnameVerifier property in ClientHandler(5) in the Configuration Reference.

Route Filename, Name, and ID

The filename of a route cannot be default.json, and the route's name property and route ID cannot be default.

For more information, see " Creating and Editing Routes Through Common REST " in the Gateway Guide and Route(5) in the Configuration Reference.

Servlet 2.x Support Removed

This release supports servlet 3.x. Servlet 2.x is no longer supported.

Captured Entity Size Is Limited

By default, when the CaptureDecorator property captureEntity is true, up to 512 KB of an entity can be captured. Before this release, IG tried to capture the entire entity.

The CaptureDecorator property maxEntityLength has been added to limit the maximum size of captured entities, and so prevent excessive memory use or OutOfMemoryError. For information, see CaptureDecorator(5) in the Configuration Reference.

ApiProtectionFilter protects /openig/api

The default ApiProtectionFilter now protects the /openig/api endpoint. Before this release, it protected the /openig endpoint.

Plus (+) Not Allowed in Names

The plus character, +, is now a reserved character in names.

The + character is no longer allowed in object and route names.

Timestamp In Route Log Files Complies With ISO 8601

The timestamp in route logs now includes the date, and is compliant with ISO 8601. The following examples show the impact of this change on log parsing:

• An entry in the route log was previously in this format:

  10:57:12:158 | INFO  | openig.example.com-startStop-1  . . .

• The entry now appears in this format:

  2018-01-16T10:57:12,242Z | INFO  | openig.example.com-startStop-1  . . .

IG Route Monitoring Endpoint

The IG Route Monitoring Endpoint is deprecated in this release and will be removed in the next release. As a replacement, IG provides Prometheus Scrape Endpoint and Forgerock Common REST Monitoring Endpoint.

For more information, see "Prometheus Scrape Endpoint" in the Gateway Guide, and "Forgerock Common REST Monitoring Endpoint" in the Gateway Guide,

Support for .war File Delivery

The delivery of a .war file is deprecated in this release and may be removed in the next release.

Support AM Policy Agents

Support for the use of AM policy agents in password capture and replay is deprecated in this release.

By using CapturedUserPasswordFilter, you can get login credentials from AM without setting up an AM policy agent. For more information, see "Getting Login Credentials From AM" in the Gateway Guide, and CapturedUserPasswordFilter(5) in the Configuration Reference.

HeapClientRegistrationRepository

The class HeapClientRegistrationRepository is removed from this release. Declare client registrations in the registrations attribute of OAuth2ClientFilter.

Support for Jetty 8

Support for Jetty 8 has been removed in this release.

Use Jetty 9 instead.

This release of IG includes the following limitations:

systemProxy Can't Be Used With Proxy Requiring Username and Password

The ClientHandler and ReverseProxyHandler property systemProxy can't be used with a proxy that requires a username and password. Use the handler's proxy property instead.

For more information, see the agent property of ClientHandler(5) in the Configuration Reference and ReverseProxyHandler(5) in the Configuration Reference.

Fail To Receive AM WebSocket Notifications with Jetty

When IG runs on versions of Jetty from 9.3.x to 9.4.8, WebSocket notifications are not received correctly. To work around this issue, comment out the entry -module=websocket in Jetty's start.ini file.

For more information, see the agent property of AmService(5) in the Configuration Reference.

Support for UMA Is Experimental

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

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

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 "Creating Routes Through Studio " in the Gateway Guide.

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 or ReverseProxyHandler 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.

CookieFilter is not JwtSession compatible

The CookieFilter heap object stores a java.net.CookieManager reference in the session, so that cookies are linked to the HTTP session. This behavior is not compatible with the use of a JwtSession.

SAML v2.0 Federation does not work if the user defined mapping is incorrectly set

If the user defined mapping is incorrectly set, missing SAML assertions produce an infinite loop during authentication attempts.