OpenIG runs in the following web application containers:

• Apache Tomcat 7 or 8

• Jetty 8 (8.1.13 or later) or 9

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

• OpenAM policy enforcement, as described in Chapter 6, "OpenIG As an OpenAM Policy Enforcement Point" in the Gateway Guide

• OpenID Connect dynamic registration and discovery, as described in Section 9.7, "Using OpenID Connect Discovery and Dynamic Client Registration" in the Gateway Guide

• User Managed Access, as described in Chapter 10, "OpenIG As an UMA Resource Server" in the Gateway Guide

• All paths starting with /openig are now reserved for use by OpenIG for administrative use, and can no longer be matched by other route conditions.

  Resources exposed under /openig are only accessible to local client applications.

• OpenIG no longer provides an exchange object to model the HTTP exchange. The exchange object model has been replaced by a new model based on requests, responses, and contexts. Table 3.1, "Comparison Between Object Models" summarizes changes that affect configuration expressions and scripts.

  Table 3.1. Comparison Between Object Models

  Previous Model	Current Model
  exchange	Removed. Arbitrary properties must move to attributes.
  exchange.clientInfo	contexts.client
  exchange.originalUri	contexts.router.originalUri
  exchange.principal	Use contexts.client.remoteUser instead.
  exchange.request	request
  exchange.response	response
  exchange.response.reason	response.status.reasonPhrase
  exchange.response.status	response.status returns a Status object. See Status(5) in the Configuration Reference.
  exchange.session	session

  
  

  • As the response status is now represented by a Status object, the expression ${response.status} resolves to a status object rather than a status code. To get the response status code as an integer, use ${response.status.code}.

    In scripts, add import org.forgerock.http.protocol.Status and then use Status objects as in the following example:

    import org.forgerock.http.protocol.Status
    
    response.status = Status.OK            // 200
    response.status = Status.FORBIDDEN     // 403
          

    For details, see Status(5) in the Configuration Reference.

  • The exchange allowed arbitrary properties at the base level. The new model includes an attributes context instead. Add arbitrary properties to the map named attributes.

    For example, if an existing configuration targets an expression that defines a base-level property in the exchange, such as ${exchange.token}, edit the configuration to make the property one of the attributes instead, as in ${attributes.token}.

• A change in the way JWTs are represented has the effect that JwtSession cookies encrypted by earlier versions of OpenIG cannot be decrypted.

  After upgrade, OpenIG must renew users' JwtSession cookies. This is reflected with messages in the log, such as the following:

  • The JWT Session Cookie 'openig-jwt-session' could not be decrypted.

  • Cannot rebuild JWT Session from Cookie 'openig-jwt-session'

• Previously, when a router or dispatcher could not find a route or handler for a request, it threw a handler exception, resulting in an HTTP 500 Server Error message.

  OpenIG now generates a response instead, resulting in a proper HTTP 404 Not Found message.

• The following changes affect Groovy scripts called from ScriptableFilter and ScriptableHandler objects:

  • Groovy scripts must now return a Promise<Response, NeverThrowsException> or a Response. Any other return type, including null, yields an HTTP 500 Server Error response.

    Note that in the Groovy language, methods always return a value. If no return statement is provided, the value evaluated in the last line is returned.

    Also, to return a Promise based on an existing response, use Response.newResponsePromise(response).

  • The global objects passed to Groovy scripts now include context and request.

    Edit your scripts to use request instead of exchange.request.

  • The http global object passed to Groovy scripts is now an org.forgerock.http.Client. A Client has a send() method for sending a request that returns a Promise representing the pending HTTP response.

    The script must then use the Promise methods to deal with the response, working either with asynchronous callbacks or with the Promise get() methods for synchronous responses.

  • The Handler interface has changed, affecting the next.handle() method.

    Edit your scripts to use next.handle(context, request) instead of next.handle(exchange).

  • In Groovy scripts, raw access to header values must now be prefixed with .values or ?.values if the header might not exist. For example, headers.Username[0] must replaced with headers.Username?.values[0]. Similarly, headers['Username'][0] must be replaced with headers['Username']?.values[0].

  • Consumers of audit events now access source, tags, and timestamps through a map called event rather than through the exchange. Request, response, and context are available through event.data.

    For example, to access the request URI, use ${event.data.request.uri}. To access the response headers, use ${event.data.response.headers}.

  • Arguments (args) passed to scripts must no longer override other global objects passed to scripts. Attempts to reuse the name of another global object now cause the script to fail and OpenIG to return a response with HTTP status code 500 Internal Server Error.

  • The examples in Chapter 13, "Extending OpenIG's Functionality" in the Gateway Guide reflect these changes.

