"handler": Handler reference, required

Dispatch all requests to this handler.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

"heap": array of configuration objects, optional

The heap object configuration.

You can omit an empty array. If you only have one object in the heap, you can inline it as the handler value.

"baseURI": string, optional

Overrides the existing request URI, making requests relative to a new base URI.

Only scheme, host and port are used in the supplied URI.

Default: leave the request URI untouched.

"logSink": LogSink reference, optional

Send log messages to this LogSink.

Provide either the name of a LogSink object defined in the heap, or an inline LogSink configuration object.

Default: use the heap object named "LogSink". Otherwise use an internally-created ConsoleLogSink object that is named "LogSink" and that uses default settings for a ConsoleLogSink object.

"temporaryStorage": TemporaryStorage reference, optional

Cache content during processing based on this TemporaryStorage configuration.

Provide either the name of a TemporaryStorage object defined in the heap, or an inline TemporaryStorage configuration object.

Default: use the heap object named "TemporaryStorage". Otherwise use an internally-created TemporaryStorage object that is named "TemporaryStorage" and that uses default settings for a TemporaryStorage object.

"name": string, required except for inline objects

The unique name to give the heap object in the heap. This name is used to resolve the heap object, for example when another heap object names a heap object dependency.

"type": string, required

The class name of the object to be created. To determine the type name, see the object's documentation in this reference.

"config": object, required

The configuration that is specific to the heap object being created.

If all the fields are optional and the configuration uses only default settings, you can omit the "config" field instead of including an empty "config" object as the field value.

When a heap is first created, it is automatically populated with some objects, without required configuration. An automatically created object can be overridden by creating a heap object with the same name.

"LogSink"

The default object to use for writing all audit and performance logging.

Default: a ConsoleLogSink object with default values.

"TemporaryStorage"

The default object to use for managing temporary buffers.

Default: a TemporaryStorage object with default values.

Every heap object has a set of implicit properties, which can be overridden on an object-by-object basis.

"logSink": string

Specifies the heap object that should be used for audit and performance logging.

Default: "LogSink".

"temporaryStorage": string

Specifies the heap object that should be used for temporary buffer storage.

Default: "TemporaryStorage".

"filters": array of Filter references, required

An array of names of Filter objects defined in the heap, and inline Filter configuration objects.

The chain dispatches to dispatch the exchange to these Filters in the order they appear in the array.

"handler": Handler reference, required

Either the name of a Handler object defined in the heap, or an inline Handler configuration object.

The chain dispatches to this handler once the exchange has traversed all of the specified filters.

"httpClient": HttpClient reference, optional

HttpClient used when making HTTP requests to other servers.

Provide either the name of an HttpClient object defined in the heap, or an inline HttpClient configuration object.

Default: use the heap object named "HttpClient", which matches the name of the HttpClient object created by the gateway servlet by default with default settings

If you overload that name by configuring your own HttpClient object named "HttpClient", then use that heap object.

"bindings": array of objects, required

A list of bindings of conditions and associated handlers to dispatch to.

"condition": expression, optional

Condition to evaluate to determine if associated handler should be dispatched to. If omitted, then dispatch is unconditional.

"handler": Handler reference, required

Dispatch to this handler if the associated condition yields true.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

"baseURI": string, optional

Overrides the existing request URI, making requests relative to a new base URI. Only scheme, host and port are used in the supplied URI.

Default: leave URI untouched.

"handler": Handler reference, required

For this route, dispatch the exchange to this handler.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

"heap": array of configuration objects, optional

Heap object configuration for objects local to this route.

Objects referenced but not defined here are inherited from the parent.

You can omit an empty array. If you only have one object in the heap, you can inline it as the handler value.

"baseURI": string, optional

URI on which to rebase the request URL.

If this is set, the request URL is rebased using the value. Rebasing changes the scheme, host, and port of the request URL. Rebasing does not affect the path, query string, or fragment.

Default: the request URL remains unchanged.

"condition": expression, optional

Whether the route accepts to handle the Exchange.

Default: If the condition is not set, or is null, then this route accepts any Exchange.

"name": string, optional

Name for the route, used by the Router to order the routes.

Default: Route configuration file name

"session": Session reference, optional

Session storage implementation used by this route, such as a JwtSession.

Provide either the name of a session storage object defined in the heap, or an inline session storage configuration object.

Default: do not change the session storage implementation for exchange.session.

"defaultHandler": Handler reference, optional

Default handler for this Router.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

The router routes the exchange to the first route whose "condition" expression is satisfied. If no route "condition" matches, then the exchange is routed to the default handler if one is configured.

Default: if no default route is set either here or in the route configurations, then OpenIG aborts the exchange with an internal error.

"directory": expression, optional

Base directory from which to load configuration files for routes.

Default: default base directory for route configuration files. For details see the section, Installing OpenIG in the Gateway Guide.

"scanInterval": integer, optional

Interval in seconds after which OpenIG scans the specified directory for changes to configuration files.

Default: 10 (seconds)

To prevent OpenIG from reloading Route configurations after you except at startup, set the scan interval to -1.

"assertionMapping": object, required

The "assertionMapping" defines how to transform attributes from the incoming assertion to attribute value pairs in OpenIG.

Each entry in the assertionMapping object has the form localName: incomingName, where incomingName is used to fetch the value from the incoming assertion, and localName is the name of the attribute set in the session. Avoid using dot characters (.) in the localName, as the . character also serves as a query separator in expressions.

The following shows an example of an "assertionMapping" object.

{
    "username": "mail",
    "password": "mailPassword"
}
     

