mode: operating mode, optional

Set the IG mode to development or production. The value is not case-sensitive.

Development mode

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

In development mode, by default all endpoints are open and accessible. You can create, edit, and deploy routes through IG Studio, and manage routes through Common REST, without authentication or authorization.

To protect specific endpoints in development mode, configure an ApiProtectionFilter in admin.json and add it to the IG configuration.

Production mode

After you have developed your configuration, switch to production mode to test the configuration, to run the software in pre-production or production, or to run multiple instances of the software with the same configuration.

In production mode, the /routes endpoint is not exposed or accessible. IG Studio is effectively disabled, and you cannot manage, list, or even read routes through Common REST.

By default, other endpoints, such as /monitoring, /share, and api/info are exposed to the loopback address only. To change the default protection for specific endpoints, configure an ApiProtectionFilter in admin.json and add it to the IG configuration.

Default: development

"heap": array of configuration objects, optional

The heap object configuration, described in Heap Objects(5).

You can omit an empty array.

"prefix": configuration expression<string>, optional

The base of the route for administration requests. This route and its subroutes are reserved for administration endpoints.

Default: openig

"properties": JSON object, optional

Configuration parameters declared as property variables for use in the configuration. See also Properties(5).

Default: none

"temporaryStorage": TemporaryStorage reference, optional

Cache content during processing based on this TemporaryStorage configuration.

Define the TemporaryStorage in one of the following ways:

• An inline TemporaryStorage configuration object.

• The name of a TemporaryStorage object defined in the heap.

• A configuration expression that evaluates to the name of a TemporaryStorage object defined in the heap.

Default: use the heap object named TemporaryStorage.

See also reference and TemporaryStorage(5).

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

See also Handlers.

"heap": array of configuration objects, optional

The heap object configuration, described in Heap Objects(5).

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

"properties": JSON object, optional

Configuration parameters declared as property variables for use in the configuration. See also Properties(5).

Default: none

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

See also TemporaryStorage(5).

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

IG automatically creates required configuration objects. To override an automatically created object, create a heap object with the same name. The following objects are automatically created:

"ApiProtectionFilter"

The default filter used to protect administrative APIs on reserved routes. Reserved routes are described in "Reserved Routes".

To override this filter, declare a different filter with the same name in admin.json. For more information, see AdminHttpApplication(5).

Default: a filter that allows access only from the loopback address.

"TemporaryStorage"

The default object to use for managing temporary buffers.

Default: a TemporaryStorage object named "TemporaryStorage" with the default configuration is added to the top-level heap.

Routes can use this object without explicitly defining it. To override this object, create a TemporaryStorage heap object with the same name.

See also TemporaryStorage(5).

"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 the request to these filters in the order they appear in the array.

See also Filters.

"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 after the request has traversed all of the specified filters.

See also Handlers.

"connections": number, optional

The maximum number of connections in the HTTP client connection pool.

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, and 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, µs: microseconds

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

Default: 10 seconds

"disableRetries": boolean, optional

Whether to disable automatic retries for failed requests.

Default: false

"disableReuseConnection": boolean, optional

Whether to disable connection reuse.

Default: false

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

• 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

"numberOfWorkers": number, optional

The number of worker threads dedicated to processing outgoing requests.

Increasing the value of this attribute can be useful in deployments where a high number of simultaneous connections remain open, waiting for protected applications to respond.

Default: One thread per CPU available to the JVM.

"proxy": Server reference, optional

A proxy server to which requests can be submitted. Use this property to submit requests to other parts of the network, for example, to submit requests from an internal network to the internet.

url: configuration expression<uri string>, required

URI of a server to use as a proxy for outgoing requests.

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object.

username: string, required if the proxy requires authentication

Username to access the proxy server.

password: string, required if the proxy requires authentication

Password to access the proxy server.

In the following example, the ClientHandler passes outgoing requests to the proxy server, which requires authentication:

"handler": {
  "type": "ClientHandler",
  "config": {
     "proxy" : {
        "uri": "http://proxy.example.com:3128",
        "username": "proxy-user",
        "password": "proxy-password"
     }
  }
}

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

See also KeyManager(5).

"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, and 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, µs: microseconds

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

Default: 10 seconds

"sslCipherSuites": array of strings, optional

Array of cipher suite names, used to restrict the cipher suites allowed when negotiating transport layer security for an HTTPS connection.

For details about the available cipher suite names, see the documentation for the Java virtual machine (JVM) used by the container where you run IG. For Oracle Java, see the list of JSSE Cipher Suite Names.

Default: Allow any cipher suite supported by the JVM.

"sslContextAlgorithm": string, optional

The SSLContext algorithm name, as listed in the table of SSLContext Algorithms for the Java Virtual Machine used by the container where IG runs.

Default: TLS

"sslEnabledProtocols": array of strings, optional

Array of protocol names, used to restrict the protocols allowed when negotiating transport layer security for an HTTPS connection.

For details about the available protocol names, see the documentation for the Java virtual machine (JVM) used by the container where you run IG. For Oracle Java, see the list of Additional JSSE Standard Names.

Default: Allow any protocol supported by the JVM.

"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 truststore. The default Java truststore depends on the Java environment. For example, $JAVA_HOME/lib/security/cacerts.

See also TrustManager(5).

"temporaryStorage": string, optional

Specifies the heap object to use for temporary buffer storage.

Default: The temporary storage object named TemporaryStorage, declared in the top-level heap.

"bindings": array of objects, required

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

"condition": runtime expression<boolean>, optional

If the expression evaluates true, the request is dispatched to the associated handler. If no condition is specified, the request is dispatched to the associated handler unconditionally.

Default: No condition is specified.

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

See also Handlers.

"baseURI": runtime expression<uri string>, optional

A base URI that overrides the existing request URI. Only scheme, host, and port are used in the supplied URI.

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object. For example, it would be incorrect to use ${request.uri}, which is not a String but a MutableUri.

In the following example, the binding condition looks up the hostname of the request. If it finds a match, the value is used for the baseURI. Otherwise, the default value is used:

{
  "properties": {
    "uris": {
      "app1.example.com": {
        "baseURI": "http://backend1:8080/"
      },
      "app2.example.com": {
        "baseURI": "http://backend2:8080/"
      },
      "default": {
        "baseURI": "http://backend3:8080/"
      }
    }
  },
  "handler": {
    "type": "DispatchHandler",
    "config": {
      "bindings": [
        {
          "condition": "${not empty uris[contexts.router.originalUri.host]}",
          "baseURI": "${uris[contexts.router.originalUri.host].baseURI}",
          "handler": "ClientHandler"
        },
        {
          "baseURI": "${uris['default'].baseURI}",
          "handler": "ClientHandler"
        }
      ]
    }
  }
}

Default: No change to the base URI

"handler": Handler reference, required

For this route, dispatch the request to this handler.

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

See also Handlers.

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

See also Heap Objects(5).

"condition": runtime expression<boolean>, optional

If the expression evaluates to true, the request is dispatched to the route. If no condition is specified, the route accepts any request.

Default: No condition is specified.

All paths starting with /openig are reserved for administrative use by IG. Expressions such as the following never match externally configured routes: ${matches(request.uri.path, '^/openig/my/path')}. In effect, such routes are ignored.

See also Expressions(5).

"monitor": boolean expression OR object, optional

