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

"logSink": LogSink reference, optional

Send log messages to this LogSink.

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

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

"temporaryStorage": TemporaryStorage reference, optional

Cache content during processing based on this TemporaryStorage configuration.

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

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

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.

OpenIG automatically creates some configuration objects that it needs for its own use. An automatically created object can be overridden by creating a heap object with the same name. Automatically created objects include the following:

"ApiProtectionFilter"

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

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

To override this filter, declare a different filter with the same name in the top-level heap found in config.json.

"LogSink"

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

Default: A ConsoleLogSink object named "LogSink" 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 LogSink heap object with the same name.

See also ConsoleLogSink(5).

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

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

"logSink": string

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

Default: LogSink.

"temporaryStorage": string

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

Default: TemporaryStorage.

"filters": array of Filter references, required

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

The chain dispatches 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 once the request has traversed all of the specified filters.

See also Handlers.

"connections": number, optional

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

Default: 64

"connectionTimeout": duration string, optional

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

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

Durations are not case sensitive.

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

Default: 10 seconds

"disableRetries": boolean, optional

Whether to disable automatic retries for failed requests.

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

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

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

Default: 10 seconds

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

"bindings": array of objects, required

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

"condition": expression, optional

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

See also Expressions(5).

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

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

Default: leave URI untouched.

"handler": Handler reference, required

For this route, dispatch the 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": expression, optional

Whether the route accepts to handle the request.

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

All paths starting with /openig are reserved for administrative use by OpenIG. 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, an 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 over REST as described in "The REST API for Monitoring".

Default: false (with percentiles 0.999, 0.9999, and 0.99999)

Use an object instead of a boolean to specify percentiles:

{
    "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 ]

"name": string, optional

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

Default: Route configuration file name

"session": Session reference, optional

Session storage implementation used by this route, such as a JwtSession 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

Default handler for this Router.

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

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

Default: if no default route is set either here or in the route configurations, then OpenIG aborts the 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 Section 3.3, "Installing OpenIG" in the Gateway Guide.

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

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

Default: 10 (seconds)

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

"assertionMapping": object, required

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

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

The following shows an example of an assertionMapping object:

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

If the incoming assertion contains the statement:

mail = george@example.com

mailPassword = costanza

Then the following values are set in the session:

username = george@example.com

password = costanza

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

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

"redirectURI": string, required

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

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

"assertionConsumerEndpoint": string, optional

Default: fedletapplication (same as the Fedlet)

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

"authnContext": string, optional

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

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

As an example, if you set "authnContext": "myAuthnContext", then OpenIG 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. Avoid using dot characters (.) in the field name, as the . character also serves as a query separator in expressions.

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

As an example, if you set "sessionIndexMapping": "mySessionIndex", then OpenIG 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. Avoid using dot characters (.) in the field name, as the . character also serves as a query separator in expressions.

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

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

The script has access to the following global objects:

Any parameters passed as args

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

Take care when naming keys in the args object. Attempts to reuse the name of another global object cause the script to fail and OpenIG to return a response with HTTP status code 500 Internal Server Error.

attributes

The attributes object provides access to a context map of arbitrary attributes, which is a mechanism for transferring transient state between components when processing a single request.

Use session for maintaining state between successive requests from the same logical client.

context

The processing context.

This context is the leaf of a chain of Contexts. It provides access to other Context types, such as SessionContext, AttributesContext, and ClientContext, through the context.asContext(ContextClass.class) method.

request

The HTTP request.

globals

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

http

An embedded client for making outbound HTTP requests, which is an org.forgerock.http.Client.

If a "clientHandler" is set in the configuration, then that Handler is used. Otherwise, the default ClientHandler configuration is used.

For details, see Handlers.

ldap

The ldap object provides an embedded LDAP client.

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

logger

The logger object provides access to the server log sink.

session

The session object provides access to the session context, which is a mechanism for maintaining state when processing a successive requests from the same logical client or end-user.

Use attributes for transferring transient state between components when processing a single request.

"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 Section 3.3, "Installing OpenIG" in the Gateway Guide.

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

"source": string

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

"args": map, optional

Parameters passed from the configuration to the script.

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

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

The script can then access the args parameters in the same way as other global objects. The following example sets the response 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": expression, optional

Evaluated to determine if the sequence continues.

Default: unconditional.

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

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

"entity": expression, optional

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

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

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

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

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

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

See also Expressions(5).

"managed": array of strings, optional

A list of the names of cookies to be managed.

"suppressed": array of strings, optional

A list of the names of cookies to be suppressed.

"relayed": array of strings, optional

A list of the names of cookies to be relayed.

"defaultAction": string, optional

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

"messageType": string, required

Indicates the type of message 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 the file is encoded in. 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

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

"fields": array of strings, optional

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

"target": lvalue-expression, required

Expression that yields the target object to contain the record.

The target object is a Map<String, String>, where the fields are the keys. For example, if the target is ${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 name of the field in the file to perform the lookup on.

"value": expression, required

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

See also Expressions(5).

"messageType": string, 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 name specifies the header name, with an associated array of string values.

"username": expression, required

Expression that yields the username to supply during authentication.

See also Expressions(5).

"password": expression, required

Expression that yields 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 to cache credentials in the session after the first successful authentication, and then replay those credentials for subsequent authentications in the same session.

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

Default: true

"baseURI": expression, optional

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

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

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": expression, required

Base URI for the filter.

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

See also Expressions(5).

"failureHandler": Handler reference, required

Invoke this Handler if authentication fails.

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

If this handler is invoked, then the target in the context is populated with information about the client registration, and the error

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

{
    "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"
}
     

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: OpenIG uses the default ClientHandler.

See also Handlers, ClientHandler(5).

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

Invoke this Handler the user must choose a provider.

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

This handler allows the user to choose a client registration, as in the following example that allows the user to choose between openam and google:

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

See also Handlers.

"registration": ClientRegistration reference, required when a single provider is configured

Use this ClientRegistration to authenticate OpenIG with the provider.

The value represents a static client registration with a 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 OpenAM 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.

"scopes": array of strings, optional

Array of scope strings to request of the OpenID Provider.

"cacheExpiration": duration string, optional

Duration for which to cache user-info resources.

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

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

Durations are not case sensitive.

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

Default: 20 seconds

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

"target": expression, optional

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

Default: ${attributes.openid}

See also Expressions(5).

"defaultLoginGoto": expression, optional

The URI to redirect to after successful authentication and authorization.

Default: return an empty page.

See also Expressions(5).

"defaultLogoutGoto": expression, optional

The URI to redirect to after successful logout.

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.

"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: OpenIG uses the default ClientHandler.

See also Handlers, ClientHandler(5).

"scopes": array of expressions, required

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

See also Expressions(5).

"tokenInfoEndpoint": URL string, required

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

"cacheExpiration": duration string, optional

Duration for which to cache OAuth 2.0 access tokens.

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

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

Durations are not case sensitive.

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

Default: 1 minute

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

"requireHttps": boolean, optional

Whether to require that requests use the HTTPS scheme.

Default: true

"realm": string, optional

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

Default: OpenIG

"target": expression, optional

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

Default: ${attributes.oauth2AccessToken}

See also Expressions(5).

"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": expression, 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')}

OpenIG only evaluates the expression 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.

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 OpenAM service, such as https://openam.example.com:8443/openam/.

See also Expressions(5).

"pepUsername": expression, required

The OpenAM username of a user with access to request policy decisions.

See also Expressions(5).

"pepPassword": expression, required

The OpenAM password of the user with access to request policy decisions.

See also Expressions(5).

"ssoTokenSubject": expression, required if "jwtSubject" is missing

An expression evaluating to the OpenAM SSO token ID string for the subject making the request to the protected resource.

See also Expressions(5).

"jwtSubject": expression, required if "ssoTokenSubject" is missing

An expression evaluating to the JWT string for the subject making the request to the protected resource.

See also Expressions(5).

"policiesHandler": Handler reference, optional

The handler to use when requesting policy decisions from OpenAM.

Default: OpenIG uses the default ClientHandler.

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

See also Handlers.

"realm": string, optional

The OpenAM 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 OpenAM application to use when requesting policy decisions.

Default: OpenIG does not specify an application when making a policy decision request. As a result, the application is iPlanetAMWebAgentService, which is the default for OpenAM.

"cacheMaxExpiration": duration string, optional

Maximum duration for which to cache policy decision responses. If the time-to-live value in the policy decision response is shorter, then OpenIG expires the decision according to the shorter lifetime.

This setting prevents OpenIG from having to issue a new request for every policy decision, including even repeated requests by the same subject for the same resource.

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

Durations are not case sensitive.

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

Default: 1 minute

The script has access to the following global objects:

Any parameters passed as args

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

Take care when naming keys in the args object. If you reuse the name of another global object, cause the script to fail and OpenIG to return a response with HTTP status code 500 Internal Server Error.

attributes

The attributes object provides access to a context map of arbitrary attributes, which is a mechanism for transferring transient state between components when processing a single request.

Use session for maintaining state between successive requests from the same logical client.

context

The processing context.

This context is the leaf of a chain of Contexts. It provides access to other Context types, such as SessionContext, AttributesContext, and ClientContext, through the context.asContext(ContextClass.class) method.

request

The HTTP request.

globals

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

http

An embedded client for making outbound HTTP requests, which is an org.forgerock.http.Client.

If a "clientHandler" is set in the configuration, then that Handler is used. Otherwise, the default ClientHandler configuration is used.

For details, see Handlers.

ldap

The ldap object provides an embedded LDAP client.

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

logger

The logger object provides access to the server log sink.

next

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

session

The session object provides access to the session context, which is a mechanism for maintaining state when processing a successive requests from the same logical client or end-user.

Use attributes for transferring transient state between components when processing a single request.

"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 Section 3.3, "Installing OpenIG" in the Gateway Guide.

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

"source": string

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

"args": object, optional

Parameters passed from the configuration to the script.

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

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

The script can then access the args parameters in the same way as other global objects. The following example sets the response 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.

"dataSource": string, required

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

"preparedStatement": string, required

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

"parameters": array of expressions, optional

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

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": string, required

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

"version": string, optional

Protocol version. Default: "HTTP/1.1".

"headers": object, optional

Header fields to set in the request.

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

"form": object, optional

A form to include in the request.

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

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

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

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

Condition to evaluate to determine if the request or response should be dispatched to the handler.

Default: unconditional dispatch to the handler.

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.

"rate": rate object, required

Defines a threshold rate of operations. When the threshold rate per partition is reached, OpenIG limits requests to the handler or responses to the client.

Rate is calculated as the number of operations divided by the duration. Both the "numberOfRequests" and the "duration" fields are required.

The number of requests is expressed as an integer.

The duration is expressed using duration syntax.

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

Durations are not case sensitive.

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

"partitionKey": expression, optional

Expression to evaluate whether a request matches when calculating a rate for a group of requests.

The partition key is a mechanism for grouping operations by their properties, effectively giving a name to the group. For example, the key ${contexts.client.remoteAddress} could resolve to the address of internal-client.example.com for operations where the request came from the host named internal-client.example.com, and the address of proxy.example.com for requests coming through the host named proxy.example.com, effectively splitting the requests into two groups for throttling purposes.

Default: all operations belong to the same group, and so all operations on the current route are limited by the specified rate.

See also Expressions(5).

"openamUri": URL string, required

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

Authentication and REST STS requests are made to this service.

"realm": string, optional

The OpenAM realm containing both the OpenAM 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.

Default: / (Top Level Realm)

"username": expression, required

The username for authenticating OpenIG as an OpenAM REST STS client.

See also Expressions(5).

"password": expression, required

The password for authenticating OpenIG as an OpenAM REST STS client.

See also Expressions(5).

"idToken": expression, required

An expression evaluating to OpenID Connect ID token.

The expected value is a string that is the JWT encoded id_token.

See also Expressions(5).

"target": expression, required

An expression evaluating to the location where the SAML 2.0 assertion is injected following successful transformation.

The value of the SAML 2.0 assertion is a string.

See also Expressions(5).

"instance": expression, required

An expression evaluating to 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, required

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

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

See also Handlers.

"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

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

event.data

A reference to the data involved in the event, providing access to the request, response, and contexts objects.

event.source

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

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

event.tags

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

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

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

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

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

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

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

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

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

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

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

event.timestamp

Timestamp indicating when the event happened, with millisecond precision.

"name": string, required except for inline objects

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

"type": string, required

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

See also Filters and Handlers.

"config": object, required unless empty

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

"audit": string or array of strings, required

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

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

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

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

The decorator configuration has these properties:

"logSink": LogSink reference, optional

Capture requests and responses to this LogSink.

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

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

"captureEntity": boolean, optional

Whether the message entity should be captured.

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

Default: false

"captureContext": boolean, optional

Whether the context should be captured as JSON.

Default: false

"name": string, required except for inline objects

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

"type": string, required

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

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

"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

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

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

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

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

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

OpenIG supports the following audit event handlers:

• CsvAuditEventHandler(5)

• JdbcAuditEventHandler(5)

• SyslogAuditEventHandler(5)

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.

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

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

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

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

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

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

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

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

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.

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

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

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

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.

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

"protocol": string, required

The transport protocol used to send event messages to the Syslog daemon.

Set this to TCP for Transmission Control Protocol, or to UDP for User Datagram Protocol.

"host": string, required

The hostname of the Syslog daemon to which to send event messages. The hostname must resolve to an IP address.

"port": number, required

The port of the Syslog daemon to which to send event messages.

The value must be between 0 and 65535.

"connectTimeout": number, required when using TCP

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

"facility": string, required

The Syslog facility to use for event messages.

Set this to one of the following values:

kern

Kernel messages

user

User-level messages

mail

Mail system

daemon

System daemons

auth

Security/authorization messages

syslog

Messages generated internally by syslogd

lpr

Line printer subsystem

news

Network news subsystem

uucp

UUCP subsystem

cron

Clock daemon

authpriv

Security/authorization messages

ftp

FTP daemon

ntp

NTP subsystem

logaudit

Log audit

logalert

Log alert

clockd

Clock daemon

local0

Local use 0

local1

Local use 1

local2

Local use 2

local3

Local use 3

local4

Local use 4

local5

Local use 5

local6

Local use 6

local7

Local use 7

"buffering": object, optional

Buffering settings for writing to the system log facility. The default is for messages to be written to the log for each event.

The buffering object has the following fields:

"enabled": boolean, optional

Whether log buffering is enabled.

Default: false.

"maxSize": number, optional

The maximum number of buffered event messages.

Default: 5000.

"severityFieldMappings": object, optional

Severity field mappings set the correspondence between audit event fields and Syslog severity values.

The severity field mappings object has the following fields:

"topic": string, required

The audit event topic to which the mapping applies.

Set this to access.

"field": string, required

The audit event field to which the mapping applies.

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

"valueMappings": object, required

The map of audit event values to Syslog severities, where both the keys and the values are strings.

Syslog severities are one of the following values:

emergency

System is unusable.

alert

Action must be taken immediately.

critical

Critical conditions.

error

Error conditions.

warning

Warning conditions.

notice

Normal but significant condition.

informational

Informational messages.

debug

Debug-level messages.

The client registration configuration object properties are as follows:

"name": string, required

A name for the client registration.

"clientId": expression, required

The client_id obtained when registering with the authorization server.

See also Expressions(5).

"clientSecret": expression, required

The client_secret obtained when registering with the authorization server.

See also Expressions(5).

"issuer": Issuer reference, required

The provider configuration to use for this client registration.

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

See also Issuer(5).

"redirect_uris": array of URI strings, required

The array of redirection URIs to use for this client registration.

At least one redirection URI must be specified.

"registrationHandler": Handler reference, optional

Invoke this HTTP client handler to communicate with the authorization server.

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: OpenIG uses the default ClientHandler.

See also Handlers, ClientHandler(5).

"scopes": array of expressions, optional

OAuth 2.0 scopes to use with this client registration.

See also Expressions(5).

"tokenEndpointUseBasicAuth": boolean, optional

Whether to perform client authentication to the provider using HTTP Basic authentication when sending a request to the provider's OAuth 2.0 token endpoint.

When set to true, the client credentials are sent using HTTP Basic authentication as in the following example request:

POST /oauth2/token HTTP/1.1
Host: as.example.com
Authorization: Basic ....
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...
     

When set to false, the client credentials are sent in HTTP POST form data as in the following example request:

POST /oauth2/token HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=.....&client_secret=.....&code=...
     

Some providers accept both authentication methods. For providers that strictly enforce how the client must authenticate, such as recent versions of OpenAM, you must align the configuration with that of the provider.

If the provider does not support the configured authentication method, then according to RFC 6749 The OAuth 2.0 Authorization Framework, section 5.2 the provider sends an HTTP 400 Bad Request response with an invalid_client error message as in the following example response:

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "error":"invalid_client"
}
     

Default: true

"level": string, optional

The level of log entries to display in the console.

Must be one of the following settings. These are ordered from most verbose to least verbose:

• ALL (log all messages)

• TRACE (log low-level tracing information)

• DEBUG (log debugging information)

• STAT (log performance measurement statistics)

• CONFIG (log configuration information)

• INFO (log general information)

• WARNING (log potential problems)

• ERROR (log serious failures)

• OFF (log no messages)

Default: INFO.

"stream": string, optional

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

Must be one of the following settings:

• ERR (use standard error: System.err)

• OUT (use standard output: System.out)

• AUTO (select standard error or output depending on the message log level: TRACE, DEBUG, STAT, CONFIG, INFO print to System.out; WARNING and ERROR print to System.err)

Default: ERR.

"file": configuration expression, required

The path to the log file.

A configuration expression, described in Expressions(5) is independent of the request, response, and contexts, so do not use expressions that reference their properties. You can, however, use ${env['variable']}, ${system['property']}, and all the built-in functions listed in Functions(5).

"level": string, optional

The level of log entries to display in the console.

Must be one of the following settings. These are ordered from most verbose to least verbose:

• ALL (log all messages)

• TRACE (log low-level tracing information)

• DEBUG (log debugging information)

• STAT (log performance measurement statistics)

• CONFIG (log configuration information)

• INFO (log general information)

• WARNING (log potential problems)

• ERROR (log serious failures)

• OFF (log no messages)

Default: INFO.

"keystore": KeyStore reference, optional

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

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

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

See also KeyStore(5).

"alias": string, required when keystore is used

Alias for the private key.

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

The password to read the private key from the keystore.

A configuration expression, described in Expressions(5) is independent of the request, response, and contexts, so do not use expressions that reference their properties. You can, however, use ${env['variable']}, ${system['property']}, and all the built-in functions listed in Functions(5).

"cookieName" string, optional

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

Default: openig-jwt-session

"sessionTimeout" duration, optional

The amount of time before the cookie session expires.

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

Durations are not case sensitive.

Negative durations are not supported.

The following units can be used in durations:

• indefinite, infinity, undefined, unlimited: unlimited duration

• zero, disabled: zero-length duration

• days, day, d: days

• hours, hour, h: hours

• minutes, minute, min, m: minutes

• seconds, second, sec, s: seconds

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

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

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

Default: 30 minutes

A zero duration for session timeout is not a valid setting. The maximum session timeout duration is 3650 days (approximately 10 years). If you set a longer duration, OpenIG truncates the duration to the maximum value.

"keystore": KeyStore reference, optional

The keystore that references the store for the actual keys.

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

See also KeyStore(5).

"password": expression, required

The password to read private keys from the keystore.

"alg" string, optional

The certificate algorithm to use.

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

See also Expressions(5).

"url": expression, required

URL to the keystore file.

See also Expressions(5).

"password": expression, optional

The password to read private keys from the keystore.

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

Default: No password is set.

See also Expressions(5).

"type": string, optional

The keystore format.

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

The provider configuration object properties are as follows:

"name": string, required

A name for the provider configuration.

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

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

"authorizeEndpoint": expression, required unless obtained through wellKnownEndpoint

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

See also Expressions(5).

"registrationEndpoint": expression, optional

The URL to the provider's OpenID Connect dynamic registration endpoint.

See also Expressions(5).

"tokenEndpoint": expression, required unless obtained through wellKnownEndpoint

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

See also Expressions(5).

"userInfoEndpoint": expression, optional

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

Default: no UserInfo is obtained from the provider.

See also Expressions(5).

"issuerHandler": Handler reference, optional

Invoke this HTTP client handler to communicate with the authorization server.

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: OpenIG uses the default ClientHandler.

See also Handlers, ClientHandler(5).

"supportedDomains": array of patterns, optional

List of patterns matching domain names handled by this issuer, used as a shortcut for OpenID Connect discovery before performing OpenID Connect dynamic registration.

In summary when the OpenID Provider is not known in advance, it might be possible to discover the OpenID Provider Issuer based on information provided by the user, such as an email address. The OpenID Connect discovery specification explains how to use WebFinger to discover the issuer. OpenIG can discover the issuer in this way. As a shortcut OpenIG can also use supported domains lists to find issuers already described in the OpenIG configuration.

To use this shortcut, OpenIG extracts the domain from the user input, and looks for an issuer whose supported domains list contains a match.

Supported domains patterns match host names with optional port numbers. Do not specify a URI scheme such as HTTP. OpenIG adds the scheme. For instance, *.example.com matches any host in the example.com domain. You can specify the port number as well as in host.example.com:8443. Patterns must be valid regular expression patterns according to the rules for the Java Pattern class.

"initialLength": number, optional

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

"memoryLimit": number, optional

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

"fileLimit": number, optional

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

"directory": string, optional

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

"keystore": KeyStore reference, optional

The KeyStore that references the store for public key certificates.

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

See also KeyStore(5).

"alg" string, optional

The certificate algorithm to use.

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

"protectionApiHandler": Handler reference, required

The handler to use when interacting with the UMA authorization server to manage resource sets, such as a ClientHandler capable of making an HTTPS connection to the server.

For details, see Handlers.

"authorizationServerUri": URI string, required

The URI to the UMA authorization server.

"clientId": expression, required

An expression that evaluates to the OAuth 2.0 client_id registered with the UMA authorization server.

"clientSecret": expression, required

An expression that evaluates to the OAuth 2.0 client_secret registered with the UMA authorization server.

"resources": array of resources, required

Resource objects matching the resources the resource owner wants to share.

Each resource object has the following form:

{
    "pattern": resource pattern,
    "actions": [
        {
            "scopes": [ scope string, ... ],
            "condition": boolean expression
        },
        {
            ...
        }
    ]
}
      

Each resource pattern can be seen to represent an application, or a consistent set of endpoints that share scope definitions. The actions map each request to the associated scopes. This configuration serves to set the list of scopes in the following ways:

1. When registering a resource set, OpenIG uses the list of actions to provide the aggregated, exhaustive list of all scopes that can be used.

2. When responding to an initial request for a resource, OpenIG derives the scopes for the ticket based on the scopes that apply according to the request.

3. When verifying the RPT, OpenIG checks that all required scopes are encoded in the RPT.

A description of each field follows:

"pattern": resource pattern, required

A pattern matching resources to be shared by the resource owner, such as .* to match any resource path, and /photos/.* to match paths starting with /photos/.

See also Patterns(5).

"actions": array of action objects, optional

A set of actions on matching resources that the resource owner can authorize.

When granting permission, the resource owner specifies the action scope. Conditions specify what the scopes mean in concrete terms. A given scope matches a requesting party operation when the corresponding condition evaluates to true.

"scopes": array of scope strings, optional

Scope strings to identify permissions.

For example, #read (read access on a resource).

"condition": boolean expression, required

A boolean expression representing the meaning of a scope.

For example, ${request.method == 'GET'} (true when reading a resource).

See also Expressions(5).

A share object has the following form:

{
    "path": pattern,
    "pat": UMA protection API token (PAT) string,
    "id": unique identifier string,
    "resource_set_id": unique identifier string,
    "user_access_policy_uri": URI string
}
   

The fields are as follows:

"path": pattern, required

A pattern matching the path to protected resources, such as /photos/.*.

This pattern must match a pattern defined in the UmaService for this API.

See also Patterns(5).

"pat": PAT string, required

A PAT granted by the UMA authorization server given consent by the resource owner.

In the present implementation, OpenIG has access only to the PAT, not to any refresh tokens.

"id": unique identifier string, read-only

This uniquely identifies the share. This value is set by the service when the share is created, and can be used when reading or deleting a share.

"resource_set_id": unique identifier string, read-only

This uniquely identifies the UMA resource set registered with the authorization server. This value is obtained by the service when the resource set is registered, and can be used when setting access policy permissions.

"user_access_policy_uri": URI string, read-only

This URI indicates the location on the UMA authorization server where the resource owner can set or modify access policies. This value is obtained by the service when the resource set is registered.

strings

the strings to put in the array.

array

the resulting array of containing the given strings.

object

the object to be searched for the presence of.

value

the value to be searched for.

true

if the object contains the specified value.

string

The base64-encoded string to decode.

string

The base64-decoded string.

string

The string to encode into Base64.

string

The base64-encoded string.

string

the parameter name or value

string

The string resulting from decoding the provided form encoded parameter name or value as per application/x-www-form-urlencoded.

string

the parameter name or value

string

The string resulting from form encoding the provided parameter name or value as per application/x-www-form-urlencoded.

string

the string in which to search for the specified substring.

substring

the value to search for within the string.

number

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

The index count starts from 1, not 0.

separator

the separator to place between joined elements.

strings

the array of strings to be joined.

string

the string containing the joined strings.

map

the map whose keys are to be searched.

pattern

a string containing the regular expression pattern to match.

string

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

object

the object whose length is to be determined.

number

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

string

the string to be searched.

pattern

a string containing the regular expression pattern to match.

array

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

string

the string to be searched.

pattern

a string containing the regular expression pattern to find.

true

if the string contains the specified regular expression pattern.

string

The name of the file to read.

string

The content of the file or null on error.

string

The name of the Java Properties file to read.

object

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

string

the string to be split.

pattern

the regular expression to split substrings around.