If the incoming assertion contains the statement:

mail = george@example.com

mailPassword = costanza

Then the following values are set in the session:

username = george@example.com

password = costanza

For this to work, you must edit the <Attribute name="attributeMap"> element in the SP extended metadata file, $HOME/.openig/SAML/sp-extended.xml, so that it matches the assertion mapping configured in the SAML 2.0 Identity Provider (IDP) metadata.

When protecting multiple service providers, use unique localName settings. Otherwise different handlers can overwrite each others' data.

"redirectURI": string, required

Set this to the page that the filter used to HTTP POST a login form recognizes as the login page for the protected application.

This is how OpenIG and the Federation component work together to provide single sign-on. When OpenIG detects the login page of the protected application, it redirects to the Federation component. Once the Federation handler validates the SAML exchanges with the IDP, and sets the required session attributes, it redirects back to the login page of the protected application. This allows the filter used to HTTP POST a login form to finish the job by creating a login form to post to the application based on the credentials retrieved from the session attributes.

"assertionConsumerEndpoint": string, optional

Default: "fedletapplication" (same as the Fedlet)

If you modify this attribute you must change the metadata to match.

"authnContext": string, optional

Name of the session field to hold the value of the authentication context. Avoid using dot characters (.) in the field name, as the . character also serves as a query separator in expressions.

Use this setting when protecting multiple service providers, as the different configurations must not map their data into the same fields of exchange.session. Otherwise different handlers can overwrite each others' data.

As an example, if you set "authnContext": "myAuthnContext", then OpenIG sets exchange.session.myAuthnContext to the authentication context specified in the assertion. When the authentication context is password over protected transport, then this results in the session containing "myAuthnContext": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport".

Default: map to session.authnContext

"authnContextDelimiter": string, optional

The authentication context delimiter used when there are multiple authentication contexts in the assertion.

Default: |

"logoutURI": string, optional

Set this to the URI to visit after the user is logged out of the protected application.

You only need to set this if the application uses the single logout feature of the Identity Provider.

"sessionIndexMapping": string, optional

Name of the session field to hold the value of the session index. Avoid using dot characters (.) in the field name, as the . character also serves as a query separator in expressions.

Use this setting when protecting multiple service providers, as the different configurations must not map their data into the same fields of exchange.session. Otherwise different handlers can overwrite each others' data.

As an example, if you set "sessionIndexMapping": "mySessionIndex", then OpenIG sets exchange.session.mySessionIndex to the session index specified in the assertion. This results in the session containing something like "mySessionIndex": "s24ccbbffe2bfd761c32d42e1b7a9f60ea618f9801".

Default: map to session.sessionIndex

"singleLogoutEndpoint": string, optional

Default: "fedletSLORedirect" (same as the Fedlet)

If you modify this attribute you must change the metadata to match.

"singleLogoutEndpointSoap": string, optional

Default: "fedletSloSoap" (same as the Fedlet)

If you modify this attribute you must change the metadata to match.

"SPinitiatedSLOEndpoint": string, optional

Default: "SPInitiatedSLO"

If you modify this attribute you must change the metadata to match.

"SPinitiatedSSOEndpoint": string, optional

Default: "SPInitiatedSSO"

If you modify this attribute you must change the metadata to match.

"subjectMapping": string, optional

Name of the session field to hold the value of the subject name. Avoid using dot characters (.) in the field name, as the . character also serves as a query separator in expressions.

Use this setting when protecting multiple service providers, as the different configurations must not map their data into the same fields of exchange.session. Otherwise different handlers can overwrite each others' data.

As an example, if you set "subjectMapping": "mySubjectName", then OpenIG sets exchange.session.mySubjectName to the subject name specified in the assertion. If the subject name is an opaque identifier, then this results in the session containing something like "mySubjectName": "vtOk+APj1s9Rr4yCka6V9pGUuzuL".

Default: map to session.subjectName

The script has access to the following global objects.

Any parameters passed as "args"

You can use the configuration to pass parameters to the script by specifying an "args" object.

Take care when naming keys in the "args" object. If you reuse the name of another global object, then you overwrite the global object value with the specified "args" value.

exchange

The exchange provides access to the HTTP request and response.

The request is created and populated before calling the handler. The handler is responsible for creating and for populating the response in the exchange.

globals

This object is a Map that holds variables that persist across successive invocations.

http

The http object provides an embedded HTTP client.

Use this client to perform outbound HTTP requests.

ldap

The ldap object provides an embedded LDAP client.

Use this client to perform outbound LDAP requests, such as LDAP authentication.

logger

The logger object provides access to the server log sink.

"type": string, required

The Internet media type (formerly MIME type) of the script, "application/x-groovy" for Groovy

"file": string

Path to the file containing the script; mutually exclusive with "source"

Relative paths in the "file" field are relative to the base location for scripts. The base location depends on the configuration. For details see the section, Installing OpenIG in the Gateway Guide.

The base location for Groovy scripts is on the classpath when the scripts are executed. If therefore some Groovy scripts are not in the default package, but instead have their own package names, they belong in the directory corresponding to their package name. For example, a script in package com.example.groovy belongs under openig-base/scripts/groovy/com/example/groovy/.

"source": string

The script as a string; mutually exclusive with "file"

"args": map, optional

Parameters passed from the configuration to the script.

The configuration object is a map whose values can be scalars, arrays, objects and so forth, as in the following example.