This property lets you specify whether to maintain statistics about the route, and optionally to specify the percentiles in the distribution for which to record response times.

Use a boolean or boolean expression to activate monitoring with the default percentiles configuration.

When the boolean expression resolves to true, statistics for the route are exposed at a Common REST endpoint. For more information, see "The REST API for Monitoring".

For information about API descriptors for monitoring endpoints, see "Understanding IG APIs With API Descriptors" in the Gateway Guide. For information about Common REST, see "About ForgeRock Common REST".

Default: false, with percentiles 0.999, 0.9999, and 0.99999.

{
    "monitor": {
        "enabled": boolean expression OR boolean,
        "percentiles": array of numbers
    }
}

The configuration object fields include the following:

"enabled": boolean expression, required

Whether to maintain statistics about the route, as described above.

"percentiles": array of decimal numbers, optional

The percentiles in the distribution for which to maintain response time statistics. If you specify percentiles, only those percentiles are used. The default percentile settings no longer apply.

Each value in the array is a decimal representation of a percentage. For example, 0.999 represents 99.9%.

The statistic maintained for a percentile is the response time in milliseconds after which percentile of responses were sent. For example, the statistic for 0.999 corresponds to the response time in milliseconds after which 99.9% of responses were sent. The statistic for 0.5 corresponds to the response time in milliseconds after which half of all responses were sent.

Default: [ 0.999, 0.9999, 0.99999 ]

The following examples show the formats of the monitor attribute:

{
    "monitor": true
}

{
   "monitor": {
       "enabled": false
   }
}

{
   "monitor": {
       "enabled": "${true}",
       "percentiles": [ 0.1, 0.75, 0.99, 0.999 ]
   }
}

"name": string, optional

Name for the route. This parameter is used by the router to order the routes in the configuration. If the route is not named, the route ID is used.

When you add a route manually to the routes folder or add it through Common REST, the route ID is the same as the filename of the route you add. When you add a route through IG Studio, you can edit the default route ID.

Default: route ID

"session": Session reference, optional

Session storage implementation used by this route, such as a JwtSession as described in JwtSession(5).

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

"defaultHandler": Handler reference, optional

Handler to use when a request does not satisfy the condition of any route.

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

Default: If no default route is set either here or in the route configurations, IG aborts the request with an internal error.

See also Handlers.

"directory": expression, optional

Base directory from which to load configuration files for routes.

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

The following example changes the file system location to look for routes:

{
    "type": "Router",
    "config": {
        "directory": "/path/to/safe/routes",
    }
}

Important

If you define a new router in the default base directory, then you must set the directory property to a different directory from the default base directory in order to avoid a circular reference to the new router.

See also Expressions(5).

"scanInterval": duration string or integer, optional

Time interval at which IG scans the specified directory for changes to routes. When a route is added, removed, or changed, the router updates the IG configuration without needing to restart IG or access the route.

When an integer is used for the scanInterval, the time unit is seconds.

To load routes at startup only, and prevent changes to the configuration if the routes are changed, set the scan interval to disabled.

Default: 10 seconds

A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive, and 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, µs: microseconds

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

"assertionMapping": object, required

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

Each entry in the assertionMapping object has the form localName: incomingName, where:

• localName is the name of the attribute set in the session

• incomingName is the name of the attribute set in the incoming assertion

The following example is 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, 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.

Because the dot character (.) serves as a query separator in expressions, do not use dot characters in the localName.

To prevent different handlers from overwriting each others' data, use unique localName settings when protecting multiple service providers.

"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 IG and the Federation component work together to provide SSO. When IG 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. Because the dot character (.) serves as a query separator in expressions, do not use dot characters in the field name.

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

As an example, if you set "authnContext": "myAuthnContext", then IG sets 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. Because the dot character (.) serves as a query separator in expressions, do not use dot characters in the field name.

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

As an example, if you set "sessionIndexMapping": "mySessionIndex", then IG sets 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. Because the dot character (.) serves as a query separator in expressions, do not use dot characters in the field name.

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

As an example, if you set "subjectMapping": "mySubjectName", then IG sets 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

"type": string, required

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

"file": expression

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 "Installing IG" in the Gateway Guide.

The base location for Groovy scripts is on the classpath when the scripts are executed. If 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 or array of strings, required if "file" is not used

The script as a string or array of strings; mutually exclusive with "file".

The following example shows the source of a script as an array of strings:

"source" : [
    "Response response = new Response(Status.OK)",
    "response.entity = 'foo'",
    "return response"
]

"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 status to I'm a teapot:

response.status = Status.valueOf(418, reason[1])

For details regarding this status code see RFC 7168, Section 2.3.3 418 I'm a Teapot.

Args parameters can reference objects defined in the heap using expressions. For example, the following excerpt shows the heap that defines SampleFilter:

{
    "heap": [
        {
            "name": "SampleFilter",
            "type": "SampleFilter",
            "config": {
                "name": "X-Greeting",
                "value": "Hello world"
            }
        }
    ]
}

To pass SampleFilter to the script, the following example uses an expression in the args parameters:

{
    "args": {
        "filter": "${heap['SampleFilter']}"
    }
}

The script can then reference SampleFilter as filter.

For details about the heap, see Heap Objects(5).

"clientHandler", ClientHandler reference, optional

A Handler for making outbound HTTP requests.

Default: Use the default ClientHandler.

For details, see Handlers.

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

See also Handlers.

"postcondition": runtime expression<boolean>, optional

If the expression evaluates to true, the sequence continues. If a condition is not specified, the sequence continues unconditionally.

Default: No condition is specified.

See also Expressions(5).

"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

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

"entity": runtime expression<string>, optional

The message entity to include in the request.

If present, it must conform to the Content-Type header and set the content length header automatically.

See also Expressions(5).

"onRequest": array of objects, optional

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

"onResponse": array of objects, optional

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

"condition": runtime expression<boolean>, optional

If the expression evaluates true, the value is assigned to the target. If no condition is specified, the value is assigned to the target unconditionally.

Default: No condition is specified.

See also Expressions(5).

"target": lvalue-expression, required

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

See also Expressions(5).

"value": runtime expression, optional

The value to be set in the target. The value can be a string, information from the context, or even a whole map of information.

See also Expressions(5).

"condition": runtime expression<boolean>, required

If the expression evaluates to true, the request is dispatched to the delegate Filter. Otherwise the delegate Filter is skipped.

See also Expressions.

"delegate": filter reference, required

Filter to treat the request if the condition expression evaluates as true.

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

See also Filters.

"condition": runtime expression<boolean>, required

If the expression evaluates to true, the request continues to be executed.

See also Expressions.

"failureHandler": handler reference, optional

Handler to treat the request if the condition expression evaluates as false.

Provide an inline handler configuration object, or the name of a handler object that is defined in the heap.

See also Handlers.

Default: HTTP 403 Forbidden, the request stops being executed.

"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 the request to these filters in the order they appear in the array.

See also Filters.

"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": enumeration, optional

Action to perform for cookies that do not match an action set. Set to "MANAGE", "RELAY", or "SUPPRESS". Default: "MANAGE".

"messageType": string, required

Indicates the type of message 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.

See also Expressions(5).

"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 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']}.

See also Expressions(5).

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

See also Patterns(5).

"template": pattern-template, optional

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

Default: store the match result itself.

