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.
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:
Date | Description |
---|---|
2018-01-25 |
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/.