Notes covering OpenIG prerequisites, fixes, known issues. OpenIG provides a high-performance reverse proxy server with specialized session management and credential replay functionality.

Chapter 1. What's New in OpenIG

Before you install OpenIG or update your existing OpenIG installation, read these release notes.

1.1. What's New in OpenIG 3.1.1

Important

OpenIG 3.1.1 is a maintenance release that resolves a number of issues. It is recommended that you update to this release to take advantage of important functional fixes. ForgeRock customers can contact support for help and further information.

This maintenance release introduces the following improvement:

OpenIG now provides an array(strings...) function (OPENIG-474).

The array() function returns an array given a series of strings. This function is useful when constructing a string array argument to pass to the join() function as in the following example expression that joins the first values of two request headers with a space:

${join(array(exchange.request.headers['part_1'][0],
             exchange.request.headers['part_2'][0], ' ')}
  

1.2. What's New in OpenIG 3.1.0

OpenIG 3.1.0 fixes a number of issues, and provides the following additional features.

  • OpenIG can now store session information in encrypted JSON Web Token (JWT) cookies on the user-agent (OPENIG-224, OPENIG-278). By default, OpenIG continues to back session information with HttpSession from the container where OpenIG runs.

    With this change, you can specify the session storage at the global level, or in a particular route configuration. For details, see JwtSession in the Reference and Setting Up Keys For JWT Encryption in the Gateway Guide.

  • OpenIG now allows you to inline configuration objects (OPENIG-311), to omit "config" fields when all values are optional (OPENIG-300), to omit the "objects" field from the "heap" (OPENIG-380), and even to omit the "heap" when it is empty or would only contain a single handler (OPENIG-329).

    When you bring an object inline, you no longer need to specify the "name".

    For example, suppose your former config.json file looks like this:

    {
        "heap": {
            "objects": [
                {
                    "name": "Chain",
                    "type": "Chain",
                    "config": {
                        "filters": [
                            "ReplaceHostFilter"
                        ],
                        "handler": "Router"
                    }
                },
                {
                    "name": "ReplaceHostFilter",
                    "type": "HeaderFilter",
                    "config": {
                        "messageType": "REQUEST",
                        "remove": [
                            "host"
                        ],
                        "add": {
                            "host": [
                                "example.com"
                            ]
                        }
                    }
                },
                {
                    "name": "Router",
                    "type": "Router",
                    "config": {}
                }
            ]
        },
        "handler": "Chain"
    }
        

    OpenIG now lets you rewrite the config.json file like this:

    {
        "handler": {
            "type": "Chain",
            "config": {
                "filters": [
                    {
                        "type": "HeaderFilter",
                        "config": {
                            "messageType": "REQUEST",
                            "remove": [
                                "host"
                            ],
                            "add": {
                                "host": [
                                    "example.com"
                                ]
                            }
                        }
                    }
                ],
                "handler": {
                    "type": "Router"
                }
            }
        }
    }
        

    Examples in the documentation now use streamlined configurations where it makes sense.

  • OpenIG now supports object decorators (OPENIG-340). Decorators allow you to define heap objects that decorate other objects, adding the new behavior that the decorator provides.

    OpenIG provides the following decorators out of the box.

    • A CaptureDecorator that extends what the CaptureFilter could do to capture requests, responses, and exchange data on any decorated object (OPENIG-299, OPENIG-301)

    • A TimerDecorator that records times to process the exchange through any decorated object (OPENIG-352, OPENIG-353)

    • An AuditDecorator that allows you to audit operation for any decorated object.

    For detailed information about decorators, see the Reference on Decorators in the Reference.

  • OpenIG now provides a publish-and-subscribe audit framework and a sample monitoring handler that returns basic statistics (OPENIG-359, OPENIG-386). To learn more, start by reading the chapter about the OpenIG Audit Framework in the Gateway Guide.

  • OpenIG script configurations can now include arguments (OPENIG-240).

  • The OAuth2ClientFilter and OAuth2ResourceServerFilter now cache data to avoid unnecessarily calls to the provider (OPENIG-350).

  • OpenIG uses improved object names in log messages that make it easier to identify the source of the message (OPENIG-358, OPENIG-371).

  • The OpenIG Exchange now provides information about the client (OPENIG-333).

    For details see the Reference on ClientInfo in the Reference.

Chapter 2. Before You Install

This chapter covers requirements for running OpenIG software.

Tip

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

2.1. JDK Version

This release of OpenIG requires Java Development Kit 6, 7, or 8. ForgeRock recommends the most recent update to ensure you have the latest security fixes.

If you install an OpenAM policy agent in the same container as OpenIG, then you must use a Java release that is supported with the policy agent as well.

2.2. Web Application Containers

OpenIG runs in the following web application containers.

  • Apache Tomcat 7

  • Jetty 8 (8.1.13 or later)

You must deploy OpenIG to the root context of the container. Deployment in other context causes unexpected results, and cannot be supported.

OpenIG expressions depend on Unified Expression Language 2.2, which is available in containers that support Servlet 3.0 or later. Some expressions can lead to a java.lang.NoSuchMethodError in containers that support only Servlet 2.5 (and EL 2.1).

See the Guide to OpenIG section, Configuring Deployment Containers in the Gateway Guide, for details on setting up your web application container.

Chapter 3. Changes and Deprecated Functionality

This chapter covers both major changes to existing functionality, and also deprecated and removed functionality.

3.1. Important Changes to Existing Functionality

OpenIG 3.1 includes configuration changes compared to OpenIG 3.0.0. See Section 3.2, "Deprecated Functionality" for a list of configuration changes resulting in deprecation of earlier features.

3.2. Deprecated Functionality

This release deprecates the following configuration settings. Deprecation is defined in the Reference appendix on ForgeRock Product Interface Stability in the Reference.

Table 3.1. Configuration settings
Configuration Object Deprecated in the Reference Settings Newer Evolving in the Reference Settings
CaptureFilter in the Reference Entire object Use a CaptureDecorator in the Reference instead
gateway servlet in the Reference "handlerObject" New name: "handler"
Deprecated format: "heap": { "objects": [ configuration object, ... ] } New format: "heap": [ configuration object, ... ]
HttpClient in the Reference "keystore" Replaced by "keyManager", which takes one or more KeyManager in the Reference references
"truststore" Replaced by "trustManager", which takes one or more TrustManager in the Reference references
OAuth2ResourceServerFilter in the Reference "enforceHttps" New name: "requireHttps"
"httpHandler" New name: "providerHandler"
"requiredScopes" New name: "scopes"
RedirectFilter Entire object Use LocationHeaderFilter in the Reference instead
Route in the Reference Deprecated format: "heap": { "objects": [ configuration object, ... ] } New format: "heap": [ configuration object, ... ]

This release deprecates the following API classes, which are likely to be removed in a future release.

3.3. Removed Functionality

No functionality has been removed in this release.

Chapter 4. Fixes, Limitations, and Known Issues

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

4.1. Fixes

This section lists important fixes.

4.1.1. Key Fixes in OpenIG 3.1.1

The following issues were fixed in this release:

  • OPENIG-589: Backport CHF-52 - MutableUri doesn't preserve encoded values when updating a field value

  • OPENIG-587: OpenIG can not connect to TLSv1.2 (TLSv1.1) secured resources

  • OPENIG-503: Fix resource leak on route loading

  • OPENIG-491: Using groovy script embedded in json route doesn't work on windows

  • OPENIG-470: Connections are not released after modifying HttpClient connections pool size

  • OPENIG-454: Capture decorator impacts the entity returned in GET

  • OPENIG-426: Multiple Host header

  • OPENIG-315: POST JSON payload not delivered unless CaptureFilter used

4.1.2. Key Fixes in OpenIG 3.1.0

The following issues were fixed in this release:

  • OPENIG-370: Log output often includes irrelevant or duplicated information

  • OPENIG-368: OAuth2ClientFilter rebases client endpoint against possibly rebased request.uri

  • OPENIG-331: Moving a file in Routes may result in no route configured

  • OPENIG-325: Allow scripts and AssignmentFilters to update exchange.request.uri

  • OPENIG-312: Use Jackson for better messages about configuration errors in JSON

  • OPENIG-119: RedirectFilter should handle HTTP 301

  • OPENIG-85: SqlAttributesFilter throws SQLException: Invalid operation for forward only resultset

  • OPENIG-78: SqlAttributesFilter throws SQLException: Invalid column index

  • OPENIG-56: Temporary files leak

  • OPENIG-30: OpenIG to protect multiple apps at one location

4.2. Limitations

For HTTPS, OpenIG can check server certificates. However mutual authentication, where OpenIG presents its client certificate, is not supported if the client certificate is not the first certificate in the HttpClient key store.

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

When acting as an OpenID Connect 1.0 relying party, OpenIG does not support dynamic registration.

4.3. Known Issues

This section lists important issues that were not resolved at the time of release.

4.3.1. Known Issues in OpenIG 3.1.1

The following known issues remained open at the time this release became available:

  • OPENIG-647: SSL and JDK1.6 - handshake failures

  • OPENIG-322: Cannot access both an OpenAM (self-signed) and a Google HTTPS endpoint

  • OPENIG-290: Null pointer exception when capturing SAML federation response

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

4.3.2. Known Issues in OpenIG 3.1.0

The following known issues remained open at the time this release became available:

  • OPENIG-322: Cannot access both an OpenAM (self-signed) and a Google HTTPS endpoint

  • OPENIG-290: Null pointer exception when capturing SAML federation response

  • OPENIG-258: OpenIG doesn't shutdown properly when protected by a Tomcat J2EE agent

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

Chapter 5. Documentation Updates

The following table tracks changes to the documentation from the release of OpenIG 3.1.0:

Table 5.1. Documentation Change Log
DateDescription
2017-07-31

Refreshed formatting.

2015-09-18

Release of OpenIG 3.1.1. Updates to release notes.

2014-12-12

Initial release of OpenIG 3.1.0.


Chapter 6. How to Report Problems and Provide Feedback

If you have questions regarding OpenIG that are not answered by the documentation, there is a mailing list which can be found at https://lists.forgerock.org/mailman/listinfo/openig where you are likely to find an answer.

If you have found issues or reproducible bugs within OpenIG, 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

  • Machine type, operating system version, web container and version, Java version, and OpenIG release version, including any patches or other software that might be affecting the problem

  • Steps to reproduce the problem

  • Any relevant logs or stack traces

Chapter 7. Support

You can purchase OpenIG support, subscriptions and training courses from ForgeRock and from consulting partners around the world and in your area. To contact ForgeRock, send mail to info@forgerock.com. To find a partner in your area, see https://forgerock.com/.

Read a different version of :