See also Patterns(5).

"file": expression, required

The file containing the record to be read.

See also Expressions(5).

"charset": string, optional

The character set in which the file is encoded.

Default: "UTF-8".

"separator": separator identifier string, optional

The separator character, which is one of the following:

COLON

Unix-style colon-separated values, with backslash as the escape character.

COMMA

Comma-separated values, with support for quoted literal strings.

TAB

Tab separated values, with support for quoted literal strings.

Default: COMMA

"header": boolean, optional

The setting to treat or not treat the first row of the file as a header row.

When the first row of the file is treated as a header row, the data in that row is disregarded and cannot be returned by a lookup operation.

Default: true.

"fields": array of strings, optional

A list of keys in the order they appear in a record.

If fields is not set, the keys are assigned automatically by the column numbers of the file.

"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 ${attributes.file} and the record has a username field and a password field mentioned in the fields list, Then you can access the user name as ${attributes.file.username} and the password as ${attributes.file.password}.

See also Expressions(5).

"key": string, required

The key used for the lookup operation.

"value": runtime expression<string>, required

The value to be looked-up in the file.

See also Expressions(5).

"messageType": enumeration, required

Indicates the type of message 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 header name is specified by name. The header values are specified by an array of runtime expressions that evaluate to strings.

"username": runtime expression<string>, required

The username to supply during authentication.

See also Expressions(5).

"password": runtime expression<string>, required

The password to supply during authentication.

See also Expressions(5).

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

See also Handlers.

"cacheHeader": boolean, optional

Whether or not 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": runtime expression<uri string>, optional

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

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object. For example, it would be incorrect to use ${request.uri}, which is not a String but a MutableUri.

Default: Redirect to the original URI specified in the request.

See also Expressions(5).

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/?discovery=user-input&goto=url

Using the user-input value, discover and register dynamically with the end user's OpenID Provider or with the client registration endpoint as described in RFC 7591.

Upon successful registration, redirect the end user to the provider for authentication and authorization consent before redirecting the user-agent back to the callback client endpoint.

clientEndpoint/login?registration=registrationName&goto=url

Redirect the end user for authorization with the specified registration, which is the name of a ClientRegistration configuration as described in ClientRegistration(5).

The provider corresponding to the registration then authenticates the end user and obtains authorization consent 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 context 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.

If no goto URL is specified in the request, the defaultLogoutGoto is used.

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 context 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": runtime expression<uri string>, required

The base URI for the filter. For example, if you set "clientEndpoint": "/openid", the service URIs for this filter on your IG server are /openid/login, /openid/logout, and /openid/callback. These endpoints are implicitly reserved. Attempts to access them directly can cause undefined errors.

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object. For example, it would be incorrect to use ${request.uri}, which is not a String but a MutableUri.

See also Expressions(5).

"failureHandler": handler reference, required

Provide an inline handler configuration object, or the name of a handler object that is defined in the heap.

When the OAuth 2.0 Resource Server denies access to a resource, the failure handler can be invoked only if the error response contains a WWW-Authenticate header (meaning that there was a problem with the OAuth 2.0 exchange). All other responses are forwarded to the user-agent without invoking the failure handler.

If the value of the WWW-Authenticate header is invalid_token, the OAuth2ClientFilter tries to refresh the access token:

• If the token is refreshed, the OAuth2ClientFilter tries again to access the protected resource.

• If the token is not refreshed, or if the second attempt to access the protected resource fails, the OAuth2ClientFilter invokes the failure handler.

When the failure handler is invoked, the target in the context can be populated with information such as the exception, client registration, and error. The failure object in the target is a simple map, similar to the following example:

{
    "client_registration": "ClientRegistration 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",
    "exception": exception
}

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"

See also Handlers.

"discoveryHandler": Handler reference, optional

Invoke this HTTP client handler to communicate with the OpenID Provider for OpenID Connect Discovery.

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.

Default: IG uses the default ClientHandler.

See also Handlers, ClientHandler(5).

"loginHandler": Handler reference, required if there are zero or multiple client registrations, optional if there is one client registration

Use this Handler when the user must choose an identity provider. When registrations contains only one client registration, this Handler is optional but is displayed if specified.

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

The route in "Example Configuration For Multiple Identity Providers" includes a login handler that allows the user to choose from two client registrations, openam and google. For an example of a login handler where no client registrations are defined, see "Preparing IG for Discovery and Dynamic Registration" in the Gateway Guide.

See also Handlers.

"registrations": Array of ClientRegistration references or inline ClientRegistration declarations, optional

List of client registrations that authenticate IG to the identity providers. The list must contain all client registrations that are to be used by the client filter.

The value represents a static client registration with an identity provider as described in ClientRegistration(5).

"metadata": client metadata object, required for dynamic client registration and ignored otherwise

This object holds client metadata as described in OpenID Connect Dynamic Client Registration 1.0, and optionally a list of scopes. See that document for additional details and a full list of fields.

This object can also hold client metadata as described in RFC 7591, OAuth 2.0 Dynamic Client Registration Protocol. See that RFC for additional details.

The following partial list of metadata fields is not exhaustive, but includes metadata that is useful with AM as OpenID Provider:

"redirect_uris": array of URI strings, required

The array of redirection URIs to use when dynamically registering this client.

"client_name": string, optional

Name of the client to present to the end user.

"scope": space separated string, optional

Space separated string of scopes to request of the OpenID Provider.

This property is available for dynamic client registration with AM from version 5.5, and with identity providers that support RFC 7591, OAuth 2.0 Dynamic Client Registration Protocol.

"scopes": array of strings, optional

Array of scope strings to request of the OpenID Provider.

This property is available for dynamic client registration with AM 5.5 and earlier versions only.

"cacheExpiration": duration string, optional

Duration for which to cache user-info resources.

IG lazily fetches user info from the OpenID provider. In other words, IG only fetches the information when a downstream Filter or Handler uses the user info. Caching allows IG 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, and 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, µs: microseconds

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

Default: 10 minutes

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

"executor": executor, optional

An executor service to schedule the execution of tasks, such as the eviction of entries in the OpenID Connect user information cache.

Default: ScheduledExecutorService

See also ScheduledExecutorService(5).

"target": expression, optional

An expression that yields the target object. Downstream filters and handlers can use data in the target to enrich the existing request or create a new request.

• If the authorization process completes successfully, the OAuth2ClientFilter injects the authorization state data into the target.

  In the following example, a downstream StaticRequestFilter retrieves the username and password from the target to log the user in to the sample application.

  {
    "type": "StaticRequestFilter",
    "config": {
      "method": "POST",
      "uri": "http://app.example.com:8081/login",
      "form": {
        "username": [
          "${attributes.openid.user_info.sub}"
        ],
         "password": [
          "${attributes.openid.user_info.family_name}"
        ]
      }
    }
  }

  For information about setting up this example, see "Adapting the Configuration to Authenticate Automatically to the Sample Application" in the Gateway Guide.

• If the failure handler is invoked, the target can be populated with information such as the exception, client registration, and error, as described in "failureHandler" in this reference page.

Default: ${attributes.openid}

See also Expressions(5).

"defaultLoginGoto": runtime expression<uri string>, optional

After successful authentication and authorization, if the user accesses the clientEndpoint/login endpoint without providing a landing page URL in the goto parameter, the request is redirected to this URI.

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object. For example, it would be incorrect to use ${request.uri}, which is not a String but a MutableUri.

