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 4.5 provides many new features and improvements.

1.1. New Features

This release of OpenIG includes the following new capabilities:

Throttling Filter

The throttling filter has been extended to support different throttling rates (OPENIG-595).

OpenIG can now apply different throttling rates to different groups of requests. Before this release, only one throttling rate could be applied. Requests are categorized into groups by the evaluation of an expression. The throttling rate for each request group can be mapped in memory or configured by a script.

For more information, see Chapter 16, "Throttling the Rate of Requests to a Protected Application" in the Gateway Guide and ThrottlingFilter(5) in the Configuration Reference.

SLF4J Logging in OpenIG

The Simple Logging Facade for Java (SLF4J) is now provided in OpenIG, allowing you to define different logging behavior for routes and third-party dependencies (OPENIG-920).

Before this release, some but not all log messages from SLF4J loggers were included with the default OpenIG log sink entries. To access all messages from SLF4J loggers, in config.json define the default LogSink as type Slf4jLogSink.

{
  "name": "LogSink",
  "type": "Slf4jLogSink",
   "config": {
    "base": "com.example.app"
  }
}
     

For more information, see Chapter 17, "Logging Events in OpenIG" in the Gateway Guide and Slf4jLogSink(5) in the Configuration Reference.

OAuth 2.0 Common Resource Server Filter

OpenIG now uses the OAuth 2.0 Common Resource Server filter (OPENIG-864).

Previously, access tokens for OAuth2ResourceServerFilter were stored in the "target" attribute. This attribute has been removed. Access tokens are now stored in a dedicated context and accessed through ${contexts.oauth2.accessToken}.

For more information, see Chapter 8, "OpenIG As an OAuth 2.0 Resource Server" in the Gateway Guide and OAuth2ResourceServerFilter(5) in the Configuration Reference.

Elasticsearch Audit Event Handler

The audit service now supports an ElasticsearchAuditEventHandler to log audit events in the Elasticsearch search and analytics engine.

For more information, see Chapter 15, "Auditing and Monitoring OpenIG" in the Gateway Guide and ElasticsearchAuditEventHandler(5) in the Configuration Reference.

Condition Enforcement Filter

A condition enforcement filter is now available to verify that a specified condition is met before the chain of execution is continued (OPENIG-880).

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

Class Import for Groovy Scripts

The following classes are imported automatically for Groovy scripts:

  • org.forgerock.http.Client

  • org.forgerock.http.Filter

  • org.forgerock.http.Handler

  • org.forgerock.http.filter.throttling.ThrottlingRate

  • org.forgerock.http.util.Uris

  • org.forgerock.util.AsyncFunction

  • org.forgerock.util.Function

  • org.forgerock.util.promise.NeverThrowsException

  • org.forgerock.util.promise.Promise

  • org.forgerock.services.context.Context

  • org.forgerock.http.protocol.*

It is no longer necessary to include import statements for these classes in Groovy scripts (OPENIG-963).

For more information, see ScriptableFilter(5) in the Configuration Reference and ScriptableHandler(5) in the Configuration Reference.

Scheduled Executor Service

OpenIG now provides a scheduled executor service that can be declared and configured in the heap, and shared by downstream components, such as filters and handlers, that use an executor service. Previously, each filter and handler created its own executor service (OPENIG-178).

This executor service simplifies configuration and makes it possible for components to share resources. You can configure the number of threads in the executor service and how the executor service is stopped.

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

1.2. Product Improvements

This release of OpenIG includes the following enhancements:

Improved Performance of the PolicyEnforcementFilter

Internal refactoring of the OpenIG policy enforcement filter has significantly improved performance (OPENIG-1013).

Before this release, the number of SSO tokens required by the policy enforcement filter was proportional to the number of connected user agents. From this release, a single token is requested the first time the policy enforcement filter is called, and then that same token is used for all policy evaluation requests. The token is automatically refreshed when necessary.

The refactoring has resulted in the following improvements:

  • Reduced memory usage on OpenAM and OpenIG - there are fewer SSO sessions.

  • Increased speed - OpenIG performs fewer HTTP calls to get SSO tokens, and therefore spends less time waiting for tokens.

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

Asynchronous Processing of Filters and Handlers

All of the filters and handlers in OpenIG have been refactored for fully asynchronous HTTP message processing (OPENIG-865).

Configuration Settings Can Be Defined As Expressions

Filters, handlers, and other objects whose configuration settings require strings, integers, or booleans, can now be configured by expressions (OPENIG-397).

This improvement allows you to change configuration settings by changing the value of a system property or environment variable, and then restarting OpenIG or reloading the route. You can change configuration settings without changing the configuration file.

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

Failures in OAuth2ClientFilter Are Diverted to a Failure Handler