{
    "args": {
        "title": "Coffee time",
        "status": 418,
        "reason": [
            "Not Acceptable",
            "I'm a teapot",
            "Acceptable"
        ],
        "names": {
            "1": "koffie",
            "2": "kafe",
            "3": "cafe",
            "4": "kafo"
        }
    }
}
     

The script can then access the "args" parameters in the same way as other global objects. The following example sets the response reason to "I'm a teapot".

exchange.response.reason = reason[1]
     

"bindings": array of objects, required

A list of bindings of handler and postcondition to determine that sequence continues.

"handler": Handler reference, required

Dispatch to this handler.

Either the name of the handler heap object to dispatch to, or an inline Handler configuration object.

"postcondition": expression, optional

Evaluated to determine if the sequence continues. Default: unconditional.

"status": number, required

The response status code (for example, 200).

"reason": string, optional

The response status reason (for example, "OK").

"version": string, optional

Protocol version. Default: "HTTP/1.1".

"headers": array of objects, optional

Header fields to set in the response. The name specifies the header name, with an associated array of expressions to evaluate as values.

"entity": expression, optional

The message entity expression to be evaluated and included in the response.

Conforms to the Content-Type header and sets Content-Length.

"onRequest": array of objects, optional

Defines a list of assignment bindings to evaluate before the exchange is handled.

"onResponse": array of objects, optional

Defines a list of assignment bindings to evaluate after the exchange is handled.

"condition": expression, optional

Expression to evaluate to determine if an assignment should occur. Omitting the condition makes the assignment unconditional.

"target": lvalue-expression, required

Expression that yields the target object whose value is to be set.

"value": expression, optional

Expression that yields the value to be set in the target.

"file": expression, required

The path of the file where captured output should be written.

"charset": string, optional

The character set to encode captured output with. Default: "UTF-8".

"condition": expression, optional

The condition to evaluate to determine whether to capture an exchange. Default: unconditional.

"captureEntity": boolean, optional

Whether the message entity should be captured.

The filter omits binary entities, instead writing a [binary entity] marker to the file.

Default: true

"managed": array of strings, optional

A list of the names of cookies to be managed.

"suppressed": array of strings, optional

A list of the names of cookies to be suppressed.

"relayed": array of strings, optional

A list of the names of cookies to be relayed.

"defaultAction": string, optional

Action to perform for cookies that do not match an action set. Must be one of: "MANAGE", "RELAY", "SUPPRESS". Default: "MANAGE".

"messageType": string, required

Indicates the type of message in the exchange whose headers to encrypt or decrypt.

Must be one of: "REQUEST", "RESPONSE".

"operation": string, required

Indicates whether to encrypt or decrypt.

Must be one of: "ENCRYPT", "DECRYPT".

"key": expression, required

Base64 encoded key value.

"algorithm": string, optional

Algorithm used for encryption and decryption.

Default: "AES/ECB/PKCS5Padding"

"keyType": string, optional

Algorithm name for the secret key.

Default: "AES"

"headers": array of strings, optional

The names of header fields to encrypt or decrypt.

Default: Do not encrypt or decrypt any headers

"messageType": string, required

The message type in the exchange to extract patterns from.

Must be one of: "REQUEST", "RESPONSE".

"charset": string, optional

Overrides the character set encoding specified in message.

Default: the message encoding is used.

"target": lvalue-expression, required

Expression that yields the target object that contains the extraction results.

The "bindings" determine what type of object is stored in the target location.

The object stored in the target location is a Map<String, String>. You can then access its content with ${target.key} or ${target['key']}.

"key": string, required

Name of element in target object to contain an extraction result.

"pattern": pattern, required

The regular expression pattern to find in the entity.

"template": pattern-template, optional

The template to apply to the pattern and store in the named target element.

Default: store the match result itself.

"handler": Handler reference, required

Dispatch to this handler in the event of caught exceptions.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

"file": expression, required

The file containing the record to be read.

"charset": string, optional

The character set the file is encoded in. Default: "UTF-8".

"header": boolean, optional

Indicates the first line of the file contains the set of defined field keys. Default: true.

"fields": array of strings, optional

Explicit field keys in the order they appear in a record, overriding any existing field header. Default: use field header.

"target": lvalue-expression, required

Expression that yields the target object to contain the record.

The target object is a Map<String, String>, where the "fields" are the keys. For example, if the target is ${exchange.credentials} and the record has a "username" field and a "password" field mentioned in the "fields" list, Then you can access the user name as ${exchange.credentials.username} and the password as ${exchange.credentials.password}.

"key": string, required

The name of the field in the file to perform the lookup on.

"value": expression, required

Expression that yields the value to be looked-up within the file.

"messageType": string, required

Indicates the type of message in the exchange to filter headers for. Must be one of: "REQUEST", "RESPONSE".

"remove": array of strings, optional

The names of header fields to remove from the message.

"add": object, optional

Header fields to add to the message. The name specifies the header name, with an associated array of string values.

"username": expression, required

Expression that yields the username to supply during authentication.

"password": expression, required

Expression that yields the password to supply during authentication.

"failureHandler": Handler reference, required

Dispatch to this Handler if authentication fails.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

"cacheHeader": boolean, optional

Whether to cache credentials in the session after the first successful authentication, and then replay those credentials for subsequent authentications in the same session.

With "cacheHeader": false, the filter generates the header for each request. This is useful for example when users change their passwords during a browser session.

Default: true

"baseURI": expression, required

The base URI of the OpenIG instance. This is used to rewrite the Location header on the response.

What an OAuth2ClientFilter does depends on the incoming request URI. In the following list clientEndpoint represents the value of the "clientEndpoint" in the filter configuration.