Default: return an empty page.

See also Expressions(5).

"defaultLogoutGoto": runtime expression<uri string>, optional

If the user accesses the clientEndpoint/logout endpoint without providing a goto URL, the request is redirected to this URI.

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object. For example, it would be incorrect to use ${request.uri}, which is not a String but a MutableUri.

Default: return an empty page.

See also Expressions(5).

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

"issuerRepository": Issuer repository reference, optional

A repository of OAuth 2.0 issuers, built from discovered issuers and the IG configuration.

Provide the name of an IssuerRepository object defined in the heap.

Default: Look up an issuer repository named IssuerRepository in the heap. If none is explicitly defined, then a default one named IssuerRepository is created in the current route.

See also IssuerRepository(5).

"accessTokenResolver": AccessTokenResolver reference, optional

Resolves an access token against an authorization server.

Use OpenAmAccessTokenResolver, TokenIntrospectionAccessTokenResolver, or ScriptableAccessTokenResolver.

Default: OpenAmAccessTokenResolver

OpenAMAccessTokenResolver

Use the AM token info endpoint, /oauth2/tokeninfo, to resolve access tokens and retrieve information, such as scopes. This resolver is also compatible with Google token info endpoint.

"endpoint": URI string, required

The URI to the token information endpoint for resource servers. Use /oauth2/tokeninfo.

"providerHandler": Handler reference, optional

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.

Tip

To facilitate auditing, configure this handler with a ForgeRockClientHandler, which sends a ForgeRock Common Audit transaction ID when it communicates with protected applications.

Alternatively, configure this handler as a chain containing a TransactionIdOutboundFilter, as in the following configuration:

providerHandler : {
  "type" : "Chain",
  "config" : {
    "handler": "MySecureClientHandler",
    "filters": [ "TransactionIdOutboundFilter" ]
  }
}

Default: ForgeRockClientHandler

The following examples configure a OpenAMAccessTokenResolver:

"accessTokenResolver": {
  "type": "OpenAmAccessTokenResolver",
  "config": {
    "endpoint": "http://openam.example.com:8088/openam/oauth2/tokeninfo"
  }
}

For an example route using OpenAmAccessTokenResolver, see "Validating Access Tokens Through the Token Info Endpoint" in the Gateway Guide.

TokenIntrospectionAccessTokenResolver

Use the token introspection endpoint, /oauth2/introspect, to resolve access tokens and retrieve metadata about the token, such as approved scopes and the context in which the token was issued.

The introspection endpoint is defined as a standard method for resolving access tokens, in RFC-7662, OAuth 2.0 Token Introspection.

"endpoint": URI string, required

The URI to the token information endpoint for resource servers. Use /oauth2/introspect.

"providerHandler": Handler reference, optional

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.

Default: ForgeRockClientHandler

If you use the AM token introspection endpoint, this handler can be a Chain containing a HeaderFilter to add the authorization to the request header, as in the following example:

"providerHandler": {
  "type": "Chain",
  "config": {
    "filters": [
      {
        "type": "HeaderFilter",
        "config": {
          "messageType": "request",
          "add": {
            "Authorization": [ "Basic ${encodeBase64('<OAuth 2.0 client name>:<password>')}" ]
          }
        }
      }
    ],
    "handler": "ClientHandler"
  }
}

For an example route using TokenIntrospectionAccessTokenResolver, see "Validating Access Tokens Through the Introspection Endpoint" in the Gateway Guide.

ScriptableAccessTokenResolver

Receive a string representing an access token and use it to create an instance or promise of org.forgerock.http.oauth2.AccessTokenInfo.

"scopes": array of runtime expression<string>, required

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

See also Expressions(5).

"cache": object, optional

Introduced in IG 5.5.1

Configuration of caching for OAuth 2.0 access_tokens. By default, access_tokens are not cached.

When an access_token is cached, IG can reuse the token information without repeatedly asking the authorization server to verify the access_token. When caching is disabled, IG must ask the authorization server to verify the access_token for each request.

The following example caches access_tokens for these times:

• One hour, if the access_token doesn't provide a valid expiry value.

• The duration specified by the token expiry value, when the token expiry value is shorter than one day.

• One day, when the token expiry value is longer than one day.

"cache": {
  "enabled": true,
  "defaultTimeout": "1 hour",
  "maxTimeout": "1 day"
}

enabled: boolean, optional

Enable or disable caching.

Default: false

defaultTimeout: configuration expression<duration string>, optional

The duration for which to cache an OAuth 2.0 access_token if it doesn't provide a valid expiry value.

If an access_token provides an expiry value that falls before the current time plus the maxTimeout, IG uses the token expiry value.

Default: 1 minute

maxTimeout: configuration expression<duration string>, optional

The maximum duration for which to cache OAuth 2.0 access_tokens.

If an access_token provides an expiry value that falls after the current time plus the maxTimeout, IG uses the maxTimeout.

The duration cannot be zero or unlimited.

"cacheExpiration": duration string, optional

Deprecated in IG 5.5.1

The maximum duration for which to cache OAuth 2.0 access_tokens.

If an access_token provides an expiry value that falls after the current time plus the cacheExpiration, IG uses the cacheExpiration.

In IG 5.5.1, the duration cannot be zero or unlimited.

Default: 1 minute

"executor": executor, optional

An executor service to schedule the execution of tasks, such as the eviction of entries in the access token cache.

Default: ScheduledExecutorService

See also ScheduledExecutorService(5).

"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: IG

"request": request configuration object, required

The request that replays the credentials.

The request configuration object has the following fields:

"method": string, required

The HTTP method to be performed on the resource such as GET or POST.

"uri": string, required

The fully qualified URI of the resource to access such as http://www.example.com/login.

"entity": expression, optional

The entity body to include in the request.

This setting is mutually exclusive with the form setting when the method is set to POST.

See also Expressions(5).

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

This setting is mutually exclusive with the entity setting when the method is set to POST.

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

"version": string, optional

The HTTP protocol version.

Default: "HTTP/1.1".

The implementation uses a StaticRequestFilter. The fields are the same as those described in StaticRequestFilter(5).

"loginPage": runtime expression<boolean>, required unless loginPageContentMarker is defined

An expression that is true when a login page is requested, false otherwise.

For example, the following expression specifies that an HTTP GET to the path /login is a request for a login page:

${matches(request.uri.path, '/login') and (request.method == 'GET')}

IG evaluates the expression only for the request, not for the response.

See also Expressions(5).

"loginPageContentMarker": pattern, required unless loginPage is defined

A pattern that matches when a response entity is that of a login page.

See also Patterns(5).

"credentials": Filter reference, optional

Filter that injects credentials, making them available for replay. Consider using a FileAttributesFilter or a SqlAttributesFilter.

When this is not specified, credentials must be made available to the request by other means.

See also Filters.

"headerDecryption": crypto configuration object, optional

Object to decrypt request headers that contain credentials to replay.

The crypto configuration object has the following fields:

"key": expression, required

Base64 encoded key value.

See also Expressions(5).

"algorithm": string, optional

Algorithm used for decryption.

Use the same algorithm that is used to send the encrypted credentials. For example, to configure password replay with an AM agent and AM password capture, use the DES/ECB/NoPadding algorithm, which is used by AM to send encrypted credentials.

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

