This release of OpenIG includes the following new features:

OpenIG Studio

OpenIG Studio is a new tool to help you build and deploy your OpenIG configuration through a user interface.

Through OpenIG Studio, you can create routes to authenticate and authorize users' access to protected applications, and throttle the rate of requests.

For information, see Section 12.4, "Creating Routes Through OpenIG Studio " in the Gateway Guide.

Mutable and Immutable Modes

OpenIG now provides a development mode and a production mode to make it easy to develop and then secure your configuration:

• In development mode, by default all endpoints are exposed and accessible. This mode is also called mutable.

  In development mode, you can use the /routes endpoint to read, add, edit, delete, and list routes in the OpenIG configuration. For examples, see Section 12.3, " Creating and Editing Routes Through Common REST " in the Gateway Guide.

  Use development mode to evaluate or demo OpenIG, or to develop configurations on a single instance. Development mode is not suitable for production.

• In production mode, the /routes endpoint is not exposed or accessible, and other endpoints are exposed according to the configuration of the ApiProtectionFilter. If there is no ApiProtectionFilter, other endpoints are exposed only to the loopback address. This mode is also called immutable.

  After creating your configurations in development mode, switch to production mode to test OpenIG, to run OpenIG in pre-production or production, or to run multiple instances of OpenIG.

The default mode is development. For information about switching to production mode, see Section 3.8, "Making the Configuration Immutable" in the Gateway Guide.

Support for Step-up Authentication

Step-up authentication is now supported in the following ways:

• OpenIG can respond to authentication-level advice provided when a policy decision is denied.

• The PolicyEnforcementFilter has a new property failureHandler, which can be configured to recover and respond to advice provided when a policy decision is denied.

After a policy decision, OpenIG continues to process requests as follows:

• If the request is allowed, processing continues.

• If the request is denied with advice, OpenIG checks whether it can respond to the advice. If OpenIG can respond to the advice, it processes the advice.

• If the request is denied without advice, or if OpenIG cannot respond to the advice, OpenIG forwards the request to a failureHandler declared in the PolicyEnforcementFilter. If there is no failureHandler, OpenIG returns a 403 Forbidden.

• If an error occurs during the process, OpenIG returns 500 Internal Server Error.

For an example configuration for step-up authentication, see the failureHandler property of PolicyEnforcementFilter(5) in the Configuration Reference.

Support for Single Sign-On With OpenAM

The SingleSignOnFilter has been added to support authentication with OpenAM before processing requests. The filter tests for the presence and validity of an SSO token in the cookie header of a request. If the SSO token is not present, or if it is empty or invalid, the filter redirects the user agent to the OpenAM login page for authentication.

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

Configuration Parameters as Property Variables and Inherited Across the Router

Configuration parameters, such as host names, port numbers, and directories, can be declared as property variables in the OpenIG configuration or in an external JSON file. The variables can then be used in expressions in routes and in config.json to set the value of configuration parameters.

Properties can be inherited across the router, so a property defined in config.json can be used in any of the routes in the configuration.

Storing the configuration centrally and using variables for parameters that can be different for each installation makes it easier to deploy OpenIG in different environments without changing a single line in your route configuration.

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

Implicit Object openig Gives Access to Environment

When expressions are evaluated, they now access the environment through the implicit object openig.

For more information, see "Configuration and Runtime Expressions" in the Configuration Reference.

Chain of Filters

ChainOfFilters has been added to dispatch a request to an ordered list of filters that does not end with a handler. Use this filter to assemble a list of filters into a single filter that you can then use in different places in the configuration.

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

Conditional Filter

ConditionalFilter has been added to make it easy to use or skip a filter depending on whether a condition is met (OPENIG-1138).

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

Scriptable Filters and Handlers Support Multiline Scripts

In scriptable filters and handlers, the property "source" can now be written as a string or array of strings, to make it more readable. The route is valid JSON, and can be deployed as a file or as a CREST resource.