• The Route and GatewayHttpApplication configurations now use baseURI decorators instead of baseURI configuration fields.

• This release introduces independent Issuer and ClientRegistration configuration objects. An Issuer represents an OAuth 2.0 authorization server or OpenID Provider. A ClientRegistration represents the client application registration with an Issuer. The OAuth2ClientFilter configuration has changed to work with the new configuration objects. For details, see Table 3.3, "Deprecated Configuration Settings".

  Previous configurations cause errors and prevent the route from loading when OpenIG reads the configuration:

  ------------------------------
  THU SEP 10 17:37:04 CEST 2015 (ERROR) {Router}/handler
  The route defined in file '/home/user/.openig/config/routes/07-openid.json'
   cannot be added
  ------------------------------
  THU SEP 10 17:37:04 CEST 2015 (ERROR) {Router}/handler
  /handler/config/filters/0/config/loginHandler: Expecting a value
  [       JsonValueException] > /handler/config/filters/0/config/loginHandler:
   Expecting a value
      

  The new configuration object calls for HTTP Basic authentication by default when connecting to the provider's OAuth 2.0 token endpoint. The previous implementation called for client credentials to be sent as HTTP POST form data. If necessary you can set tokenEndpointUseBasicAuth to false in the client registration configuration to send client credentials as HTTP POST form data.

• It is no longer possible to set openig-base in the .war file. This was set as a Servlet <init-param>:

  <init-param>
    <param-name>openig-base</param-name>
    <param-value>/path/to/openig</param-value>
  </init-param>
  

  Set the value as a system property or environment variable instead. For details, see Section 3.3, "Installing OpenIG" in the Gateway Guide.

• The classes mentioned in Table 3.2, "Class Changes" have changed names or changed packages.

The following class is likely to be removed in a future release:

• org.forgerock.openig.heap.NestedHeaplet

  The interface to extend instead is org.forgerock.openig.heap.GenericHeaplet.

• Support for Java 6

• The CaptureFilter implementation

  Use a CaptureDecorator instead, as described in CaptureDecorator(5) in the Configuration Reference.

• The GatewayServlet implementation

  The implementation has been replaced with org.forgerock.http.servlet.HttpFrameworkServlet, which wraps an HttpApplication that is provided by org.forgerock.openig.http.GatewayHttpApplication. The GatewayHttpApplication creates the heap and builds the configuration.

• The HttpClient configuration object

  Its configuration is now part of the ClientHandler configuration, described in ClientHandler(5) in the Configuration Reference.

  The hostnameVerifier setting BROWSER_COMPATIBLE has been removed. Consider using STRICT instead.

  The keystore and truststore settings, which are deprecated since the release of 3.1, have been removed. Use keyManager and trustManager instead.

• The client connection information implementation, org.forgerock.openig.http.ClientInfo

  The implementation has been replaced with org.forgerock.services.context.ClientContext.

• The StaticRequestFilter configuration setting restore, used to restore the request in the exchange, has been removed.

The following API interfaces and classes have been removed:

• org.forgerock.openig.filter.Filter

  The new interface to implement is org.forgerock.http.Filter.

• org.forgerock.openig.handler.Handler

  The new interface to implement is org.forgerock.http.Handler.

• org.forgerock.openig.handler.HandlerException

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

• 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

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

The following limitations are present in this release:

• 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 Issuer field, supportedDomains, only causes OpenIG to use ClientRegistration settings if the ClientRegistration name is set to the concatenation of the Issuer name and the OAuth2ClientFilter name. For example, if the Issuer name is openam and the OAuth2ClientFilter name is OAuth2Client then the ClientRegistration name must be set to openamOAuth2Client.

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

• OPENIG-816: The UmaResourceServerFilter returns with wrong as_uri

• OPENIG-813: auditService : fileRotation may overwrite existing audit file

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

• OPENIG-478: assertionMapping doesn't support multi-valued attribute

• OPENIG-466: No way to add realm parameter to tokenInfoEndPoint

• 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