Default: Do not decrypt any headers.

"loginPageExtractions": extract configuration array, optional

Object to extract values from the login page entity.

The extract configuration array is a series of configuration objects. To extract multiple values, use multiple extract configuration objects. Each object has the following fields:

"name": string, required

Name of the field where the extracted value is put.

The names are mapped into attributes.extracted.

For example, if the name is nonce, the value can be obtained with the expression ${attributes.extracted.nonce}.

The name isLoginPage is reserved to hold a boolean that indicates whether the response entity is a login page.

"pattern": pattern, required

The regular expression pattern to find in the entity.

The pattern must contain one capturing group. (If it contains more than one, only the value matching the first group is placed into attributes.extracted.)

For example, suppose the login page entity contains a nonce required to authenticate, and the nonce in the page looks like nonce='n-0S6_WzA2Mj'. To extract n-0S6_WzA2Mj, set "pattern": " nonce='(.*)'".

See also Patterns(5).

"openamUrl": URI expression, required

The URL to an AM service, such as https://openam.example.com:8443/openam/.

See also Expressions(5).

"pepUsername": expression, required

The AM username of the user with permission to request policy decisions.

See also Expressions(5).

"pepPassword": expression, required

The AM password of the user with permission to request policy decisions.

See also Expressions(5).

"pepRealm": string, optional

The realm of the user with permission to request policy decisions.

Default: The value used by realm

"ssoTokenSubject": runtime expression<string>, required if neither of the following properties are present: "jwtSubject", "claimsSubject"

The AM SSO token ID string for the subject making the request to the protected resource.

See also Expressions(5).

"jwtSubject": runtime expression<string>, required if neither of the following properties are present: "ssoTokenSubject", "claimsSubject"

The JWT string for the subject making the request to the protected resource.

To use the raw id_token (base64, not decoded) returned by the OpenID Connect Provider during authentication, place an OAuth2ClientFilter filter before the PEP filter, and then use ${attributes.openid.id_token} as the expression value.

See also OAuth2ClientFilter(5) and Expressions(5).

"claimsSubject": map or runtime expression<map>, required if neither of the following properties are present: "jwtSubject", "ssoTokenSubject"

A representation of JWT claims for the subject. The subject must be specified, but the JWT claims can contain other information such as the token issuer, expiration, and so on.

If this property is a map, the structure must have the format Map<String, Object>. The value is evaluated as an expression.

"claimsSubject": {
  "sub": "${attributes.subject_identifier}",
  "iss": "openam.example.com"
}

If this property is an expression, its evaluation must give an object of type Map<String, Object>.

"claimsSubject": "${attributes.openid.id_token_claims}"

See also Expressions(5).

"amHandler": handler reference, optional

The handler to use when requesting policy decisions from AM.

In production, use a ClientHandler that is capable of making an HTTPS connection to AM.

Tip

To facilitate auditing, configure this handler with a ForgeRockClientHandler, which sends a ForgeRock Common Audit transaction ID when it communicates with protected applications.

Alternatively, configure this handler as a chain containing a TransactionIdOutboundFilter, as in the following configuration:

"amHandler" : {
  "type" : "Chain",
  "config" : {
    "handler": "MySecureClientHandler",
    "filters": [ "TransactionIdOutboundFilter" ]
  }
}

Default: ForgeRockClientHandler

See also Handlers, ClientHandler(5).

"realm": string, optional

The AM realm to use when requesting policy decisions.

Default: / (Top Level Realm)

"ssoTokenHeader": string, optional

The name of the HTTP header to use when supplying the SSO token ID for the user making a policy decision request.

Default: iPlanetDirectoryPro

"application": string, optional

The AM policy set to use when requesting policy decisions.

Default: Default Policy Set

cache: object, optional

The caching of AM policy decisions. By default, policy decisions are not cached.

Note

Cached policy decisions remain in the IG cache even after a user logs out of OpenAM and the OpenAM session becomes invalid.

Note

Policy decisions that contain advices are never cached.

The following code example caches AM policy decisions without advices for these times:

• One hour, when the policy decision doesn't provide a ttl value.

• The duration specified by the ttl, when ttl is shorter than one day.

• One day, when ttl is longer than one day.

"cache": {
  "enabled": true,
  "defaultTimeout": "1 hour",
  "maxTimeout": "1 day"
}

enabled: boolean, optional

Enable or disable caching of policy decisions.

Default: false

defaultTimeout: duration, optional

The default duration for which to cache AM policy decisions.

If an AM policy decision provides a valid ttl value to specify the time until which the policy decision remains valid, IG uses that value or the maxTimeout.

Default: 1 minute

maxTimeout: duration, optional

The maximum duration for which to cache AM policy decisions.

If the ttl value provided by the AM policy decision is after the current time plus the maxTimeout, IG uses the maxTimeout.

The duration cannot be zero or unlimited.

A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive, and 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, µs: microseconds

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

"environment": map or runtime expression<map>, optional

A list of strings to forward to AM with the request for a policy decision, that represent the environment (or context) of the request. Forward any HTTP header or any value that the AM policy definition can use.

AM can use the environment conditions to set the circumstances under which a policy applies. For example, environment conditions can specify that the policy applies only during working hours or only when accessing from a specific IP address.

If this property is a map, the structure must have the format Map<String, List<String>>. In the following example, the PolicyEnforcementFilter forwards standard and non-standard request headers, an ID token, and the IP address of the subject making the request:

"environment": {
  "H-Via": "${request.headers['Via']}",
  "H-X-Forwarded-For": "${request.headers['X-Forwarded-For']}",
  "H-myHeader": "${request.headers['myHeader']}",
  "id_token": [
    "${attributes.openid.id_token}"
  ],
    "IP": [
      "${contexts.client.remoteAddress}"
  ]
}

If this property is an expression, its evaluation must give an object of type Map<String, List<String>>.

"environment": "${attributes.my_environment}"

"executor": executor, optional

An executor service to schedule the execution of tasks, such as the eviction of entries in the policy decision cache.

Default: ScheduledExecutorService

See also ScheduledExecutorService(5).

"failureHandler": handler reference, optional

Handler to treat requests when they are denied by the policy decision.

In the following example, the failureHandler is a chain with a scriptable filter. If there are some advices with the policy decision, the script recovers the advices for processing. Otherwise, it passes the request to the StaticResponseHandler to display a message.

"failureHandler":{
  "type": "Chain",
  "config": {
    "filters": [
      {
        "type": "ScriptableFilter",
        "config": {
          "type": "application/x-groovy",
          "source": [
            "if (contexts.policyDecision.advices['MyCustomAdvice'] != null) {",
            "  return handleCustomAdvice(context, request)",
            "} else {",
            "  return next.handle(context, request)",
            "}"
          ]
        }
      }
    ],
    "handler" : {
      "type": "StaticResponseHandler",
      "config": {
        "status": 403,
        "entity": "Restricted area. You do not have sufficient privileges."
      }
    }
  }
}

Provide an inline handler configuration object, or the name of a handler object that is defined in the heap.

See also Handlers.

Default: HTTP 403 Forbidden, the request stops being executed.

"type": string, required

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

"file": expression

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 "Installing IG" in the Gateway Guide.