clientEndpoint/login/provider?goto=url

Redirect the end user for authorization with the specified provider.

The provider then authenticates the end user and obtains authorization consent from the end user before redirecting the user-agent back to the callback client endpoint.

Ultimately if the entire process is successful, the filter saves the authorization state in the exchange and redirects the user-agent to the specified URL.

clientEndpoint/logout?goto=url

Remove the authorization state for the end user and redirect to the specified URL.

clientEndpoint/callback

Handle the callback from the OAuth 2.0 authorization server that occurs as part of the authorization process.

If the callback is handled successfully, the filter saves the authorization state in the exchange at the specified "target" location and redirects to the URL during login.

Other request URIs

Restore authorization state in the specified "target" location and call the next filter or handler in the chain.

"clientEndpoint": expression, required

Base URI for the filter.

For example, if you set "clientEndpoint": "/openid", then the service URIs for this filter on your OpenIG server are /openid/login, /openid/logout, and /openid/callback.

"failureHandler": Handler reference, required

Invoke this Handler if authentication fails.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

If this handler is invoked, then the "target" in the exchange is populated with information about the provider, and the error

The failure object in the "target" is a simple map. It has the following layout.

{
    "provider": "provider name string",
    "error": {
        "realm": "optional string",
        "scope": [ "optional required scope string", ... ],
        "error": "optional string",
        "error_description": "optional string",
        "error_uri": "optional string"
    },
    "access_token": "string",
    "id_token": "string",
    "token_type": "Bearer",
    "expires_in": "number",
    "scope": [ "optional scope string", ... ],
    "client_endpoint": "URL string"
}
     

In the failure object, the following fields are not always present. Their presence depends on when the failure occurs.

• "access_token"

• "id_token"

• "token_type"

• "expires_in"

• "scope"

• "client_endpoint"

"loginHandler": Handler reference, required when multiple providers are configured

Invoke this Handler the user must choose a provider.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

This handler allows the user to choose a provider, as in the following example that allows the user to choose between "openam" and "google".

 {
    "name": "NascarPage",
    "type": "StaticResponseHandler",
    "config": {
        "status": 200,
        "entity": "<html><p><a
                   href='/openid/login?provider=openam&goto=${urlEncode(exchange.originalUri)}'
                   >OpenAM Login</a></p>
                   <p><a
                   href='/openid/login?provider=google&goto=${urlEncode(exchange.originalUri)}'
                   >Google Login</a></p>
                   </html>"
    }
}
     

"cacheExpiration": duration string, optional

Duration for which to cache user-info resources.

OpenIG lazily fetches user info from the OpenID provider. In other words, OpenIG only fetches the information when a downstream Filter or Handler uses the user info. Caching allows OpenIG to avoid repeated calls to OpenID providers when reusing the information over a short period.

A duration is a lapse of time expressed in English, such as "23 hours 59 minutes and 59 seconds".

Durations are not case sensitive.

Negative durations are not supported.

The following units can be used in durations.

• "indefinite", "infinity", "undefined", "unlimited": unlimited duration

• "zero", "disabled": zero-length duration

• "days", "day", "d": days

• "hours", "hour", "h": hours

• "minutes", "minute", "min", "m": minutes

• "seconds", "second", "sec", "s": seconds

• "milliseconds", "millisecond", "millisec", "millis", "milli", "ms": milliseconds

• "microseconds", "microsecond", "microsec", "micros", "micro", "us": microseconds

• "nanoseconds", "nanosecond", "nanosec", "nanos", "nano", "ns": nanoseconds

Default: 20 seconds

Set this to "disabled" or "zero" to disable caching. When caching is disabled, user info is still lazily fetched.

"providerHandler": Handler reference, required

Invoke this HTTP client handler to communicate with the provider.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

Usually set this to the name of a ClientHandler configured in the heap, or a chain that ends in a ClientHandler.

"providers": array of provider configuration objects, required

One or more provider configuration objects that indicate how the client communicates with authorization providers.

If the provider has a well-known configuration URL as defined for OpenID Connect 1.0 Discovery that returns JSON with at least authorization and token endpoint URLs, then you can specify that URL in the provider configuration. Otherwise, you must specify at least the provider authorization and token endpoint URLs, and optionally the user info endpoint URL.

Provider configuration objects have the following layout:

{
    "name": string,
    "clientId": expression,
    "clientSecret": expression,
    "wellKnownConfiguration": URL string,
    "authorizeEndpoint": URI expression,
    "tokenEndpoint": URI expression,
    "userInfoEndpoint": URI expression,
    "scopes": [ "expression", ... ]
}
     

The provider configuration object properties are as follows.

"name": string, required

A name for the provider configuration.

"clientID": expression, required

The client_id obtained when registering with the provider.

"clientSecret": expression, required

The client_secret obtained when registering with the provider.

"wellKnownConfiguration": URL string, required unless "authorizeEndpoint" and "tokenEndpoint" are specified

The URL to the well-known configuration resource as described in OpenID Connect 1.0 Discovery.

"authorizeEndpoint": expression, required unless obtained through "wellKnownConfiguration"

The URL to the provider's OAuth 2.0 authorization endpoint.

"tokenEndpoint": expression, required unless obtained through "wellKnownConfiguration"

The URL to the provider's OAuth 2.0 token endpoint.

"userInfoEndpoint": expression, optional

The URL to the provider's OpenID Connect UserInfo endpoint.

Default: no UserInfo is obtained from the provider.

"scopes": array of expressions, optional

Overrides the list of scopes specified globally for the filter.

