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
OpenIG 3.0.0 fixes a number of issues, and provides the following additional features.
This release brings major improvements to the configuration model.
OpenIG now supports runtime configuration changes, with separate routes for separate applications ( OPENIG-73, OPENIG-97, OPENIG-204 ). For a tutorial on how to use routes, see Routing Tutorial in the Gateway Guide.
OpenIG now removes the Java EE Servlet and Servlet Filter objects to simplify configurations. The top-level configuration object now references a handler rather than a Servlet ( OPENIG-95 ).
OpenIG now supports the ability to change the location where configuration files are stored ( OPENIG-96, OPENIG-140 ).
OpenIG now supports OAuth 2.0 and OpenID Connect 1.0 ( OPENIG-176, OPENIG-195 ).
OpenIG can act as an OAuth 2.0 resource server on behalf of a server housing protected resources. For details and a tutorial demonstrating this capability see the chapter, Configuring OpenIG as an OAuth 2.0 Resource Server in the Gateway Guide.
OpenIG can act as an OAuth 2.0 client application, and as an OpenID Connect 1.0 relying party. For details and a tutorial demonstrating these capabilities see the chapter, Configuring OpenIG as an OAuth 2.0 Client in the Gateway Guide.
OpenIG now supports use of scripts to process and to handle the HTTP exchange ( OPENIG-66, OPENIG-72, OPENIG-80, OPENIG-90, OPENIG-92, OPENIG-235 ). Use the
ScriptableFilter
andScriptableHandler
objects to the configuration in order to hook scripts into exchange processing. At present Groovy is supported, but JavaScript is not. For examples using Groovy scripts for Filters and Handlers see the chapter, Scripting Filters & Handlers in the Gateway Guide.Scripting also adds support for working with LDAP servers ( OPENIG-81 ).
OpenIG now includes a default welcome page if no configuration is found ( OPENIG-202 ).
SAML 2.0 federation support is now integrated into the main OpenIG .war file ( OPENIG-94 ).
OpenIG SAML 2.0 federation now supports SP-initiated single logout and also supports single logout using the SOAP binding ( OPENIG-10, OPENIG-237 ).
OpenIG SAML 2.0 federation now supports an option to set AuthnContext in the OpenIG session ( OPENIG-9 ). You can also obtain OpenAM authentication level by including the
AuthLevel
attribute in the IDP or SP attribute mapping.OpenIG Expressions now support additional built-in functions, and use of system properties and environment variables.
Built-in functions to call within expressions now include
base64Encode(string)
,base64Decode(string)
,matchingGroups(string, pattern)
,read(filename)
,readProperties(filename)
,urlEncode(string)
, andurlDecode(string)
as described in the reference section, Functions in the Reference ( OPENIG-54, OPENIG-213 ).Expressions access system properties and environment variables as described in the reference section, Expressions in the Reference.
Expressions now also support Java Beans ( OPENIG-200 ).
OpenIG Expressions are now usable in more configuration fields ( OPENIG-12, OPENIG-211, OPENIG-232 ).
OpenIG now provides an HttpClient configuration object that lets you disable connection reuse when server does not support it, set socket and connection timeouts, choose how you verify host names in server certificates, and so forth ( OPENIG-12, OPENIG-38, OPENIG-203 ).
OpenIG now allows you to change URI components, rather than rewrite entire URIs ( OPENIG-70, OPENIG-243 ).
OpenIG now provides a RedirectFilter to rewrite Location headers returned as a result of a HTTP redirect ( OPENIG-35 ).
OpenIG StaticRequestFilter now lets you restore the original state of the request ( OPENIG-245 ).
OpenIG HttpBasicAuthFilter now lets users change their passwords during a session ( OPENIG-32 ).
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)
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 & Deprecated Functionality
This chapter covers both major changes to existing functionality, and also deprecated and removed functionality.
3.1. Major Changes to Existing Functionality
This release brings important new functionality and many changes to OpenIG.
If you are running older versions of OpenIG
you must at minimum modify both the location
and also the content of your config.json
file.
You must migrate the configuration by hand.
The configuration file location and configuration layout have changed.
By default, configuration files are now stored under
$HOME/.openig/config
and$HOME/.openig/SAML
on UNIX, Linux, and Mac OS X, and under%appdata%\OpenIG\config
and%appdata%\OpenIG\SAML
on Windows systems.For details the Guide to OpenIG section, Installing OpenIG in the Gateway Guide.
As described in that section, the base configuration directory can be changed and can even be set at run time. You must therefore take care to protect access to OpenIG, both by protecting access to the environment at startup time, and also by protecting access to configuration files at run time.
Notice that OpenIG configuration can be split across multiple files.
Usage for some configuration objects has changed. In particular, the top-level configuration object now references a Handler rather than a Servlet.
When migrating your configuration, review current usage in the OpenIG Reference.
OpenIG supports runtime configuration changes, as described in the Guide to OpenIG chapter, Routing Tutorial in the Gateway Guide.
Notice that you can turn off runtime configuration changes.
OpenIG configuration Expressions can depend on runtime settings, such as environment variables and system properties.
You must ensure that these settings are properly protected.
As SAML 2.0 federation support is now integrated into the main OpenIG .war file, the way of configuring dispatch to the Federation component has changed. For an example of how the configuration is handled now, see the Guide to OpenIG chapter, Tutorial For OpenIG Federation in the Gateway Guide, or read the example configuration file, Configuration for the Federation Tutorial in the Gateway Guide.
3.2. Deprecated Functionality
No functionality is deprecated in this release.
3.3. Removed Functionality
Custom Servlet and Servlet Filter integration now requires additional development.
For an example, see the org.forgerock.openig.handler.saml
package.
Chapter 4. Fixes, Limitations, & 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 release 3.0.0.
4.1. Fixes
The following issues were fixed in release 3.0.0.
OPENIG-76: Documentation is not clear about what the CryptoHeaderFilter can encrypt/decrypt
OPENIG-67: Shutdown problem when using Federation Gateway
OPENIG-62: StaticRequestFilter overrides the Content-Type header
OPENIG-59: Federation does not correctly handle XML signatures
OPENIG-51: SSL mutual auth fails because client certificate is not presented to server
OPENIG-49: Empty Expression string not handled correctly
OPENIG-36: Problems with Expression examples in the reference documentation
OPENIG-31: Cached HttpBasic authentication header can cause issues when a user changes password
OPENIG-29: Federation requires AssertionMapping settings, even though the mapping is optional
OPENIG-15: Expressions needed in HeaderFilter and need to support backslashes
OPENIG-8: OpenIG gateway removes Content-Length: 0
OPENIG-4: Boundary stripped off of multipart/form-data on POST operation
OPENIG-1: File upload over HTTPS fails
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
The following known issues remained open at the time release 3.0.0 became available.
OPENIG-258: OpenIG doesn't shutdown properly when protected by a Tomcat J2EE agent
OPENIG-221: Cannot specify which certificate to present to server if server requires mutual authentication in https
OPENIG-85: SqlAttributesFilter throws SQLException: Invalid operation for forward only resultset
OPENIG-78: SqlAttributesFilter throws SQLException: Invalid column index
OPENIG-69: OpenIG seems to remove the URI part of requests when using baseURI
OPENIG-56: Temporary files leak
Chapter 5. How to Report Problems & 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 6. 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 http://forgerock.com/partners/find-a-partner/.