The base location for Groovy scripts is on the classpath when the scripts are executed. If 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 or array of strings, required if "file" is not used

The script as a string or array of strings; mutually exclusive with "file".

The following example shows the source of a script as an array of strings:

"source" : [
    "Response response = new Response(Status.OK)",
    "response.entity = 'foo'",
    "return response"
]

"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 status to I'm a teapot:

response.status = Status.valueOf(418, reason[1])

For details regarding this status code see RFC 7168, Section 2.3.3 418 I'm a Teapot.

Args parameters can reference objects defined in the heap using expressions. For example, the following excerpt shows the heap that defines SampleFilter:

{
    "heap": [
        {
            "name": "SampleFilter",
            "type": "SampleFilter",
            "config": {
                "name": "X-Greeting",
                "value": "Hello world"
            }
        }
    ]
}

Note

SampleFilter is a customized filter implemented as an extension of IG. For information about sample filter, see "Implementing a Customized Sample Filter" in the Gateway Guide.

To pass SampleFilter to the script, the following example uses an expression in the args parameters:

{
    "args": {
        "filter": "${heap['SampleFilter']}"
    }
}

The script can then reference SampleFilter as filter.

For details about the heap, see Heap Objects(5).

"clientHandler", ClientHandler reference, optional

A Handler for making outbound HTTP requests.

Default: Use the default ClientHandler.

For details, see Handlers.

"amHandler": Handler reference, optional

The handler to use when communicating with AM to validate the token in the incoming request.

In production, use a ClientHandler that can make HTTPS connections to AM.

Tip

To facilitate auditing, configure this handler with a ForgeRockClientHandler, which sends a ForgeRock Common Audit transaction ID when it communicates with protected applications.

Alternatively, configure this handler as a chain containing a TransactionIdOutboundFilter, as in the following configuration:

"amHandler" : {
  "type" : "Chain",
  "config" : {
    "handler": "MySecureClientHandler",
    "filters": [ "TransactionIdOutboundFilter" ]
  }
}

Default: ForgeRockClientHandler

See also Handlers, ClientHandler(5).

"cookieName" string, optional

The name of the cookie to use for authentication.

Default: iPlanetDirectoryPro

"defaultLogoutLandingPage": expression<uri>, optional

The URI to which a request is redirected after the user logs out of AM.

This parameter is effective only when logoutEndpoint is specified.

Default: None. Processing continues.

"loginEndpoint": URI expression, optional

The URL of a service to manage authentication, and the location to which the request is redirected after authentication. When this property is specified, the SingleSignOnFilter does not use openamUrl for the authentication URL.

Authentication can be performed in the following ways:

• Directly through AM, with optional authentication parameters in the query string, such as service, module, and realm. For a list of authentication parameters that you can include in the query string, see Authentication Parameters in the AM Authentication and Single Sign-On Guide.

  The value must include a redirect with a goto parameter, which is added by default when the openamUrl property is used for the authentication URL.

  The following example uses AM as the authentication service, and includes the service authentication parameter:

  "loginEndpoint" : "https://openam.example.com/openam?
  service=TwoFactor&goto=${urlEncodeQueryParameterNameOrValue(contexts.router.originalUri)}"

• Through the URL of another application, with optional authentication parameters in the query string, such as service, module, and realm. The application must create a session with an AM instance to set an SSO token and return the request to the redirect location.

  The value can optionally include a redirect with a goto parameter or different parameter name.

  The following example uses an authentication service that is not AM, and includes a redirect parameter:

  "loginEndpoint" : "https://authservice.example.com/auth?
  redirect=${urlEncodeQueryParameterNameOrValue(contexts.router.originalUri)}"

  When using this option, review the cookie domains to make sure that cookies set by the authentication server are properly conveyed to the IG instance.

Default: None.

"logoutEndpoint" pattern, optional

A string denoting a regular expression pattern for a URI path. When a request matches the pattern, IG performs the logout process and the AM authentication token for the end user is revoked.

If a defaultLogoutLandingPage is specified, the request is redirected to that page. Otherwise, the request continues to be processed.

Default: Logout is not managed by this filter.

"openamUrl": URI expression, required

The URL of an AM service to use for authentication. For example, use a URL such as https://openam.example.com:8443/openam/.

When loginEndpoint is specified, the SingleSignOnFilter does not use openamUrl for the authentication URL.

See also Expressions(5).

"realm": string, optional

The AM realm to use for authentication.

Default: / (Top Level Realm)

"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 runtime expressions<string>, optional

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

See also Expressions(5).

"target": lvalue-expression, required

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

See also Expressions(5).

"method": string, required

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

"uri": runtime expression<string>, required

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

The result of the expression must be a string that represents a valid URI, but is not a real java.net.URI object. For example, it would be incorrect to use ${request.uri}, which is not a String but a MutableUri.

"version": string, optional

Protocol version. Default: "HTTP/1.1".

"headers": object, optional

Header fields to set in the request, with the format name: [ value, ... ].

The name field of headers specifies the header name. It can be defined by a configuration expression or string. If the configuration expressions for multiple name resolve to the same final string, multiple values are associated with the name.

The value field of headers is an array of runtime expressions to evaluate as header values.

In the following example, the name of the header is the value of the configuration time, system variable defined in cookieHeaderName. The value of the header is the runtime value stored in contexts.ssoToken.value:

"headers": {
  "${application['header1Name']}": [
    "${application['header1Value'}"
  ]

"form": object, optional

A form to include in the request, with the format param: [ value, ... ].

The param field of form specifies the name of the form parameter. It can be defined by a configuration expression or string. If the configuration expressions for multiple param resolve to the same final string, multiple values are associated with the param.

The value field of form is an array of runtime expressions to evaluate as form field values.

When the method is set to POST, this setting is mutually exclusive with the entity setting.

In the following example, the names of the field parameters and the values are hardcoded in the form:

"form": {
  "username": [
    "demo"
  ],
  "password": [
    "changeit"
  ]

In the following example, the names of the field parameters are hardcoded. The values take the first value of username and password provided in the session:

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

In the following example, the name of the first field param take the value of the expression ${application['formName']} when it is evaluated at startup. The values take the first value of username and password provided in the session:

"form": {
  "${application['formName']}": [
    "${session.username[0]}"
  ],
  "${application['formPassword']}": [
    "${session.password[0]}"
  ]

"entity": runtime expression<string>, optional

The entity body to include in the request.

This setting is mutually exclusive with the form setting when the method is set to POST.

See also Expressions(5).

"onRequest": array of objects, optional

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

"onResponse": array of objects, optional

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

"condition": runtime expression<boolean>, optional

If the expression evaluates to true, the request is dispatched to the handler. If no condition is specified, the request is dispatched to the handler unconditionally.

Default: No condition is specified.

See also Expressions(5).

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

See also Handlers.

"openamUri": URI expression, required

The base URL to an AM service, such as https://openam.example.com:8443/openam/. This expression is evaluated when the route is initialized.

Authentication and REST STS requests are made to this service.

"realm": expression, optional

The AM realm containing both the AM user who can make the REST STS request and whose credentials are the username and password, and the STS instance described by the instance field. This expression is evaluated when the route is initialized.

Default: / (Top Level Realm)

"username": expression, required

The username for authenticating IG as an AM REST STS client. This expression is evaluated when the route is initialized.

See also Expressions(5).

"password": expression, required

The password for authenticating IG as an AM REST STS client. This expression is evaluated when the route is initialized.

See also Expressions(5).

"idToken": runtime expression<string>, required

The value of the OpenID Connect ID token. The expected value is a string that is the JWT encoded id_token.

See also Expressions(5).

"instance": expression, required

An expression evaluating to the name of the REST STS instance.

This expression is evaluated when the route is initialized, so the expression cannot refer to request or contexts.

See also Expressions(5).

"amHandler": Handler reference, optional

The handler to use for authentication and STS requests to AM.

In production, use a ClientHandler that is capable of making an HTTPS connection to AM.

Tip

To facilitate auditing, configure this handler with a ForgeRockClientHandler, which sends a ForgeRock Common Audit transaction ID when it communicates with protected applications.

Alternatively, configure this handler as a chain containing a TransactionIdOutboundFilter, as in the following configuration:

"amHandler" : {
  "type" : "Chain",
  "config" : {
    "handler": "MySecureClientHandler",
    "filters": [ "TransactionIdOutboundFilter" ]
  }
}

Default: ForgeRockClientHandler

See also Handlers, ClientHandler(5).

"ssoTokenHeader": string, optional

The name of the HTTP header to use when supplying the SSO token ID for the REST STS client subject.

Default: iPlanetDirectoryPro

"protectionApiHandler": Handler reference, required

The handler to use when interacting with the UMA authorization server for token introspection and permission requests, such as a ClientHandler capable of making an HTTPS connection to the server.

For details, see Handlers.

"umaService": UmaService reference, required

The UmaService to use when protecting resources.

For details, see UmaService(5).

"realm": string, optional

The UMA realm set in the response to a request for a protected resource that does not include a requesting party token enabling access to the resource.

Default: uma

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

See also Filters and Handlers.

"config": object, required unless empty

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

decorator name: string, required

A string representing the scheme, host, and port of the new base URI. The port is optional when using the defaults (80 for HTTP, 443 for HTTPS).

IG ignores this setting if the value is not a string.

The decorator configuration has these properties:

"captureEntity": boolean, optional

Whether the message entity should be captured. The message entity is the body of the HTTP message, which can be a JSON document, XML, HTML, image, or other information.

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

Default: false

"captureContext": boolean, optional

Whether the context should be captured as JSON. The context chain is used when processing the request inside IG in the filters and handlers.

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.

See also Filters and Handlers.

"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

"timeUnit": duration string, optional

Unit of time used in the decorator output. The unit of time can be any unit allowed in the duration field. For information, see duration.

Default: ms

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

See also Filters and Handlers.

"config": object, required unless empty

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

decorator name: boolean, required

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

"config": object, required

This object configures the audit service itself, rather than event handlers. If the configuration uses only default settings, you can omit the field instead of including an empty object as the field value.

The configuration object has the following fields:

"handlerForQueries": string, optional

This references the name of the event handler to use when querying audit event messages over REST.

"availableAuditEventHandlers": array of strings, optional

This lists fully qualified event handler class names for event handlers available to the audit service.

"caseInsensitiveFields": array of strings, optional

A list of audit event fields to be considered as case-insensitive for filtering. The fields are referenced using JSON pointer syntax. The list can be null or empty.

Default: Audit event fields are considered as case-sensitive for filtering.

"filterPolicies": object, optional

These policies indicate what fields and values to include and to exclude from audit event messages.

The filter policies object has these fields:

"field": object, optional

Audit event fields use JSON pointer notation, and are taken from the JSON schema for the audit event content.

Default: Include all fields.

The field object specifies which fields to include and to exclude:

"excludeIf": array of strings, optional

This holds a list of audit event fields to exclude.

"includeIf": array of strings, optional

This holds a list of audit event fields to include.

"value": object, optional

Default: Include all messages.

The value object specifies field values based on which messages are included and excluded:

"excludeIf": array of strings, optional

This holds a list of audit event field values.

When a value matches, the message is excluded.

"includeIf": array of strings, optional

This holds a list of audit event field values.

When a value matches, the message is included.

"event-handlers": array of configuration objects, required

This array of audit event handler configuration objects defines the event handlers that deal with audit events.

Each event handler configuration depends on type of the event handler. IG supports the event handlers described in Audit Framework.

The "config" object has the following properties:

"name": string, required

The name of the event handler.

"logDirectory": string, required

The file system directory where log files are written.

"topics": array of strings, required

The topics that this event handler intercepts.

IG handles access events that occur at the system boundary, such as arrival of the initial request and departure of the final response.

Set this to "topics": [ "access" ].

"enabled": boolean, optional

Whether this event handler is active.

Default: true.

"formatting": object, optional

Formatting settings for CSV log files.

The formatting object has the following fields:

"quoteChar": single-character string, optional

The character used to quote CSV entries.

Default: ".

"delimiterChar": single-character string, optional

The character used to delimit CSV entries.

Default: ,.

"endOfLineSymbols": string, optional

The character or characters that separate a line.

Default: system-dependent line separator defined for the JVM.

"buffering": object, optional

Buffering settings for writing CSV log files. The default is for messages to be written to the log file for each event.

The buffering object has the following fields:

"enabled": boolean, optional

Whether log buffering is enabled.

Default: false.

"autoFlush": boolean, optional

Whether events are automatically flushed after being written.

Default: true.

"security": object, optional

Security settings for CSV log files. These settings govern tamper-evident logging, whereby messages are signed. By default tamper-evident logging is not enabled.

The security object has the following fields:

"enabled": boolean, optional

Whether tamper-evident logging is enabled.

Default: false.

Tamper-evident logging depends on a specially prepared keystore. For details, see "Preparing a Keystore for Tamper-Evident Logs".

"filename": string, required

File system path to the keystore containing the private key for tamper-evident logging.

The keystore must be a keystore of type JCEKS. For details, see "Preparing a Keystore for Tamper-Evident Logs".

"password": string, required

The password for the keystore for tamper-evident logging.

This password is used for the keystore and for private keys. For details, see "Preparing a Keystore for Tamper-Evident Logs".

"signatureInterval": duration, required

The time interval after which to insert a signature in the CSV file. This duration must not be zero, and must not be unlimited.

A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive, and 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, µs: microseconds

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

"fileRetention": object, optional

File retention settings for CSV log files.

The file retention object has the following fields:

"maxDiskSpaceToUse": number, optional

The maximum disk space in bytes the audit logs can occupy. A setting of 0 or less indicates that the policy is disabled.

Default: 0.

"maxNumberOfHistoryFiles": number, optional

The maximum number of historical log files to retain. A setting of -1 disables pruning of old history files.

Default: 0.

"minFreeSpaceRequired": number, optional

The minimum free space in bytes that the system must contain for logs to be written. A setting of 0 or less indicates that the policy is disabled.

Default: 0.

"fileRotation": object, optional

File rotation settings for CSV log files.

The file rotation object has the following fields:

"rotationEnabled": boolean, optional

Whether file rotation is enabled for CSV log files.

Default: false.

"maxFileSize": number, optional

The maximum file size of an audit log file in bytes. A setting of 0 or less indicates that the policy is disabled.

Default: 0.

"rotationFilePrefix": string, optional

The prefix to add to a log file on rotation.

This has an effect when time-based file rotation is enabled.

"rotationFileSuffix": string, optional

The suffix to add to a log file on rotation, possibly expressed in SimpleDateFormat.

This has an effect when time-based file rotation is enabled.

Default: -yyyy.MM.dd-HH.mm.ss, where yyyy characters are replaced with the year, MM characters are replaced with the month, dd characters are replaced with the day, HH characters are replaced with the hour (00-23), mm characters are replaced with the minute (00-60), and ss characters are replaced with the second (00-60).

"rotationInterval": duration, optional

The time interval after which to rotate log files. This duration must not be zero.

This has the effect of enabling time-based file rotation.

A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive, and 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, µs: microseconds

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

"rotationTimes": array of durations, optional

The durations, counting from midnight, after which to rotate files.

The following example schedules rotation six and twelve hours after midnight:

"rotationTimes": [ "6 hours", "12 hours" ]

This has the effect of enabling time-based file rotation.

A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive, and 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, µs: microseconds

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

"rotationRetentionCheckInterval": duration, optional

The time interval after which to check file rotation and retention policies for updates.

Default: 5 seconds

A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive, and 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, µs: microseconds

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

The "config" object has the following properties:

"connection": object, optional

Connection settings for sending messages to Elasticsearch. If this object is not configured, it takes default values for its fields. This object has the following fields:

"host": string, optional

Hostname or IP address of Elasticsearch.

Default: localhost

"port": number, optional

The port used by Elasticsearch. The value must be between 0 and 65535.

Default: 9200

"useSSL": boolean, optional

Setting to use or not use SSL/TLS to connect to Elasticsearch.

Default: false

"username": string, optional

Username when Basic Authentication is enabled through Elasticsearch Shield.

"password": string, optional

Password when Basic Authentication is enabled through Elasticsearch Shield.

"indexMapping": object, optional

Defines how an audit event and its fields are stored and indexed.

"indexName": string, optional

The index name. Set this parameter if the default name audit conflicts with an existing Elasticsearch index.

Default: audit.

"buffering": object, optional

Settings for buffering events and batch writes.

"enabled": boolean, optional

Setting to use or not use log buffering.

Default: false.

"writeInterval": duration

The interval at which to send buffered event messages to Elasticsearch. If buffering is enabled, this interval must be greater than 0.

Default: 1 second

A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive, and 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, µs: microseconds

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

"maxBatchedEvents": number, optional

The maximum number of event messages in a batch write to Elasticsearch for each writeInterval.

Default: 500

"maxSize": number, optional

The maximum number of event messages in the queue of buffered event messages.

Default: 10000

"topics": array of strings, required

The topics that this event handler intercepts.

IG handles access events that occur at the system boundary, such as arrival of the initial request and departure of the final response.

Set this to "topics": [ "access" ].

The "config" object has the following properties:

"name": string, required

The name of the event handler.

"topics": array of strings, required

The topics that this event handler intercepts.

IG handles access events that occur at the system boundary, such as arrival of the initial request and departure of the final response.

Set this to "topics": [ "access" ].

"databaseType": string, required

The database type name.

Built-in support is provided for oracle, mysql, and h2. Unrecognized database types rely on a GenericDatabaseStatementProvider.

"enabled": boolean, optional

Whether this event handler is active.

Default: true.

"buffering": object, optional

Buffering settings for sending messages to the database. The default is for messages to be written to the log file for each event.

The buffering object has the following fields:

"enabled": boolean, optional

Whether log buffering is enabled.

Default: false.

"writeInterval": duration, required

The interval at which to send buffered event messages to the database.

This interval must be greater than 0 if buffering is enabled.

A duration is a lapse of time expressed in English, such as 23 hours 59 minutes and 59 seconds. Durations are not case sensitive, and 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, µs: microseconds

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

"autoFlush": boolean, optional

Whether the events are automatically flushed after being written.

Default: true.

"maxBatchedEvents": number, optional

The maximum number of event messages batched into a PreparedStatement.

Default: 100.

"maxSize": number, optional

The maximum size of the queue of buffered event messages.

Default: 5000.

"writerThreads": number, optional

The number of threads to write buffered event messages to the database.

Default: 1.

"connectionPool": object, required

Connection pool settings for sending messages to the database.

The connection pool object has the following fields:

"dataSourceClassName": string, optional

The class name of the data source for the database.

"jdbcUrl": string, required

The JDBC URL to connect to the database.

"username": string, required

The username identifier for the database user with access to write the messages.

"password": number, optional

The password for the database user with access to write the messages.

"autoCommit": boolean, optional

Whether to commit transactions automatically when writing messages.

Default: true.

"connectionTimeout": number, optional

The number of milliseconds to wait for a connection from the pool before timing out.

Default: 30000.

"idleTimeout": number, optional

The number of milliseconds to allow a database connection to remain idle before timing out.

Default: 600000.

"maxLifetime": number, optional

The number of milliseconds to allow a database connection to remain in the pool.

Default: 1800000.

"minIdle": number, optional

The minimum number of idle connections in the pool.

Default: 10.

"maxPoolSize": number, optional

The maximum number of connections in the pool.

Default: 10.

"poolName": string, optional

The name of the connection pool.

"tableMappings": array of objects, required

Table mappings for directing event content to database table columns.

A table mappings object has the following fields:

"event": string, required

The audit event that the table mapping is for.

Set this to access.

"table": string, required

The name of the database table that corresponds to the mapping.

"fieldToColumn": object, required

This object maps the names of audit event fields to database columns, where the keys and values are both strings.

Audit event fields use JSON pointer notation, and are taken from the JSON schema for the audit event content.

For a full list of properties in the "config" object, see Configuration Properties for the JMS Audit Event Handler in the IDM Integrator's Guide.

"name": string, required

The name of the event handler.

"topics": array of strings, required

The topics that this event handler intercepts.

IG handles access events that occur at the system boundary, such as arrival of the initial request and departure of the final response.

Set this to "topics": [ "access" ].

"deliveryMode": string, required

Delivery mode for messages from a JMS provider. Set to PERSISTENT or NON_PERSISTENT.

"sessionMode": string, required

Acknowledgement mode in sessions without transactions. Set to AUTO, CLIENT, or DUPS_OK.

"contextProperties": map, optional

Settings with which to populate the initial context.

The following properties are required when ActiveMQ is used as the message broker:

• java.naming.factory.initial

  For example, "org.apache.activemq.jndi.ActiveMQInitialContextFactory".

  To substitute a different JNDI message broker, change the JNDI context properties.

• java.naming.provider.url

  For example, "tcp://127.0.0.1:61616".

  To configure the message broker on a remote system, substitute the associated IP address.

  To set up SSL, set up keystores and truststores, and change the value of the java.naming.provider.url to:

  ssl://127.0.0.1:61617?daemon=true&socket.enabledCipherSuites=SSL_RSA_WITH_RC4_128_SHA,SSL_DH_anon_WITH_3DES_EDE_CBC_SHA

• topic.audit

  For example, "audit".

To use the JMS resources provided by your application server, leave this field empty. The values for topicName and connectionFactoryName are then JNDI names that depend on the configuration of your application server.

"topicName": string, required

JNDI lookup name for the JMS topic.

For ActiveMQ, this property must be consistent with the value of topic.audit in contextProperties.

"connectionFactoryName": string, required

JNDI lookup name for the JMS connection factory.