Default: use the list of scopes specified globally for the filter.

"target": expression, optional

Expression that yields the target object whose value is to be set, such as ${exchange.openid}.

Default: ${exchange.openid}

"defaultLoginGoto": expression, optional

The URI to redirect to after successful authentication and authorization.

Default: return an empty page.

"defaultLogoutGoto": expression, optional

The URI to redirect to after successful logout.

Default: return an empty page.

"requireHttps": boolean, optional

Whether to require that requests use the HTTPS scheme.

Default: true.

"requireLogin": boolean, optional

Whether to require authentication for all incoming requests.

Default: true.

"scopes": array of expressions, optional

Expression that yields the scope strings to request of any providers contacted by this filter.

Instead of or in addition to specifying scopes globally here, you can also specify a list of scopes per provider in each provider's configuration. Per-provider scope lists then override this list.

Default: do not specify scopes.

"providerHandler": Handler reference, required

Invoke this HTTP client handler to send token info requests.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

Usually set this to the name of a ClientHandler configured in the heap.

"scopes": array of expressions, required

The list of required OAuth 2.0 scopes for this protected resource.

"tokenInfoEndpoint": URL string, required

The URL to the token info endpoint of the OAuth 2.0 authorization server.

"cacheExpiration": duration string, optional

Duration for which to cache OAuth 2.0 access tokens.

Caching allows OpenIG to avoid repeated requests for token info when reusing the information over a short period.

A duration is a lapse of time expressed in English, such as "23 hours 59 minutes and 59 seconds".

Durations are not case sensitive.

Negative durations are not supported.

The following units can be used in durations.

• "indefinite", "infinity", "undefined", "unlimited": unlimited duration

• "zero", "disabled": zero-length duration

• "days", "day", "d": days

• "hours", "hour", "h": hours

• "minutes", "minute", "min", "m": minutes

• "seconds", "second", "sec", "s": seconds

• "milliseconds", "millisecond", "millisec", "millis", "milli", "ms": milliseconds

• "microseconds", "microsecond", "microsec", "micros", "micro", "us": microseconds

• "nanoseconds", "nanosecond", "nanosec", "nanos", "nano", "ns": nanoseconds

Default: 1 minute

Set this to "disabled" or "zero" to disable caching. When caching is disabled, each request triggers a new request to the authorization server to verify the access token.

"requireHttps": boolean, optional

Whether to require that requests use the HTTPS scheme.

Default: true

"realm": string, optional

HTTP authentication realm to include in the WWW-Authenticate response header field when returning an HTTP 401 Unauthorized status to a user-agent that need to authenticate.

Default: OpenIG

"target": expression, optional

Where to store the OAuth 2.0 access token in the exchange, such as ${exchange.token}.

Default: ${exchange.oauth2AccessToken}

The script has access to the following global objects.

Any parameters passed as "args"

You can use the configuration to pass parameters to the script by specifying an "args" object.

Take care when naming keys in the "args" object. If you reuse the name of another global object, then you overwrite the global object value with the specified "args" value.

exchange

The exchange provides access to the HTTP request and response.

globals

This object is a Map that holds variables that persist across successive invocations.

http

The http object provides an embedded HTTP client.

Use this client to perform outbound HTTP requests.

ldap

The ldap object provides an embedded LDAP client.

Use this client to perform outbound LDAP requests, such as LDAP authentication.

logger

The logger object provides access to the server log sink.

next

The next object refers to the next handler in the filter chain.

"type": string, required

The Internet media type (formerly MIME type) of the script, "application/x-groovy" for Groovy

"file": string

Path to the file containing the script; mutually exclusive with "source"

Relative paths in the "file" field are relative to the base location for scripts. The base location depends on the configuration. For details see the section, Installing OpenIG in the Gateway Guide.

The base location for Groovy scripts is on the classpath when the scripts are executed. If therefore some Groovy scripts are not in the default package, but instead have their own package names, they belong in the directory corresponding to their package name. For example, a script in package com.example.groovy belongs under openig-base/scripts/groovy/com/example/groovy/.

"source": string

The script as a string; mutually exclusive with "file"

"args": object, optional

Parameters passed from the configuration to the script.

The configuration object is a map whose values can be scalars, arrays, objects and so forth, as in the following example.

{
    "args": {
        "title": "Coffee time",
        "status": 418,
        "reason": [
            "Not Acceptable",
            "I'm a teapot",
            "Acceptable"
        ],
        "names": {
            "1": "koffie",
            "2": "kafe",
            "3": "cafe",
            "4": "kafo"
        }
    }
}
     

The script can then access the "args" parameters in the same way as other global objects. The following example sets the response reason to "I'm a teapot".

exchange.response.reason = reason[1]
     

"dataSource": string, required

The JNDI name of the factory for connections to the physical data source.

"preparedStatement": string, required

The parameterized SQL query to execute, with ? parameter placeholders.

"parameters": array of expressions, optional

The parameters to evaluate and include in the execution of the prepared statement.

"target": lvalue-expression, required

Expression that yields the target object that will contain the query results.

"method": string, required

The HTTP method to be performed on the resource (for example, "GET").

"uri": string, required

The fully-qualified URI of the resource to access (for example, "http://www.example.com/resource.txt").

"version": string, optional

Protocol version. Default: "HTTP/1.1".

"restore": boolean, optional

Whether to restore the original request after the exchange is handled.

Default: false

"headers": object, optional

Header fields to set in the request.

The name specifies the header name. Its value is an array of expressions to evaluate as header values.

"form": object, optional