Before this release, a route with a property "source" that contained line breaks was invalid JSON, and was tolerated only when deployed as a file.

For an example of "source" written as an array of strings, see "Example of a Scriptable Throttling Policy" in the Configuration Reference.

Decorating Individual Uses of Named Filters and Handlers

When a named filter or handler is configured in config.json or in the heap, it can be used many times in the configuration. You can now use a delegate to decorate each use of a named filter or handler individually.

This new feature allows you to decorate a named filter or handler differently each time you use it in the configuration.

For more information, see Section 3.4, " Decorating Individual Uses of a Named Filter or Handler " in the Configuration Reference.

Audit Event Handlers

Support has been added for the JMS Audit Handler and JSON Audit Handler For information, see JmsAuditEventHandler(5) in the Configuration Reference and JsonAuditEventHandler(5) in the Configuration Reference.

API Descriptors

The following endpoints now serve API descriptors at runtime: ../info, ../router-name/routes, ../umaservice-name/share, and ../routeId/monitoring.

For information, see Section 1.10, "Understanding OpenIG APIs With API Descriptors" in the Gateway Guide.

REST Endpoint for Server and Build Information

The product version and build information for a running instance of OpenIG can now be retrieved from the /api/info endpoint. When OpenIG is set up as described in Chapter 2, "Getting Started" in the Gateway Guide, you can access the information at http://openig.example.com:8080/openig/api/info.

This release of OpenIG includes the following improvements:

Routes Reloaded Automatically Into the Configuration

When a route has been updated, by default it is reloaded automatically in the OpenIG configuration. Before this release, is was necessary to access the route to load it into the OpenIG configuration.

The scanning interval of Router can now be configured with a duration. Before this release, it could be configured only with an integer that defined a number of seconds.

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

Policy Enforcement Filter Cache Can Be Disabled

To force OpenIG to apply for a new policy decision for every request, you can now disable the cache in the PolicyEnforcementFilter.

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

Addition of a Domain for JWT Cookies

The property cookieDomain has been added to JwtSession.

When the domain is specified, a JWT cookie can be accessed from different hosts in that domain. When the domain is not specified, the JWT cookie can be accessed only from the host where the cookie was created.

The sharedSecret property specifies the key used to sign and verify JWTs. If this property is not specified, random data is generated as the key, and the OpenIG instance can verify only the sessions it has created.

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

Integer and Boolean Functions for Expressions

The following functions have been added for expressions: integer, boolean, fileToUrl, and pathToUrl.

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

Unit of Time for TimerDecorator Defined by Parameter

The property timeUnit has been added to TimerDecorator, to make it possible to define the unit of time used by the decorator.

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

Addition of µs to the Duration class

The unit µs has been added to the Duration class as an abbreviation for microseconds.

Home Page for the Sample Application

A mockup web application is provided for testing OpenIG configurations. A home page has been added to this sample application.

Requests can access the home page without the need log in to the sample application. For information, see Section 2.3, "Install the Sample Application" in the Gateway Guide.

This release of OpenIG includes the following important changes:

Update Required in Scripts that Authenticate to DS 5.0.0

DS 5.0.0 has been refactored and some APIs have changed:

• The org.forgerock.opendj.ldap.requests and org.forgerock.opendj.ldap.responses packages have been renamed to org.forgerock.opendj.ldap.messages

• The following methods and class names have been renamed for consistent use of camel case:

  • The DN class has been renamed to Dn

  • The ModifyDNRequest class has been renamed to ModifyDnRequest

  • The Requests.newModifyDNRequest() factory method has been renamed to Requests.newModifyDnRequest()

If OpenIG uses scripts to authenticate to DS 5.0.0, adapt the scripts according to the changes listed in the following tables:

Table 3.1. Static Imports