All client failures are rerouted to a failure handler. Before this release, a 500 Internal Server Error was returned. The failure object in the target has an additional field called exception, providing the cause of failure (OPENIG-981).

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

Support for Environment and Subject/Claims in Policy Enforcement

The PolicyEnforcementFilter now provides support to specify a policy environment and to specify a subject by claims (OPENIG-836).

The circumstances under which a policy applies can now be configured. For example, environment conditions can specify that the policy applies only during working hours or only when accessing from a specific IP address. For this improvement, the "environment" attribute has been added to the PolicyEnforcementFilter.

Subjects can now be specified by JWT claims. For this improvement, the "claimsSubject" attribute has been added to the PolicyEnforcementFilter.

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

Attributes and Advices Returned With Policy Decisions

The PolicyEnforcementFilter now exposes attributes and advices returned by the policy decision (OPENIG-824).

For this improvement, the "target" attribute has been added to the PolicyEnforcementFilter. For more information, see PolicyEnforcementFilter(5) in the Configuration Reference.

Logs at Error Level on OAuth2ClientFilter

The OAuth2ClientFilter now logs at the error level instead of the warning level (OPENIG-945).

Error Messages Improved for Evaluation of Expressions

More warning and error logs are now available for the evaluation or assignation of expressions (OPENIG-451).

The following information is logged:

  • Missing bean properties

  • Out-of-bound index in lists

  • Movement to an unmodifiable collection

  • Exception during evaluation

  • Unexpected result type

  • Any function failure

1.3. Security Advisories

Forgerock issues security advisories in collaboration with our customers and the open source community to address any security vulnerabilities transparently and rapidly. ForgeRock's security advisory policy governs the process on how security issues are submitted, received, and evaluated, as well as the timeline for the issuance of security advisories and patches.

For more information on ForgeRock's security advisory policy, click the following link: http://www.forgerock.com/services/security-policy/.

The following security advisory is about vulnerabilities in this release:

Chapter 2. Before You Install OpenIG Software

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 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 or 8

  • Jetty 8 (8.1.13 or later) or 9

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

OpenIG requires Servlet 3.0 or later.

For details on setting up your web application container see Section 3.1, "Configuring Deployment Containers" in the Gateway Guide.

2.3. OpenAM Features

When using OpenIG with OpenAM, the following features are supported with OpenAM 13 or later:

2.4. OpenAM Policy Agents

When installing an OpenAM policy agent in the same container as OpenIG, use an OpenAM Java EE policy agent version 3.5 or later. Earlier versions of OpenAM policy agents might not shut down properly with the web application container (OPENIG-258).

Make sure that the container version is supported both for OpenIG and for the OpenAM Java EE policy agent that you install alongside OpenIG.

Chapter 3. OpenIG Compatibility

This chapter describes major changes to existing functionality, deprecated functionality, and removed functionality.

3.1. Important Changes to Existing Functionality

This release brings the following important changes to OpenIG:

  • The policy enforcement filter returns different HTTP status codes (OPENIG-871).

    Before this release, the policy enforcement filter returned 401 Unauthorized if a request was denied by OpenAM. From this release, the policy enforcement filter returns 403 Forbidden if a request is denied, or 500 Internal Server Error if an error occurs during the process.

  • In the PolicyEnforcementFilter, the policiesHandler is replaced by amHandler, and the default amHandler is ForgeRockClientHandler (OPENIG-1014).

  • In the TokenTransformationFilter, amHandler is now optional. If it is not defined, the default value ForgeRockClientHandler is used.

  • In OpenID Connect (OAuth2ClientFilter), the goto parameter of the login/discovery endpoints is no longer decoded twice (OPENIG-847).

    When OAuth2ClientFilter is configured to work with multiple providers, the user is directed to a login handler page, known as a NASCAR page, to choose a provider. The NASCAR page is defined by the loginHandler parameter of OAuth2ClientFilter.

    Do not URL-encode the goto query parameter in the NASCAR page. For example, replace the first handler with the second.

    {
        "name": "NascarPage",
        "type": "StaticResponseHandler",
        "config": {
            "status": 200,
            "entity": "<html><p><a
                       href='/openid/login?registration=openam&goto=${urlEncode(contexts.router.originalUri)}'
                       >OpenAM Login</a></p>
                       </html>"
        }
    }
         
        
    {
        "name": "NascarPage",
        "type": "StaticResponseHandler",
        "config": {
            "status": 200,
            "entity": "<html><p><a
                       href='/openid/login?registration=openam&goto=${contexts.router.originalUri}'
                       >OpenAM Login</a></p>
                       </html>"
        }
    }
         
        
  • For OAuth 2.0 and OpenID Connect deployments, the loginHandler parameter of the OAuth2ClientFilter is now required when there are zero or multiple client registrations. It is optional when there is one client registration (OPENIG-954).

    The registration parameter has been deprecated and replaced by registrations, which is an array of client registrations. Before a client registration can be used by the OAuth2ClientFilter filter, it must be declared in the registrations parameter.

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

  • When OpenIG fails to start up, a 500 Internal Server Error is sent to the user agent, and an error is written to the logs. Before this release, the error page of the web container was displayed (OPENIG-1009).