A form to include in the request.

The param specifies the form parameter name. Its value is an array of expressions to evaluate as form field values.

"onRequest": array of objects, optional

Conditions to test (and handler to dispatch to, if true) before the exchange is handled.

"onResponse": array of objects, optional

Conditions to test (and handler to dispatch to, if true) after the exchange is handled.

"condition": expression, optional

Condition to evaluate to determine if exchange should be dispatched to handler.

Default: unconditional dispatch to handler.

"handler": Handler reference, required

Dispatch to this handler if the condition yields true.

Provide either the name of a Handler object defined in the heap, or an inline Handler configuration object.

To help listeners determine what to do with audit events, each audit event holds the following information about what it represents.

exchange

A reference to the Exchange involved in the event.

Note that does not represent a copy of the exchange at event creation. If notification receivers process the event asynchronously, the content of the exchange can change between the time the event is created and the time the receiver processes the audit event.

source

The source of the audit event, meaning the name of the object under audit.

For details, see org.forgerock.openig.audit.AuditSource.

tags

Strings that qualify the event. Entities receiving notifications can use the tags to select audit events of interest.

Define your own audit tags in order to identify particular events or routes.

OpenIG provides the following built-in tags in org.forgerock.openig.audit.Tag.

• request: This event happens before OpenIG calls the decorated object.

• response: This event happens after the call to the decorated object returns or throws an exception.

  When decorating a Filter, realize that the filter returns after handling the response, even if it only filters the request and so does nothing to the response but pass it along.

• completed: This event happens when the processing unit under audit has successfully handled the exchange. This tag always complements a response tag.

  Note that completed says nothing about the client application's perception of whether the result of the exchange was successful. For example, a Handler could successfully pass back an HTTP 404 Not Found response.

• exception: This event happens when the processing unit under audit handled the exchange with errors. This tag always complements a response tag.

  Note that the source object might not have thrown an exception itself, so it is not necessarily the source of the error.

  Also note that exception says nothing about the client application's perception of whether the result of the exchange was a failure. For example, another processing unit could still pass back a success response to the client application or proxy that engaged the exchange.

timestamp

Timestamp indicating when the event happened, with millisecond precision.

"name": string, required except for inline objects

The unique name of the object, just like an object that is not decorated.

"type": string, required

The class name of the decorated object, which must be either a Filter or a Handler.

"config": object, required unless empty

The configuration of the object, just like an object that is not decorated.

"audit": string or array of strings, required

Set the value to the tag(s) used to select audit events of interest.

To activate the audit decoration without setting any user-defined tags, set "audit" to any other value, such as "audit": true.

The decorator configuration has these properties.

"logSink": LogSink reference, optional

Capture requests and responses to this LogSink.

Provide either the name of a LogSink object defined in the heap, or an inline LogSink configuration object.

Default: use the "LogSink" configured for the decorated object. This makes it possible to keep all logs in a central location.

"captureEntity": boolean, optional

Whether the message entity should be captured.

The filter omits binary entities, instead writing a [binary entity] marker to the file.

Default: false

"captureExchange": boolean, optional

Whether the exchange, excluding the request and response, should be captured as JSON.

Default: false

"name": string, required except for inline objects

The unique name of the object, just like an object that is not decorated

"type": string, required

The class name of the decorated object, which must be either a Filter or a Handler

"config": object, required unless empty

The configuration of the object, just like an object that is not decorated

decorator name: capture point(s), optional

The decorator name must match the "name" of the CaptureDecorator. For example, if the CaptureDecorator has "name": "capture", then decorator name is "capture".

The capture point(s) are either a single string, or an array of strings. The strings are documented here in lowercase, but are not case-sensitive.

"all"

Capture at all available capture points

"request"

Capture the request as it enters the Filter or Handler

"filtered_request"

Capture the request as it leaves the Filter

Only applies to Filters

"response"

Capture the response as it enters the Filter or leaves the Handler

"filtered_response"

Capture the response as it leaves the Filter

Only applies to Filters

"name": string, required except for inline objects

The unique name of the object, just like an object that is not decorated

"type": string, required

The class name of the decorated object, which must be either a Filter or a Handler

"config": object, required unless empty

The configuration of the object, just like an object that is not decorated

decorator name: boolean, required

OpenIG looks for the presence of the decorator name field for the TimerDecorator.

To activate the timer, set the value of the decorator name field to true.

To deactivate the TimerDecorator temporarily, set the value to false.

"level": string, optional

The level of log entries to display in the console.

Must be one of the following settings. These are ordered from most verbose to least verbose. ALL (log all messages), TRACE (log low-level tracing information), DEBUG (log debugging information), STAT (log performance measurement statistics), CONFIG (log configuration information), INFO (log general information), WARNING (log potential problems), ERROR (log serious failures), OFF (log no messages).

Default: INFO.

"stream": string, optional

The standard output to use to display logs in the console.

Must be one of the following settings. ERR (use standard error: System.err), OUT (use standard output: System.out), AUTO (select standard error or output depending on the message log level: TRACE, DEBUG, STAT, CONFIG, INFO print to System.out, WARNING and ERROR print to System.err).

Default: ERR.

"file": configuration expression, required

The path to the log file.

A configuration expression is independent of the exchange, so do not use expressions that reference exchange properties. You can, however, use ${env['variable']}, ${system['property']}, and all the built-in functions.

"level": string, optional

The level of log entries to display in the console.