OpenDJ 3.5 and Earlier Releases	DS 5.0.0
org.forgerock.opendj.ldap.requests.Requests.newAddRequest	org.forgerock.opendj.ldap.messages.Requests.newAddRequest
org.forgerock.opendj.ldap.requests.Requests.newCompareRequest	org.forgerock.opendj.ldap.messages.Requests.newCompareRequest
org.forgerock.opendj.ldap.requests.Requests.newDeleteRequest	org.forgerock.opendj.ldap.messages.Requests.newDeleteRequest
org.forgerock.opendj.ldap.requests.Requests.newModifyDNRequest	org.forgerock.opendj.ldap.messages.Requests.newModifyDnRequest
org.forgerock.opendj.ldap.requests.Requests.newModifyRequest	org.forgerock.opendj.ldap.messages.Requests.newModifyRequest
org.forgerock.opendj.ldap.requests.Requests.newSearchRequest	org.forgerock.opendj.ldap.messages.Requests.newSearchRequest
org.forgerock.opendj.ldap.requests.Requests.newSimpleBindRequest	org.forgerock.opendj.ldap.messages.Requests.newSimpleBindRequest

Table 3.2. Other Imports

OpenDJ 3.5 and Earlier Releases	DS 5.0.0
import org.forgerock.opendj.ldap.DN;	import org.forgerock.opendj.ldap.Dn;
import org.forgerock.opendj.ldap.requests.AddRequest;	import org.forgerock.opendj.ldap.messages.AddRequest;
import org.forgerock.opendj.ldap.requests.BindRequest;	import org.forgerock.opendj.ldap.messages.BindRequest;
import org.forgerock.opendj.ldap.requests.CompareRequest;	import org.forgerock.opendj.ldap.messages.CompareRequest;
import org.forgerock.opendj.ldap.requests.DeleteRequest;	import org.forgerock.opendj.ldap.messages.DeleteRequest;
import org.forgerock.opendj.ldap.requests.ModifyDNRequest;	import org.forgerock.opendj.ldap.messages.ModifyDnRequest;
import org.forgerock.opendj.ldap.requests.ModifyRequest;	import org.forgerock.opendj.ldap.messages.ModifyRequest;
import org.forgerock.opendj.ldap.requests.Request;	import org.forgerock.opendj.ldap.messages.Request;
import org.forgerock.opendj.ldap.requests.SearchRequest;	import org.forgerock.opendj.ldap.messages.SearchRequest;
import org.forgerock.opendj.ldap.responses.BindResult;	import org.forgerock.opendj.ldap.messages.BindResult;
import org.forgerock.opendj.ldap.responses.CompareResult;	import org.forgerock.opendj.ldap.messages.CompareResult;
import org.forgerock.opendj.ldap.responses.Result;	import org.forgerock.opendj.ldap.messages.Result;
import org.forgerock.opendj.ldap.responses.SearchResultEntry;	import org.forgerock.opendj.ldap.messages.SearchResultEntry;
import org.forgerock.opendj.ldap.responses.SearchResultReference;	import org.forgerock.opendj.ldap.messages.SearchResultReference;

For an example script that authenticates against an LDAP server, see Section 14.4, "Scripting LDAP Authentication" in the Gateway Guide.

OpenIG Class Logger Replaced by SLF4J Class Logger

The OpenIG class Logger has been replaced by the SLF4J class Logger. The behavior of Groovy scripts that worked with the OpenIG class Logger can be affected. Review references to ConsoleLogSink, FileLogSink, and Slf4jLogSink from scripts used in the ScriptableFilter, ScriptableHandler, and ScriptableThrottlingPolicy.

For information about the SLF4J class Logger, see http://www.slf4j.org/apidocs/org/slf4j/Logger.html.

Configuration File for Administrative Requests

The file $HOME/.openig/config/admin.json has been added as the entry point for administrative requests. The entry point for gateway requests is still $HOME/.openig/config/config.json.

Before this release the ApiProtectionFilter was configured in config.json. It is now configured in admin.json

For information, see AdminHttpApplication(5) in the Configuration Reference, and GatewayHttpApplication(5) in the Configuration Reference.

In Groovy scripts, the Response constructor for a new Response object requires a Status

Before this release, constructions like the following were allowed:

Response response = new Response
response.status = Status.OK

In this release, that construction must be written as follows:

Response response = new Response(Status.OK)

Attributes of a SAML assertion can contain one or more values

The attributes of a SAML assertion can contain one or more values. Before this release, only the first value was made available. Now, all values are made available as a list of strings. Even if an attribute contains a single value, it is made available as a list of strings.

Update scripts and expressions that use SAML assertions so that they refer to the correct value in the list of strings. Even if the list contains only one value, include the braces [ ] to refer to that value. For example, use the following code to refer to the value of the username and password attributes of a SAML assertion:

"form": {
  "username": [
    "${session.username[0]}"
  ],
  "password": [
    "${session.password[0]}"
  ]
}

Changes to the PolicyEnforcementFilter

The following changes have been made in the PolicyEnforcementFilter:

• By default, policy decisions are not cached.

• Policy decisions that contain advices are never cached.

• The cache subproperty of cacheMaxExpiration has been removed.

  To configure caching for policy decisions, use the new cache property, with subproperties enabled, defaultTimeout, and maxTimeout. For an example, see the cache property of PolicyEnforcementFilter(5) in the Configuration Reference.

• The target property has been removed. Before this release, attributes and advices returned by a policy decision were stored in the location defined by the target attribute. They are now stored in the context ${contexts.policyDecision}.

Token Transformation Filter Property target Removed

The TokenTransformationFilter property target has been removed. Before this release, SAML 2.0 assertions were made available to downstream handlers through the location defined by the target attribute. They are now made available through the context ${contexts.sts}.

Session Cookies Created by Default When Using JwtSession

By default, cookies created when using JwtSession are now session cookies. OpenIG does not specify an expiry date for session cookies. The user-agent is responsible for deleting them when it considers that a session is finished (for example, when the browser is closed).

Before this release, cookies created when using JwtSession were always persistent cookies, with an expiry date based on sessionTimeout.

JwtSession has a new property, persistentCookie. Set this property to true to create persistent cookies when using JwtSession, which is the behavior before this release.

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

Failure Handling in OAuth2ClientFilter

When the OAuth 2.0 Resource Server denies access to a resource, the OAuth2ClientFilter can invoke the failure handler only if the error response contains a WWW-Authenticate header (meaning that there was a problem with the OAuth 2.0 exchange). Before this release, the filter invoked the failure handler for a wider range of errors.

If the value of the WWW-Authenticate header is invalid_token, the OAuth2ClientFilter first tries to refresh the token and replay the request. Before this release, the filter tried to refresh the token only when the response also had a 401 Unauthorized.

temporaryStorage is no longer an implicit property of a heap object

The property temporaryStorage is no longer an implicit property of a heap object. In the ClientHandler, temporaryStorage is a new configuration property. For information, see ClientHandler(5) in the Configuration Reference.

OAuth2ResourceServerFilter uses ForgeRockClientHandler as the default handler.

To facilitate issue tracking, the default handler for the OAuth2ResourceServerFilter property providerHandler is now the ForgeRockClientHandler. Before this release, it was the default ClientHandler. For information, see OAuth2ResourceServerFilter(5) in the Configuration Reference.

Arguments of a scriptable object cannot access runtime properties

The values for script arguments that are defined as configuration expressions cannot refer to context, request, contexts, session, or attributes.

Instead, the variables can be accessed directly within the script. For maintenance, it easier to maintain the variables inside the script, with their usage context, instead of decoupling them from the script.

The arguments are evaluated once, at configuration time, instead of at every request.

This release of OpenIG includes the following limitations:

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

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

PolicyEnforcementFilter Cache Can Become Outdated

The PolicyEnforcementFilter can keep policy decisions in the cache after a user has logged out and the session has become invalid. Because the PolicyEnforcementFilter does not listen to OpenAM notifications, it is not aware that a user has logged out, and is therefore not aware that the policy decision should be evicted from the cache.

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, 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 Can Access Anything in Their Environment

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.

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