3.2. Deprecated Functionality

Deprecation is defined in Section A.2, "ForgeRock Product Interface Stability" in the Configuration Reference.

  • The following log sink classes are deprecated in this release: Logger, ConsoleLogSink, FileLogSink, Slf4jLogSink. The Simple Logging Facade for Java (SLF4J) is now provided in OpenIG, allowing you to define different logging behavior for routes and third-party dependencies.

  • The AuditDecorator and CaptureDecorator deprecated in the previous release remain deprecated in this release.

Table 3.1. Deprecated Configuration Settings
Configuration Object Deprecated Settings Newer Evolving Settings
ThrottlingFilter partitionKey Replaced by requestGroupingPolicy.
OAuth2ClientFilter Deprecated parameter and format "registration": ClientRegistration reference. Replaced by "registrations": [ ClientRegistration reference(s) ].

loginHandler

Required when there are zero or multiple client registrations. Optional when there is one client registration.

PolicyEnforcementFilter

policiesHandler, using ClientHandler as default.

amHandler, using ForgeRockClientHandler as default.


For details on the new and updated configuration objects, see OAuth2ClientFilter(5) in the Configuration Reference, PolicyEnforcementFilter(5) in the Configuration Reference, Client(5) in the Configuration Reference, and ThrottlingFilter(5) in the Configuration Reference.

3.3. Removed Functionality

The class org.forgerock.openig.heap.NestedHeaplet has been removed in this release. The interface to extend instead is org.forgerock.openig.heap.GenericHeaplet (OPENIG-803).

The "target" attribute of the OAuth2ResourceServerFilter has been removed (OPENIG-864). Access tokens are now stored in a dedicated context and accessed through ${contexts.oauth2.accessToken}.

Table 3.2. Removed Configuration Settings
Configuration Object Deprecated Settings Newer Evolving Settings
OAuth2ClientFilter providerHandler N/A
providers Replaced by separate Issuer and ClientRegistration configuration objects.
redirect_uris List the redirect URIs in the dynamic client registration metadata.
scopes List the scopes in the dynamic client registration metadata.

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 release 4.5.

4.1. Key Fixes

The following important issues were fixed in this release:

  • OPENIG-1084: OAuth2ClientFilter heaplet should use a defensive copy

  • OPENIG-1012: OpenIDConnect : Thread remaining blocked in WAITING state on `unauthorized` response of application

  • OPENIG-1008: OpenIDConnect : context attributes are not updated when a refresh token is performed by OAuth2ClientFilter

  • OPENIG-933: Access token expiration in OAuth2ClientFilter still not handled in 4.0.0

  • OPENIG-871: Policy Enforcement Filter should return a 403 instead of a 401

  • OPENIG-847: goto URL in OIDC Nascar page does not need to be URL encoded

  • OPENIG-834: Single logout processing in SamlFederationHandler.serviceSPInitiatedSLO does not correctly pass the metaalias property

  • OPENIG-712: Issuer definition : supportedDomains doesn't lead to use of static clientRegistration

  • OPENIG-683: Too much information in response in case of error

  • OPENIG-555: OpenIG container doesn't stop properly, waiting for a promise

4.2. Limitations

The following limitations are present in this release:

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

    Workaround: Set the log rotation parameters so that the log is not likely to rotate before rotationFileSuffix changes.

  • 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 ClientHandler keystore.

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

  • 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 OpenIG, and can be null when control returns to OpenIG. For example, do not use this handler in a SequenceHandler where the postcondition depends on the response.

  • assertionMapping does not support multi-valued attributes (OPENIG-98).

    When using assertionMapping in the SamlFederationHandler to map a SAML assertion attribute value to a session attribute, only the first attribute value is saved in the session. If the SAML assertion attribute has multiple values, the other values are not saved in the session.

  • The route /openig and its subroutes are reserved for administration endpoints.

4.3. Known Issues

The following known issues remained open at the time of release:

  • OPENIG-910: ScriptableFilter : Get error `Cannot execute script` with groovy scripts previously working

  • 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-322: Cannot access both an OpenAM (self-signed) and a Google HTTPS endpoint

  • 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 chapter describes important changes made to the documentation set in this release.

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, use the ForgeRock website.

Read a different version of :