Must be one of the following settings. These are ordered from most verbose to least verbose. ALL (log all messages), TRACE (log low-level tracing information), DEBUG (log debugging information), STAT (log performance measurement statistics), CONFIG (log configuration information), INFO (log general information), WARNING (log potential problems), ERROR (log serious failures), OFF (log no messages).

Default: INFO.

"connections": number, optional

The maximum number of connections to open, from 1-64 inclusive.

Default: 64

"connectionTimeout": duration string, optional

Amount of time to wait to establish a connection, expressed as a duration

A duration is a lapse of time expressed in English, such as "23 hours 59 minutes and 59 seconds".

Durations are not case sensitive.

Negative durations are not supported.

The following units can be used in durations.

• "indefinite", "infinity", "undefined", "unlimited": unlimited duration

• "zero", "disabled": zero-length duration

• "days", "day", "d": days

• "hours", "hour", "h": hours

• "minutes", "minute", "min", "m": minutes

• "seconds", "second", "sec", "s": seconds

• "milliseconds", "millisecond", "millisec", "millis", "milli", "ms": milliseconds

• "microseconds", "microsecond", "microsec", "micros", "micro", "us": microseconds

• "nanoseconds", "nanosecond", "nanosec", "nanos", "nano", "ns": nanoseconds

Default: 10 seconds

"disableRetries": boolean, optional

Whether to disable automatic retries for failed requests.

Default: true

"disableReuseConnection": boolean, optional

Whether to disable connection reuse.

Default: true

"hostnameVerifier": string, optional

How to handle hostname verification for outgoing SSL connections.

Set this to one of the following values.

• ALLOW_ALL: turn off verification.

• BROWSER_COMPATIBLE: match the hostname either as the value of the the first CN, or any of the subject-alt names.

  A wildcard can occur in the CN, and in any of the subject-alt names. Wildcards match all subdomains, so *.example.com matches www.example.com and some.host.example.com.

• STRICT: match the hostname either as the value of the the first CN, or any of the subject-alt names.

  A wildcard can occur in the CN, and in any of the subject-alt names. Wildcards match one domain level, so *.example.com matches www.example.com but not some.host.example.com.

Default: ALLOW_ALL

"keyManager": KeyManager reference(s), optional

The key manager(s) that handle(s) this client's keys and certificates.

The value of this field can be a single reference, or an array of references.

Provide either the name(s) of KeyManager object(s) defined in the heap, or specify the configuration object(s) inline.

You can specify either a single KeyManager, as in "keyManager": "MyKeyManager", or an array of KeyManagers, as in "keyManager": [ "FirstKeyManager", "SecondKeyManager" ].

If you do not configure a key manager, then the client cannot present a certificate, and so cannot play the client role in mutual authentication.

"soTimeout": duration string, optional

Socket timeout, after which stalled connections are destroyed, expressed as a duration

A duration is a lapse of time expressed in English, such as "23 hours 59 minutes and 59 seconds".

Durations are not case sensitive.

Negative durations are not supported.

The following units can be used in durations.

• "indefinite", "infinity", "undefined", "unlimited": unlimited duration

• "zero", "disabled": zero-length duration

• "days", "day", "d": days

• "hours", "hour", "h": hours

• "minutes", "minute", "min", "m": minutes

• "seconds", "second", "sec", "s": seconds

• "milliseconds", "millisecond", "millisec", "millis", "milli", "ms": milliseconds

• "microseconds", "microsecond", "microsec", "micros", "micro", "us": microseconds

• "nanoseconds", "nanosecond", "nanosec", "nanos", "nano", "ns": nanoseconds

Default: 10 seconds

"trustManager": TrustManager reference(s), optional

The trust managers that handle(s) peers' public key certificates.

The value of this field can be a single reference, or an array of references.

Provide either the name(s) of TrustManager object(s) defined in the heap, or specify the configuration object(s) inline.

You can specify either a single TrustManager, as in "trustManager": "MyTrustManager", or an array of KeyManagers, as in "trustManager": [ "FirstTrustManager", "SecondTrustManager" ].

If you do not configure a trust manager, then the client uses only the default Java trust store. The default Java trust store depends on the Java environment. For example, $JAVA_HOME/lib/security/cacerts.

"keystore": KeyStore reference, optional

The key store holding the key pair with the private key used to encrypt the JWT.

Provide either the name of the KeyStore object defined in the heap, or the inline KeyStore configuration object inline.

Default: When no "keystore" is specified, OpenIG generates a unique key pair, and stores the key pair in memory. With JWTs encrypted using a unique key pair generated at runtime, OpenIG cannot decrypt the JWTs after a restart, nor can it decrypt such JWTs encrypted by another OpenIG server.

"alias": string, required when "keystore" is used

Alias for the private key.

"password": configuration expression, required when "keystore" is used

The password to read the private key from the key store.

A configuration expression is independent of the exchange, so do not use expressions that reference exchange properties. You can, however, use ${env['variable']}, ${system['property']}, and all the built-in functions.

"cookieName" string, optional

The name of the JWT cookie stored on the user-agent.

Default: openig-jwt-session

"keystore": KeyStore reference, optional

The key store that references the store for the actual keys.

Provide either the name of the KeyStore object defined in the heap, or the inline KeyStore configuration object inline.

"password": expression, required

The password to read private keys from the key store.

"alg" string, optional

The certificate algorithm to use.

Default: the default for the platform, such as "SunX509"

"url": expression, required

URL to the key store file.

"password": expression, optional

The password to read private keys from the key store.

If the key store is used as a trust store to store only public key certificates of peers and no password is required to do so, then you do not have to specify this field.

Default: No password is set.

"type": string, optional

The key store format.

Default: the default for the platform, such as "JKS"

"initialLength": number, optional

The initial length of memory buffer byte array. Default: 8192 (8 KiB).

"memoryLimit": number, optional

The length limit of the memory buffer. Exceeding this limit results in promotion from memory to file. Default: 65536 (64 KiB).

"fileLimit": number, optional

The length limit of the file buffer. Exceeding this limit results in a thrown exception. Default: 1048576 (1 MiB).

"directory": string, optional

The directory where temporary files are created. If omitted, then the system-dependent default temporary directory is used (typically "/tmp" on Unix systems). Default: use system-dependent default.

"keystore": KeyStore reference, optional

The KeyStore that references the store for public key certificates.

Provide either the name of the KeyStore object defined in the heap, or the inline KeyStore configuration object inline.

"alg" string, optional

The certificate algorithm to use.

Default: the default for the platform, such as "SunX509"

object

the object to be searched for the presence of.

value

the value to be searched for.

true

if the object contains the specified value.

string

The base64-encoded string to decode.

string

The base64-decoded string.

string

The string to encode into Base64.

string

The base64-encoded string.

string

the string to be searched.

substring

the value to search for within the string.

 

the index of the first instance of substring, or -1 if not found.

separator

the separator to place between joined elements.

strings

the array of strings to be joined.

 

the string containing the joined strings.

map

the map whose keys are to be searched.

pattern

a string containing the regular expression pattern to match.

 

the first matching key, or null if no match found.

object

the object whose length is to be determined.

 

the length of the object, or 0 if length could not be determined.

string

the string to be searched.

pattern

a string containing the regular expression pattern to match.

 

an array of matching groups, or null if no such match is found.

string

the string to be searched.

pattern

a string containing the regular expression pattern to find.

true

if the string contains the specified regular expression pattern.

string

The name of the file to read.

string

The content of the file or null on error.

string

The name of the Java Properties file to read.

object

The key/value map of properties or null on error.

string

the string to be split.

pattern

the regular expression to split substrings around.

 

the resulting array of split substrings.

string

the string whose characters are to be converted.

 

the string with characters converted to lower case.

object

the object whose string value is to be returned.

 

the string value of the object.

string

the string whose characters are to be converted.

 

the string with characters converted to upper case.

string

the string whose white space is to be omitted.

 

the string with leading and trailing white space omitted.

string

The string to be URL decoded, which may be null.

 

The URL decoding of the provided string, or null if string was null.

string

The string to be URL encoded, which may be null.

 

The URL encoding of the provided string, or null if string was null.

"certificates": array

List of X.509 certificates presented by the client

If the client does not present any certificates, OpenIG returns an empty list.

This is never null.

"remoteAddress": string

The IP address of the client (or the last proxy) that sent the request

"remoteHost": string

The fully qualified host name of the client (or the last proxy) that sent the request

"remotePort": number

The source port of the client (or the last proxy) that sent the request

"remoteUser": string

The login of the user making the request, or null if unknown

This is likely to be null unless you have deployed OpenIG with a non-default deployment descriptor that secures the OpenIG web application.

"userAgent": string

The value of the User-Agent HTTP header in the request if any, otherwise null

"clientInfo": object

Information about the client making the request in this HTTP exchange.

"exchange": object

Self-referential property to make this the root object in the exchange object model.

"originalUri": URI

The original target URI for the request, as received by the web container.

The value of this field is read-only.

"request": object

The request portion of the HTTP exchange.

"response": object

The response portion of the HTTP exchange.

"principal": object

The principal associated with the request, or null if unknown.

"session": object

Session context associated with the remote client. Exposes session attributes as name-value pairs, where both name and value are strings.

"method": string

The method to be performed on the resource. Example: "GET".

"uri": object

The fully-qualified URI of the resource being accessed. Example: "http://www.example.com/resource.txt".

"version": string

Protocol version. Example: "HTTP/1.1".

"headers": object

Exposes message header fields as name-value pairs, where name is header name and value is an array of header values.

"cookies": object

Exposes incoming request cookies as name-value pairs, where name is cookie name and value is an array of string cookie values.

"form": object

Exposes query parameters and/or application/x-www-form-urlencoded entity as name-value pairs, where name is the field name and value is an array of string values.

"entity": object

The message entity body (no accessible properties).

"name": string

The name of the principal, or null if principal is undefined (user has not been authenticated).

"status": number

The response status code. Example: 200.

"reason": string

The response status reason. Example: "OK".

"version": string

Protocol version. Example: "HTTP/1.1".

"headers": object

Exposes message header fields as name-value pairs, where name is header name and value is an array of header values.

"entity": object

The message entity body (no accessible properties).

"scheme": string

The scheme component of the URI, or null if the scheme is undefined.

"authority": string

The decoded authority component of the URI, or null if the authority is undefined.

Use "rawAuthority" to access the raw (encoded) component.

"userInfo": string

The decoded user-information component of the URI, or null if the user information is undefined.

Use "rawUserInfo" to access the raw (encoded) component.

"host": string

The host component of the URI, or null if the host is undefined.

"port": number

The port component of the URI, or null if the port is undefined.

"path": string

The decoded path component of the URI, or null if the path is undefined.

Use "rawPath" to access the raw (encoded) component.

"query": string

The decoded query component of the URI, or null if the query is undefined.

Use "rawQuery" to access the raw (encoded) component.

"fragment": string

The decoded fragment component of the URI, or null if the fragment is undefined.

Use "rawFragment" to access the raw (encoded) component.