Reference documentation for ForgeRock® Token Validation Microservice.

"connectors": object, required

This property can be configured as one or more ports on which the Microgateway is connected, or any other connection supported by Vertx.

When more than one port is defined, TVMS is connected to each port.

"infoEndpointEnabled": configuration expression<boolean>, optional

Exposes the version information endpoint, /info.

Default: true

"temporaryDirectory": configuration expression<string>, optional

Directory containing temporary storage files.

Set this property to store temporary files in a different directory, for example:

{
  "temporaryDirectory": "/path/to/my-temporary-directory"
}

Default: /path/to/microservices/token-validation/tmp

"heap": array of configuration objects, optional

The heap object configuration, described in "Heap Objects".

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

"accessTokenResolver": AccessTokenResolver reference, required

An access_token resolver to resolve an access_token against an authorization server.

"properties": JSON object, optional

Configuration parameters declared as property variables for use in the configuration. See also "Properties".

Default: none

"temporaryStorage": TemporaryStorage reference, optional

Cache content during processing based on this TemporaryStorage configuration.

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

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

See also "TemporaryStorage".

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

"filters": array of filter references, required

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

The chain dispatches the request to these filters in the order they appear in the array.

See also "Filters".

"handler": Handler reference, required

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

The chain dispatches to this handler after the request has traversed all of the specified filters.

See also "Handlers".

"connections": configuration expression<number>, optional

• When TVMS is in ${sa-mode}, this property defines the maximum number of concurrent HTTP/1.1 connections in the client connection pool, for each Vert.x HTTP client. The number of Vert.x HTTP clients is configured by the gatewayUnits property of admin.json.

  For example, when connections = 64, and gatewayUnits = 3, the maximum number of concurrent HTTP/1.1 connections in the client connection pool is 192.

• When TVMS is in ${wc-mode}, this property defines the maximum number of concurrent HTTP/1.1 connections in the client connection pool.

Default: 64

"connectionTimeout": duration string, optional

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

Default: 10 seconds

For information about supported formats for duration, see duration.

"connectionTimeToLive": duration string, optional

Amount of time before a reusable pooled connection expires.

Set this property to expire reusable pooled connections after a fixed duration. For example, to prevent the reuse of connections set this property in routes for applications where the IP address (baseURI) is not stable or can change.

Default: Unlimited

For information about supported formats for duration, see duration.

"disableReuseConnection": configuration expression<boolean>, optional

Whether to disable connection reuse.

Default: false

"stateTrackingEnabled": configuration expression<boolean>, optional

Not supported.

By default, the Apache HTTP Client does not allow connection reuse when a client certificate is used for authentication. However, because the client certificate is defined at the client level, it is acceptable for requests to the same target to share a client certificate.

Use in combination with disableReuseConnection:

disableReuseConnection	stateTrackingEnabled	Description
false (default)	true (default)	Do not allow connection reuse when a client certificate is used for authentication.
false (default)	false	Allow connection reuse when a client certificate is used for authentication.
true	true (default) or false	Do not allow connection reuse.

Default: true

"hostnameVerifier": configuration expression<enumeration>, optional

Way to handle hostname verification for outgoing SSL connections. Use one of the following values:

• ALLOW_ALL: Allow a certificate issued by a trusted CA for any hostname or domain to be accepted for a connection to any domain.

  Caution

  This setting allows a certificate issued for one company to be accepted as a valid certificate for another company.

  To prevent the compromise of TLS connections, use this setting in development mode only. In production, use STRICT.

• 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: STRICT

"numberOfWorkers": configuration expression<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.

"protocolVersion": configuration expression<enumeration>, optional

Note

This property is used only when TVMS is running in ${sa-mode}.

Specifies the version of HTTP protocol to use when processing requests:

• HTTP/2:

  • For HTTP, process requests using HTTP/1.1.

  • For HTTPS, process requests using HTTP/2.

• HTTP/1.1:

  • For HTTP and HTTPS, process requests using HTTP/1.1.

• Not set:

  • For HTTP, process requests using HTTP/1.1.

  • For HTTPS with alpn enabled in ClientTlsOptions, process requests using HTTP/1.1, with an HTTP/2 upgrade request. If the targeted server can use HTTP/2, the client uses HTTP/2.

    For HTTPS with alpn disabled in ClientTlsOptions, process requests using HTTP/1.1, without an HTTP/2 upgrade request.

    Note that alpn is enabled by default in ClientTlsOptions.

Default: Not set

Note

In HTTP/1.1 request messages, a Host header is required to specify the host and port number of the requested resource. In HTTP/2 request messages, the Host header is not available.

In scripts or custom extensions that use HTTP/2, use UriRouterContext.originalUri.host or UriRouterContext.originalUri.port in requests.

"http2PriorKnowledge": configuration expression<boolean>, optional

Note

This property is used only when TVMS is running in ${sa-mode}, and when protocolVersion is HTTP/2.

Specifies whether the client should have prior knowledge that the server supports HTTP/2. This property is for cleartext (non-TLS requests) only.

• false: The client checks whether the server supports HTTP/2 by sending an HTTP/1.1 request to upgrade the connection to HTTP/2:

  • If the server supports HTTP/2, the server upgrades the connection to HTTP/2, and subsequent requests are processed over HTTP/2.

  • If the server does not support HTTP/2, the connection is not upgraded, and subsequent requests are processed over HTTP/1.

• true: The client does not check that the server supports HTTP/2. The client sends HTTP/2 requests to the server, assuming that the server supports HTTP/2.

Default: false

"proxy": Server reference, optional

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

If both proxy and systemProxy are defined, proxy takes precedence.

"proxy" : {
  "uri": configuration expression<uri string>,
  "username": configuration expression<string>,
  "passwordSecretId": configuration expression<secret-id>,
  "secretsProvider": SecretsProvider reference
}

uri: configuration expression<uri string>, required

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

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

username: configuration expression<string>, required if the proxy requires authentication

Username to access the proxy server.

"passwordSecretId": configuration expression<secret-id>, required if the proxy requires authentication

The secret ID of the password to access the proxy server.

For information about supported formats for secret-id, see secret-id.

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider to query for the proxy's password. For more information, see "SecretsProvider".

Default: The route's default secret service. For more information, see "Default Secrets Object".

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

"handler": {
  "type": "ClientHandler",
  "config": {
     "proxy": {
        "uri": "http://proxy.example.com:3128",
        "username": "proxyuser",
        "passwordSecretId": "myproxy.secret.id",
        "secretsProvider": "SystemAndEnvSecretStore"
     }
  }
}

"soTimeout": duration string, optional

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

Default: 10 seconds

For information about supported formats for duration, see duration.

"systemProxy": boolean, optional

Submit outgoing requests to a system-defined proxy, set by the following system properties or their HTTPS equivalents:

• http.proxyHost, the host name of the proxy server.

• http.proxyPort, the port number of the proxy server. The default is 80.

• http.nonProxyHosts, a list of hosts that should be reached directly, bypassing the proxy.

This property can't be used with a proxy that requires a username and password. Use the property proxy instead.

If both proxy and systemProxy are defined, proxy takes precedence.

For more information, see Java Networking and Proxies .

Default: False.

"temporaryStorage": string, optional

Specifies the heap object to use for temporary buffer storage.

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

tls: ClientTlsOptions reference, optional

Configure options for connections to TLS-protected endpoints, based on "ClientTlsOptions". Define the object inline or in the heap.

Default: Connections to TLS-protected endpoints are not configured.

"asyncBehavior": enumeration, optional

Specifies how the HTTP client behaves for asynchronous responses. Set the value to streaming or non_streaming:

• streaming: (Not supported.) Responses are processed as soon as all headers are received. The entity content is downloaded in a background thread. The value is not case-sensitive.

  Streaming mode reduces latency and is mandatory for Server-Sent Events (SSE) and the support of very large files (bigger than 2 GB). If thread starvation occurs, consider increasing numberOfWorkers, the number of worker threads dedicated to processing outgoing requests.

• non_streaming: Responses are processed when the entity content is entirely available. The value is not case-sensitive.

  Non-streaming mode does not support SSE or very large files. However, it has higher latency, and does not cause thread starvation.

Default: non_streaming

"retries": object, optional

Enable and configure retry for requests.

When a runtime error occurs while executing the request to the remote server, TVMS schedules a new execution of the request after the specified delay, until the allowed number of retries is reached or the execution succeeds.

"enabled": boolean, optional

Enable retries.

Default: true

"executor": ScheduledExecutorService reference, optional

The ScheduledExecutorService to use for scheduling delayed execution of the request.

Default: ScheduledExecutorService.

See also "ScheduledExecutorService".

"count": number, optional

The maximum number of retries to perform.

After this threshold is passed and if the request is still not successful, then the ClientHandler propagates the failure.

Default: 5 retries.

"delay": duration, optional

The delay to wait before retrying the request.

After a failure to send the request, if the number of retries is below the threshold, a new attempt is scheduled with the executor service after this delay.

Default: 10 seconds.

For information about supported formats for duration, see duration.

The following example configures the handler to retry the request only once, after a 1-minute delay:

{
  "retries": {
    "count": 1,
    "delay": "1 minute"
  }
}

The following example configures the handler to retry the request at most 20 times, every second:

{
  "retries": {
    "count": 20,
    "delay": "1 second"
  }
}

The following example configures the handler to retry the request 5 times, every 10 seconds (default values), with a dedicated executor:

{
  "retries": {
    "executor": {
      "type": "ScheduledExecutorService",
      "config": {
        "corePoolSize": 20
      }
    }
  }
}

"websocket": object, optional

Enable upgrade from HTTP or HTTPS protocol to WebSocket protocol.

{
  "websocket": {
    "enabled": boolean,
    "connectionTimeout": duration string,
    "soTimeout": duration string,
    "numberOfSelectors": number,
    "tls": ClientTlsOptions reference,
    "vertx": object
  }
}

For more information, see The WebSocket Protocol, RFC6455.

"enabled": boolean, optional

Enable upgrade from HTTP protocol and HTTPS protocol to WebSocket protocol.

Default: false

"connectionTimeout": duration string, optional

The maximum time allowed to establish a WebSocket connection.

Default: The value of handler's main connectionTimeout.

For information about supported formats for duration, see duration.

"soTimeout": duration string, optional

The time after which stalled connections are destroyed.

Tip

If there can be long delays between messages, consider increasing this value. Alternatively, keep the connection active by using WebSocket ping messages in your application.

Default: The value of handler's main soTimeout.

For information about supported formats for duration, see duration.

"numberOfSelectors": number, optional

The maximum number of worker threads.

In deployments with a high number of simultaneous connections, consider increasing the value of this property.

Default: 2

tls: ClientTlsOptions reference, optional

Configure options for connections to TLS-protected endpoints, based on a "ClientTlsOptions" configuration. Define a ClientTlsOptions object inline or in the heap.

Default: Use ClientTlsOptions defined for the handler

vertx: object, optional

Vert.x-specific configuration for this connector, where TVMS does not provide its own first-class configuration. Vert.x options are described in HttpClientOptions.

For properties where TVMS provides its own first-class configuration, Vert.x configuration options are disallowed, and the TVMS configuration option takes precedence over Vert.x options configured in vertx. The following Vert.x configuration options are disallowed client-side:

• port

• connectTimeout

• idleTimeout

• idleTimeoutUnit

• protocolVersion

• http2ClearTextUpgrade

• verifyHost

• ssl

• enabledSecureTransportProtocols

• enabledCipherSuites

• proxyOptions

• keyStoreOptions

• keyCertOptions

• pemKeyCertOptions

• pfxKeyCertOptions

• trustOptions

• trustStoreOptions

• pemTrustOptions

• pfxTrustOptions

• useAlpn

• alpnVersions

The following default vertx configuration provided by this handler overrides the Vert.x defaults:

• tryUsePerFrameWebSocketCompression = true

• tryUsePerMessageWebSocketCompression = true

The following example configures the maximum frame size and message size for Websocket connections:

"vertx": {
  "maxWebSocketFrameSize": 200000000,
  "maxWebSocketMessageSize": 200000000,
  "tryUsePerMessageWebSocketCompression": true
}

"bindings": array of objects, required

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

"condition": runtime expression<boolean>, optional

An inline expression to define a condition based on the request, context, or TVMS runtime environment, such as system properties or environment variables.

Conditions are defined using TVMS expressions, as described in "Expressions", and are evaluated as follows:

• If the condition evaluates to true, the request is dispatched to the associated handler.

• If the condition evaluates to false, the next condition in the list is evaluated.

• If no condition is specified, the request is dispatched unconditionally to the associated handler.

Default: No condition is specified.

"handler": Handler reference, required

A handler to dispatch the request to if the associated condition yields true, or if there is no associated condition.

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

See also "Handlers".

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

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

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

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

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

Default: No change to the base URI

"connections": configuration expression<number>, optional

• When TVMS is in ${sa-mode}, this property defines the maximum number of concurrent HTTP/1.1 connections in the client connection pool, for each Vert.x HTTP client. The number of Vert.x HTTP clients is configured by the gatewayUnits property of admin.json.

  For example, when connections = 64, and gatewayUnits = 3, the maximum number of concurrent HTTP/1.1 connections in the client connection pool is 192.

• When TVMS is in ${wc-mode}, this property defines the maximum number of concurrent HTTP/1.1 connections in the client connection pool.

Default: 64

"connectionTimeout": duration string, optional

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

Default: 10 seconds

For information about supported formats for duration, see duration.

"connectionTimeToLive": duration string, optional

Amount of time before a reusable pooled connection expires.

Set this property to expire reusable pooled connections after a fixed duration. For example, to prevent the reuse of connections set this property in routes for applications where the IP address (baseURI) is not stable or can change.

Default: Unlimited

For information about supported formats for duration, see duration.

"disableReuseConnection": configuration expression<boolean>, optional

Whether to disable connection reuse.

Default: false

"stateTrackingEnabled": configuration expression<boolean>, optional

Not supported.

By default, the Apache HTTP Client does not allow connection reuse when a client certificate is used for authentication. However, because the client certificate is defined at the client level, it is acceptable for requests to the same target to share a client certificate.

Use in combination with disableReuseConnection:

disableReuseConnection	stateTrackingEnabled	Description
false (default)	true (default)	Do not allow connection reuse when a client certificate is used for authentication.
false (default)	false	Allow connection reuse when a client certificate is used for authentication.
true	true (default) or false	Do not allow connection reuse.

Default: true

"hostnameVerifier": configuration expression<enumeration>, optional

Way to handle hostname verification for outgoing SSL connections. Use one of the following values:

• ALLOW_ALL: Allow a certificate issued by a trusted CA for any hostname or domain to be accepted for a connection to any domain.

  Caution

  This setting allows a certificate issued for one company to be accepted as a valid certificate for another company.

  To prevent the compromise of TLS connections, use this setting in development mode only. In production, use STRICT.

• 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: STRICT

"numberOfWorkers": configuration expression<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.

"protocolVersion": configuration expression<enumeration>, optional

Note

This property is used only when TVMS is running in ${sa-mode}.

Specifies the version of HTTP protocol to use when processing requests:

• HTTP/2:

  • For HTTP, process requests using HTTP/1.1.

  • For HTTPS, process requests using HTTP/2.

• HTTP/1.1:

  • For HTTP and HTTPS, process requests using HTTP/1.1.

• Not set:

  • For HTTP, process requests using HTTP/1.1.

  • For HTTPS with alpn enabled in ClientTlsOptions, process requests using HTTP/1.1, with an HTTP/2 upgrade request. If the targeted server can use HTTP/2, the client uses HTTP/2.

    For HTTPS with alpn disabled in ClientTlsOptions, process requests using HTTP/1.1, without an HTTP/2 upgrade request.

    Note that alpn is enabled by default in ClientTlsOptions.

Default: Not set

Note

In HTTP/1.1 request messages, a Host header is required to specify the host and port number of the requested resource. In HTTP/2 request messages, the Host header is not available.

In scripts or custom extensions that use HTTP/2, use UriRouterContext.originalUri.host or UriRouterContext.originalUri.port in requests.

"http2PriorKnowledge": configuration expression<boolean>, optional

Note

This property is used only when TVMS is running in ${sa-mode}, and when protocolVersion is HTTP/2.

Specifies whether the client should have prior knowledge that the server supports HTTP/2. This property is for cleartext (non-TLS requests) only.

• false: The client checks whether the server supports HTTP/2 by sending an HTTP/1.1 request to upgrade the connection to HTTP/2:

  • If the server supports HTTP/2, the server upgrades the connection to HTTP/2, and subsequent requests are processed over HTTP/2.

  • If the server does not support HTTP/2, the connection is not upgraded, and subsequent requests are processed over HTTP/1.

• true: The client does not check that the server supports HTTP/2. The client sends HTTP/2 requests to the server, assuming that the server supports HTTP/2.

Default: false

"proxy": Server reference, optional

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

If both proxy and systemProxy are defined, proxy takes precedence.

uri: configuration expression<uri string>, required

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

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

username: string, required if the proxy requires authentication

Username to access the proxy server.

"passwordSecretId": configuration expression<secret-id>, required if the proxy requires authentication

The secret ID of the password to access the proxy server.

For information about supported formats for secret-id, see secret-id.

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

"handler": {
  "type": "ReverseProxyHandler",
  "config": {
     "proxy": {
        "uri": "http://proxy.example.com:3128",
        "username": "proxyuser",
        "passwordSecretId": "myproxy.secret.id"
     }
  }
}

"soTimeout": duration string, optional

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

Tip

If SocketTimeoutException errors occur in the logs when you try to upload or download large files, consider increasing soTimeout.

Default: 10 seconds

For information about supported formats for duration, see duration.

"systemProxy": boolean, optional

Submit outgoing requests to a system-defined proxy, set by the following system properties or their HTTPS equivalents:

• http.proxyHost, the host name of the proxy server.

• http.proxyPort, the port number of the proxy server. The default is 80.

• http.nonProxyHosts, a list of hosts that should be reached directly, bypassing the proxy.

This property can't be used with a proxy that requires a username and password. Use the property proxy instead.

If both proxy and systemProxy are defined, proxy takes precedence.

For more information, see Java Networking and Proxies .

Default: False.

"temporaryStorage": string, optional

Specifies the heap object to use for temporary buffer storage.

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

tls: ClientTlsOptions reference, optional

Configure options for connections to TLS-protected endpoints, based on "ClientTlsOptions". Define the object inline or in the heap.

Default: Connections to TLS-protected endpoints are not configured.

"asyncBehavior": enumeration, optional

Specifies how the HTTP client behaves for asynchronous responses. Set the value to streaming or non_streaming:

• streaming: (Not supported.) Responses are processed as soon as all headers are received. The entity content is downloaded in a background thread. The value is not case-sensitive.

  Streaming mode reduces latency and is mandatory for Server-Sent Events (SSE) and the support of very large files (bigger than 2 GB). If thread starvation occurs, consider increasing numberOfWorkers, the number of worker threads dedicated to processing outgoing requests.

• non_streaming: Responses are processed when the entity content is entirely available. The value is not case-sensitive.

  Non-streaming mode does not support SSE or very large files. However, it has higher latency, and does not cause thread starvation.

Tip

If timeout errors occur in the logs, consider setting soTimeout to limit the timeout, and setting asyncBehavior to non_streaming.

Default: non_streaming

"retries": object, optional

Enable and configure retry for requests.

When a runtime error occurs while executing the request to the remote server, TVMS schedules a new execution of the request after the specified delay, until the allowed number of retries is reached or the execution succeeds.

"enabled": boolean, optional

Enable retries.

Default: true

"executor": ScheduledExecutorService reference, optional

The ScheduledExecutorService to use for scheduling delayed execution of the request.

Default: ScheduledExecutorService.

See also "ScheduledExecutorService".

"count": number, optional

The maximum number of retries to perform.

After this threshold is passed and if the request is still not successful, then the ReverseProxyHandler returns a 502 Bad Gateway response.

Default: 5 retries.

"delay": duration, optional

The delay to wait before retrying the request.

After a failure to send the request, if the number of retries is below the threshold, a new attempt is scheduled with the executor service after this delay.

Default: 10 seconds.

For information about supported formats for duration, see duration.

The following example configures the handler to retry the request only once, after a 1-minute delay:

{
  "retries": {
    "count": 1,
    "delay": "1 minute"
  }
}

The following example configures the handler to retry the request at most 20 times, every second:

{
  "retries": {
    "count": 20,
    "delay": "1 second"
  }
}

The following example configures the handler to retry the request 5 times, every 10 seconds (default values), with a dedicated executor:

{
  "retries": {
    "executor": {
      "type": "ScheduledExecutorService",
      "config": {
        "corePoolSize": 20
      }
    }
  }
}

"websocket": object, optional

Enable upgrade from HTTP or HTTPS protocol to WebSocket protocol.

{
  "websocket": {
    "enabled": boolean,
    "connectionTimeout": duration string,
    "soTimeout": duration string,
    "numberOfSelectors": number,
    "tls": ClientTlsOptions reference,
    "vertx": object
  }
}

For more information, see The WebSocket Protocol, RFC6455.

"enabled": boolean, optional

Enable upgrade from HTTP protocol and HTTPS protocol to WebSocket protocol.

Default: false

"connectionTimeout": duration string, optional

The maximum time allowed to establish a WebSocket connection.

Default: The value of handler's main connectionTimeout.

For information about supported formats for duration, see duration.

"soTimeout": duration string, optional

The time after which stalled connections are destroyed.

Tip

If there can be long delays between messages, consider increasing this value. Alternatively, keep the connection active by using WebSocket ping messages in your application.

Default: The value of handler's main soTimeout.

For information about supported formats for duration, see duration.

"numberOfSelectors": number, optional

The maximum number of worker threads.

In deployments with a high number of simultaneous connections, consider increasing the value of this property.

Default: 2

tls: ClientTlsOptions reference, optional

Configure options for connections to TLS-protected endpoints, based on a "ClientTlsOptions" configuration. Define a ClientTlsOptions object inline or in the heap.

Default: Use ClientTlsOptions defined for the handler

vertx: object, optional

Vert.x-specific configuration for this connector, where TVMS does not provide its own first-class configuration. Vert.x options are described in HttpClientOptions.

For properties where TVMS provides its own first-class configuration, Vert.x configuration options are disallowed, and the TVMS configuration option takes precedence over Vert.x options configured in vertx. The following Vert.x configuration options are disallowed client-side:

• port

• connectTimeout

• idleTimeout

• idleTimeoutUnit

• protocolVersion

• http2ClearTextUpgrade

• verifyHost

• ssl

• enabledSecureTransportProtocols

• enabledCipherSuites

• proxyOptions

• keyStoreOptions

• keyCertOptions

• pemKeyCertOptions

• pfxKeyCertOptions

• trustOptions

• trustStoreOptions

• pemTrustOptions

• pfxTrustOptions

• useAlpn

• alpnVersions

The following default vertx configuration provided by this handler overrides the Vert.x defaults:

• tryUsePerFrameWebSocketCompression = true

• tryUsePerMessageWebSocketCompression = true

The following example configures the maximum frame size and message size for Websocket connections:

"vertx": {
  "maxWebSocketFrameSize": 200000000,
  "maxWebSocketMessageSize": 200000000,
  "tryUsePerMessageWebSocketCompression": true
}

"directories": array of configuration expressions<string>, required

A list of one or more directories in which to search for static content.

When multiple directories are specified in an array, the directories are searched in the listed order.

"basePath": configuration expression<string>, required if the route is not /

The base path of the incoming request for static content.

To specify no base path, leave this property out of the configuration, or specify it as "basePath": "" or "basePath": "/".

Default: "".

"welcomePages": array of configuration expressions<string>, optional

A set of static content to serve from one of the specified directories when no specific resource is requested.

When multiple sets of static content are specified in an array, the sets are searched for in the listed order. The first set that is found is used.

Default: Empty list

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

"condition": runtime expression<boolean>, optional

An inline expression to define a condition based on the request, context, or TVMS runtime environment, such as system properties or environment variables.

Conditions are defined using TVMS expressions, as described in "Expressions", and are evaluated as follows:

• If the condition evaluates to true, the request is dispatched to the route.

• If the condition evaluates to false, the condition for the next route in the configuration is evaluated.

• If no condition is specified, the request is dispatched unconditionally to the route.

An external request can never match a condition that uses the reserved administrative route. Therefore, routes that use these conditions are effectively ignored. For example, if /openig is the administrative route, a route with the following condition would effectively be ignored: ${matches(request.uri.path, '^/openig/my/path')}.

Default: No condition is specified.

"name": string, optional

Name for the route.

The Router uses the name property to order the routes in the configuration. If the route does not have a name property, the Router uses the route ID.

The route ID is managed as follows:

• When you add a route manually to the routes folder, the route ID is the value of the _id field. If there is no _id field, the route ID is the filename of the added route.

• When you add a route through the Common REST endpoint, the route ID is the value of the mandatory _id field.

Caution

The filename of a route cannot be default.json, and the route's name property and route ID cannot be default.

Default: route ID

"secrets": configuration object, optional

An object that configures an inline array of one or more secret stores, as defined in "Default Secrets Object".

"session": JwtSession object, optional

Stateless session implementation for this route. Define a JwtSession object inline or in the heap.

When a request enters the route, TVMS builds a new session object for the route. The session content is available to the route's downstream handlers and filters. Session content available in the ascending configuration (a parent route or config.jso) is not available in the new session.

When the response exits the route, the session content is serialized as a secure JWT that is encrypted and signed, and the resulting JWT string is placed in a cookie. Session information set inside the route is no longer available. The session references the previous session object.

Default: Do not change the session storage implementation.

"auditService": AuditService object, optional

Provide an audit service for the route. Provide either the name of an AuditService object defined in the heap, or an inline AuditService configuration object.

Default: No auditing of a configuration. The NoOpAuditService provides an empty audit service to the top-level heap and its child routes.

"globalDecorators": one or more decorations, optional

Decorate all compatible objects in the route with one or more decorators referred to by the decorator name, and provide the configuration as described in "Decorators":

"globalDecorators":  {
  "decorator name": "decoration configuration"
  ...
}

The following object decorates all compatible objects in the route with a capture and timer decorator:

"globalDecorators":  {
  "capture": "all",
  "timer": true
}

Default: No decoration.

"decorator name": decoration, optional

Decorate the main handler of this route with a decorator referred to by the decorator name, and provide the configuration as described in "Decorators".

Default: No decoration.

"defaultHandler": Handler reference, optional

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

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

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

See also "Handlers".

"directory": expression, optional

Directory from which to load route configuration files.

Default: The default directory for route configuration files, at ${instanceDir} (on Windows, ${windowsInstanceDir}).

With the following example, route configuration files are loaded from /path/to/safe/routes instead of from the default directory:

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

Important

If you define multiple routers, configure directory so that the routers load route configuration files from different directories.

An infinite route-loading sequence is triggered when a router starts a route that, directly or indirectly, starts another router, which then loads route configuration files from the same directory.

See also "Expressions".

"scanInterval": duration string or integer, optional

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

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

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

Default: 10 seconds

For information about supported formats for duration, see duration.

"bindings": array of objects, required

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

"handler": Handler reference, required

Dispatch to this handler.

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

See also "Handlers".

"postcondition": runtime expression<boolean>, optional

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

Default: No condition is specified.

See also "Expressions".

"status": runtime expression<number>, required

The response status code (for example, 200).

"reason": runtime expression<string>, optional

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

"version": runtime expression<string>, optional

Protocol version. Default: "HTTP/1.1".

"headers": object, optional

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

• name is a configuration expression that resolves to a string for a header name. If multiple expressions resolve to the same final string, name has multiple values.

• value is a runtime expression that resolves to one or more header values.

When the property entity is used, you are recommended to set a Content-Type header with the correct content type value. The following example sets the content type of a message entity in the response:

"headers": {
  "Content-Type": [ "text/html" ]
}

The following example is used in 05-federate.json to redirect the original URI from the request:

"headers": {
  "Location": [
     "http://sp.example.com:8080/saml/SPInitiatedSSO"
  ]
}

"entity": runtime expression<string>, optional

The message entity to include in the response. If present, it must conform to the Content-Type header and set the content length header automatically.

Important

Attackers during reconnaissance can use response messages to identify information about a deployment. For security, limit the amount of information in messages, and avoid using words that help identify TVMS.

Default: No message entity

"rules": array of objects, required

An array of one or more rules configuration objects to specify criteria for the request.

When more than one rules configuration object is included in the array, the request must match at least one of the configuration objects.

When more than one property is specified in the rules configuration (for example, from and destination) the request must match criteria for each property.

{
  "rules": [
    {
      "name": configuration expression<string>,
      "from": [ object, ... ]
      "destination": [ object, ... ]
      "when": configuration expression<boolean>
    },
    ...
  ]
}

"name": configuration expression<string>, optional

A name for the rules configuration. When logging is configured for the AllowOnlyFilter, the rule name appears in the logs.

"from": array of objects, required

An array of one or more from configuration objects to specify criteria about the last request sender (the direct client).

When more than one from configuration object is included in the array, the last request sender must match at least one of the configuration objects.

When both ip and certificate properties are included in the configuration, the last request sender must match criteria for both properties.

"from": [
  {
    "ip": {
      "list": [configuration expression<string>, ...],
      "resolver": configuration expression<string>
    },
    "certificate" : {
      "subjectDNs" : Pattern[]
    }
  },
  ...
]

"ip": object, optional

Criteria about the IP address of the last request sender.

"list": array of configuration expressions<string>, required

An array of IP addresses or IP address ranges, using IPv4 or IPv6, and CIDR notation. The following example includes different formats:

"list": ("127.0.0.1", "::1", "192.168.0.0/16", "1234::/16")

The IP address of the last request sender must match at least one of the specified IP addresses or IP address ranges.

"resolver": configuration expression<string>, optional

An expression that returns an IP address as a string. The following example returns an IP address from the first item in X-Forwarded-For:

"resolver": "${request.headers['X-Forwarded-For'][0]}"

Default: Resolve the IP address from the following items, in order:

1. If there is a Forwarded header, use the IP address of the last hop.

2. Otherwise, if there is an X-Forwarded-For header, use the IP address of the last hop.

3. Otherwise, use the IP address of the connection.

"certificate": array of configuration expressions<object>, optional

An array of certificate configuration objects that specify criteria about the certificate of the last request sender.

"subjectDNs": array of configuration expressions<pattern>, required

An array of regular expressions to represent the expected distinguished name of the certificate subject, the subjectDN.

The subjectDN of the last request sender must match at least one of the patterns.

"destination": array of objects, optional

An array of destination configuration objects to specify criteria about the request destination.

When more than one destination configuration object is included in the array, the request destination must match at least one of the configuration objects.

When more than one property is specified in the destination configuration, for example hosts and ports, the request destination must match criteria for each property.

"destination": [
  {
    "hosts": [configuration expression<pattern>, ... ],
    "ports": [configuration expression<string>, ... ],
    "methods": [configuration expression<string>, ... ],
    "paths": [configuration expression<pattern>, ... ]
  },
  ...
]

"hosts": array of configuration expressions<pattern>, optional

An array of case-insensitive patterns to match the request.host attribute. Patterns are matched with the Java Pattern class.

When this property is configured, the request destination must match at least one host pattern in the array.

Default: Any host is allowed.

"ports": array of configuration expressions<string>, optional

An array of strings to match the request.port attribute. Specify values in the array as follows:

• Array of single ports, for example ["80", "90"].

• Array of port ranges, for example ["100:200"].

• Array of single ports and port ranges, for example ["80", "90", "100:200"].

When this property is configured, the destination port must match at least one entry in the array.

Default: Any port is allowed.

"methods": array of configuration expressions<string>, optional

An array of HTTP methods to match the request.method attribute.

When this property is configured, the request method must match at least one method in the array.

Default: Any method is allowed.

"paths": array of configuration expressions<pattern>, optional

An array of case-sensitive patterns to match the request.url_path attribute. Patterns are matched with the Java Pattern class.

When this property is configured, the destination path must match at least one path in the array.

Default: Any path is allowed.

"when": configuration expression<boolean>, optional

A condition that the request must meet.

The following condition is met when the first value of h1 is 1:

"when": "${request.headers['h1'][0] == '1'}"

"failureHandler": Handler reference, optional

Handler to treat the request if none of the declared rules are satisfied.

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

Default: HTTP 401 Unauthorized, with an empty response body.

See also "Handlers".

"onRequest": array of objects, optional

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

"onResponse": array of objects, optional

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

"condition": runtime expression<boolean>, optional

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

Default: No condition is specified.

See also "Expressions".

"target": lvalue-expression, required

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

See also "Expressions".

"value": runtime expression, optional

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

See also "Expressions".

"amService": AmService reference, required

The AmService heap object to use for the following properties:

• agent, the credentials of the TVMS agent in AM. When the agent is authenticated, the token can be used for tasks such as getting the user's profile, making policy evaluations, and connecting to the AM notification endpoint.

• url, the URL of an AM service to use for session token validation and authentication.

• amHandler, the handler to use when communicating with AM to validate the token in the incoming request.

• realm: Realm of the TVMS agent in AM.

• version: The version of the AM server.

This filter is compatible with AM version 5.5 or higher. If version is not set, the default version is AM 5 and an error is thrown.

See also, "AmService".

"keySecretId": configuration expression<secret-id>, required

The secret ID for the key required decrypt the AM password.

For information about supported formats for secret-id, see secret-id.

"keyType": configuration expression<enumeration>, required

Algorithm to decrypt the AM password. Use one of the following values:

• DES for DES/ECB/NoPadding

• AES AES for JWT-based AES_128_CBC_HMAC_SHA_256 encryption, available from AM 6.

  For more information, see AES_128_CBC_HMAC_SHA_256 in the IETF JSON Web Algorithms.

Default: DES

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for the JWT session signing or encryption keys. For more information, see "SecretsProvider".

Default: The route's default secret service. For more information, see "Default Secrets Object".

"ssoToken": runtime expression<string>, required

Location of the AM SSO token.

Default: ${request.cookies['AmService-ssoTokenHeader'][0].value}, where AmService-ssoTokenHeader is the name of the header or cookie where the AmService expects to find SSO tokens.

"certificate": runtime expression<certificate>, required

An EL expression which, when evaluated, yields an instance of a java.security.cert.Certificate.

Use the following "Functions" in the expression to define hash, decoding, and certificate format:

• digestSha256, to calculate the SHA-256 hash of the certificate.

• decodeBase64url, to decode an incoming base64url-encoded string.

• pemCertificate, to convert a PEM representation string into a certificate.

See "Examples".

"failureHandler": handler reference, optional

Handler to treat the request on failure.

Provide an inline handler configuration object, or the name of a handler object declared in the heap. See also "Handlers".

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

"clientId": configuration expression<string>, required

The ID of the OAuth 2.0 client registered with the authorization server.

"clientSecretId": configuration expression<secret-id>, required

The ID to use when querying the secretsProvider for the client secret.

"secretsProvider": SecretsProvider reference, required

The "SecretsProvider" to use to resolve queried secrets, such as passwords and cryptographic keys. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline.

"tokenEndpoint": configuration expression<url>, required

The URL to the authorization server's OAuth 2.0 token endpoint.

"scopes": array of configuration expression<string>, optional

Array of scope strings to request from the authorization server.

Default: Empty, request no scopes.

"handler": Handler reference or inline Handler declaration, optional

The Handler to use to access the authorization server's OAuth 2.0 token endpoint. Provide either the name of a handler object defined in the heap, or specify a handler object inline.

Default: ClientHandler

"condition": runtime expression<boolean>, required

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

See also "Expressions".

"delegate": filter reference, required

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

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

See also "Filters".

"condition": runtime expression<boolean>, required

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

See also "Expressions".

"failureHandler": handler reference, optional

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

Provide an inline handler configuration object, or the name of a handler object declared in the heap. See also "Handlers".

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

"filters": array of filter references, required

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

The chain dispatches the request to these filters in the order they appear in the array.

See also "Filters".

"managed": array of strings, optional

A list of the names of cookies to be managed.

"suppressed": array of strings, optional

A list of the names of cookies to be suppressed.

"relayed": array of strings, optional

A list of the names of cookies to be relayed.

"defaultAction": enumeration, optional

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

"policies": list of configuration expression<object>, required

A list of policies to apply to the request. A policy is selected when the origin of the request matches the accepted origins of the policy.

When multiple policies are declared, they are tried in the order that they are declared, and the first matching policy is selected.

When no policy matches during a preflight request, the failure handler is invoked or an HTTP 403 is returned.

{
  "origins": [ configuration expression<url>, ... ] or "*",
  "acceptedMethods": [ configuration expression<string>, ... ] or "*",
  "acceptedHeaders": [ configuration expression<string>, ... ] or "*",
  "exposedHeaders": [ configuration expression<string>, ... ],
  "maxAge": configuration expression<duration>,
  "allowCredentials": configuration expression<boolean>
}

"origins": list of configuration expression<url> or "*", required

A comma-separated list of origins, to match the origin of the CORS request. Alternatively, use * to allow requests from any URL.

Origins are URLs with a scheme, hostname, and optionally a port number, for example, http://www.example.com. If a port number is not defined, origins with no port number or with the default port number (80 for HTTP, 443 for HTTPS) are accepted.

Examples:

{
  "acceptedOrigins": [
    "http://www.example.com",
    "https://example.org:8433"
  ]
}

{
  "acceptedOrigins": "*"
}

"acceptedMethods": list of configuration expression<string> or "*", optional

A comma-separated list of case-sensitive HTTP method names that are allowed when making CORS requests. Alternatively, use * to allow requests with any method.

The Access-Control-Request-Method header is used by browsers in preflight requests, to let the server know which HTTP method will be used in the actual request. If a method is allowed, it is returned in the preflight response, in the Access-Control-Allow-Methods header.

Examples:

{
  "acceptedMethods": [
    "GET",
    "POST",
    "PUT",
    "MyCustomMethod"
  ]
}

{
  "acceptedMethods": "*"
}

Default: All methods are rejected.

"acceptedHeaders": list of configuration expression<string> or "*", optional

A comma-separated list of case-insensitive request header names that are allowed when making CORS requests. Alternatively, use * to allow requests with any header.

The Access-Control-Request-Headers header is used by browsers in preflight requests, to let the server know which HTTP headers might be used in the actual request. If all requested headers are allowed, they are returned in the preflight response, in the Access-Control-Allow-Headers header. If any of the requested headers are not allowed, the Access-Control-Allow-Headers header is omitted.

Examples:

{
  "acceptedHeaders": [
    "iPlanetDirectoryPro",
    "X-OpenAM-Username",
    "X-OpenAM-Password",
    "Accept-API-Version",
    "Content-Type",
    "If-Match",
    "If-None-Match"
  ]
}

{
  "acceptedHeaders": "*"
}

Default: All requested headers are rejected.

"exposedHeaders": list of configuration expression<string>, optional

A comma-separated list of case-insensitive response header names that are returned in the Access-Control-Expose-Headers header. Only headers in this list, safe headers, and the following simple response headers are exposed to frontend JavaScript code:

• Cache-Control

• Content-Language

• Expires

• Last-Modified

• Pragma

• Content-Type

Example:

{
  "exposedHeaders": [
    "Access-Control-Allow-Origin",
    "Access-Control-Allow-Credentials",
    "Set-Cookie"
  ]
}

Default: No headers are exposed.

"maxAge": configuration expression<duration>, optional

The maximum duration for which a browser is allowed to cache a preflight response. The value is included in the Access-Control-Max-Age header of preflight responses.

When this maxAge is greater than the browser's maximum internal value, the browser value takes precedence.

Default: 5 seconds

"allowCredentials": configuration expression<boolean>, optional

Whether to allow requests that use credentials, such as cookies, authorization headers, or TLS client certificates.

Set to true to set the Access-Control-Allow-Credentials header to true, and allow browsers to expose the response to frontend JavaScript code.

Default: False

"failureHandler": handler reference, optional

Handler to treat the request when no policy matches during a preflight request.

Provide an inline handler configuration object, or the name of a handler object declared in the heap. See also "Handlers".

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

"amService": AmService reference, required

The AmService heap object to use for the following properties:

• agent, the credentials of the TVMS agent in AM. When the agent is authenticated, the token can be used for tasks such as getting the user's profile, making policy evaluations, and connecting to the AM notification endpoint.

• url, the URL of an AM service to use for session token validation and authentication.

• ssoTokenHeader, the name of the cookie that contains the session token created by AM.

• amHandler, the handler to use when communicating with AM to validate the token in the incoming request.

• realm: Realm of the TVMS agent in AM.

• version: The version of the AM server.

See also, "AmService".

"redirectEndpoint": runtime expression<uri string>, required

The URI to the endpoint for CDSSO. This URI must also be configured in AM exactly as it is configured here.

To make sure that the redirect is routed back to this filter, where the authentication can be validated, include the endpoint in the route condition in one of the following ways:

• As a sub-path of the condition path.

  For example, use the following route condition with the following endpoint:

  "condition": "${matches(request.uri.path, '^/home/cdsso')}"

  "redirectEndpoint": "/home/cdsso/callback"

• To match the route condition.

  For example, use the following route condition with the following endpoint:

  "condition": "${matches(request.uri.path, '^/home/cdsso')}"

  "redirectEndpoint": "/home/cdsso"

  Note

  With this route condition, all POST requests on the condition path are treated as AM CDSSO callbacks. Any POST requests that aren't the result of an AM CDSSO callback will fail.

• As a specific path that is not related to the condition path.

  To make sure that the redirect is routed back to this filter, include the redirectEndpoint as a path in the filter condition.

  For example, use the following route condition with the following endpoint:

  "condition": "${matches(request.uri.path, '^/home/cdsso/redirect') || matches(request.uri.path, '^/ig/cdssoRedirectUri')}"

  "redirectEndpoint": "/ig/cdssoRedirectUri"

"authenticationService": configuration expression<uri string>,optional

The name of an AM authentication tree or authentication chain to use for authentication.

Default: AM's default authentication service.

"authCookie": object, optional

The configuration of the cookie used to store the authentication.

{
  "cookie": {
    "name": configuration expression<string>,
    "domain": configuration expression<string>,
    "httpOnly": configuration expression<boolean>,
    "path": configuration expression<string>,
    "sameSite": configuration expression<enumeration>,
    "secure": configuration expression<boolean>
  }
}

"name": configuration expression<string>, optional

Name of the cookie containing the authentication token from AM.

For security, change the default name of cookies.

Default: ig-token-cookie

"domain": configuration expression<string>, optional

Domain to which the cookie applies.

Set a domain only if the user-agent is able to re-emit cookies on that domain on its next hop. For example, to re-emit a cookie on the domain example.com, the user-agent must be able to access that domain on its next hop.

Default: The fully qualified hostname of the user-agent's next hop.

"httpOnly": configuration expression<boolean>, optional

Flag to mitigate the risk of client-side scripts accessing protected cookies.

Default: true

"path": configuration expression<string>, optional

Path protected by this authentication.

Set a path only if the user-agent is able to re-emit cookies on the path. For example, to re-emit a cookie on the path /home/cdsso, the user-agent must be able to access that path on its next hop.

Default: The path of the request that got the Set-Cookie in its response.

"sameSite": configuration expression<enumeration>, optional

Manage the circumstances in which a cookie is sent to the server. Use one of the following options to reduce the risk of cross-site request forgery (CSRF) attacks:

• STRICT: Send the cookie only if the request was initiated from the cookie domain.

• LAX: Send the cookie only with GET requests in a first-party context, where the URL in the address bar matches the cookie domain.

The value is not case-sensitive.

Default: Null; send the cookie whenever a request is made to the cookie domain.

"secure": configuration expression<boolean>, optional

Flag to limit the scope of the cookie to secure channels.

Set this flag only if the user-agent is able to re-emit cookies over HTTPS on its next hop. For example, to re-emit a cookie with the secure flag, the user-agent must be connected to its next hop by HTTPS.

Default: false

"defaultLogoutLandingPage": configuration expression<url>, optional

The URL to which a request is redirected if logoutExpression is evaluated as true.

If this property is not an absolute URL, the request is redirected to the TVMS domain name.

This parameter is effective only when logoutExpression is specified.

Default: None, processing continues.

"logoutExpression" runtime expression<boolean>, optional

An expression to define a condition for logout, based on the request. If the expression evaluates to true, the AM session token for the end user is revoked.

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

The following example expressions can be used to trigger revocation of the end user token:

• The request URI contains /logout:

  ${matches(request.uri, '/logout')}

• The request path starts with /logout:

  ${matches(request.uri.path, '^/logout')}

• The request query includes the logOff=true query parameter:

  ${matches(request.uri.query, 'logOff=true')}

Default: Logout is not managed by this filter.

"failureHandler": Handler reference, optional

Handler to treat the request if an error occurs during authentication.

If an error occurs during authentication, a "CdSsoFailureContext" is populated with details of the error and any associated Throwable. This is available to the failure handler so that it can respond appropriately.

Be aware that the failure handler does not itself play a role in user authentication. It is only invoked if there is a problem that prevents user authentication from taking place.

A number of circumstances may cause the failure handler to be invoked, including:

• The redirect endpoint is invalid.

• The redirect endpoint is invoked without a valid CDSSO token.

• The redirect endpoint is invoked inappropriately.

• An error was reported by AM during authentication.

If no failure handler is configured, the default failure handler is used.

See also "Handlers".

Default: HTTP 200 OK. The response entity contains details of the error.

"verificationSecretId": configuration expression<secret-id>, required to verify the signature of signed tokens

The secret ID for the secret to verify the signature of signed tokens.

If configured, the token must be signed. If not configured, TVMS does not verify the signature.

"secretsProvider": SecretsProvider reference, required to verify the signature of signed JWTs

The "SecretsProvider" to use to resolve queried secrets, such as passwords and cryptographic keys. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline.

"messageType": configuration expression<enumeration>, required

The type of message whose headers to encrypt or decrypt.

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

"operation": configuration expression<enumeration>, required

Indication of whether to encrypt or decrypt.

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

"keySecretId": configuration expression<secret-id>, required

The secret ID of the key to encrypt or decrypt the headers. For more information, see "Default Secrets Object".

"secretsProvider": SecretsProvider reference, required

The SecretsProvider object to query for the key to encrypt or decrypt the headers. For more information, see "SecretsProvider".

"algorithm": configuration expression<string>, optional

The algorithm name, mode, and padding used for encryption and decryption.

CryptoHeaderFilter does not support EC-based encryption. Use other cipher algorithm values given in Java Security Standard Algorithm Names.

Default: AES/ECB/PKCS5Padding

"charset": configuration expression<string>, optional

The name of the charset used to encrypt or decrypt values, as described in Class Charset.

Default: UTF-8

"headers": array of configuration expression<string>, optional

The names of header fields to encrypt or decrypt.

Default: Empty

"cookieName": configuration expression<string>, required

The name of the cookie used to store the session ID.

"headerName": configuration expression<string>, optional

The name of the header that carries the CSRF token. The same header is used to create and verify the token.

Default: X-CSRF-Token

"excludeSafeMethods": configuration expression<boolean>, optional

Whether to exclude GET, HEAD, and OPTION methods from CSRF testing. In most cases, these methods are assumed as safe from CSRF.

Default: true

"failureHandler": handler reference, optional

Handler to treat the request if the CSRF the token is not provided or can't be validated. Provide an inline handler declaration, or the name of a handler object defined in the heap.

Although TVMS returns the CSRF token transparently in the response header, this handler cannot access the CSRF token.

Default: Handler that generates HTTP 403 Forbidden.

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

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

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

"file": expression, required

The file containing the record to be read.

See also "Expressions".

"charset": string, optional

The character set in which the file is encoded.

Default: "UTF-8".

"separator": separator identifier string, optional

The separator character, which is one of the following:

COLON

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

COMMA

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

TAB

Tab separated values, with support for quoted literal strings.

Default: COMMA

"header": boolean, optional

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

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

Default: true.

"fields": array of strings, optional

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

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

"target": lvalue-expression, required

Expression that yields the target object to contain the record.

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

See also "Expressions".

"key": string, required

The key used for the lookup operation.

"value": runtime expression<string>, required

The value to be looked-up in the file.

See also "Expressions".

"messageType": enumeration, required

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

"remove": array of strings, optional

The names of header fields to remove from the message.

"add": object, optional

Header fields to add to the message. The header name is specified by name. The header values are specified by an array of runtime expressions that evaluate to strings.

"username": configuration expression<string>, required

The username of the client to authenticate.

"passwordSecretId": configuration expression<string>, required

The secret ID required to obtain the client password.

For information about supported formats for secret-id, see secret-id.

"secretsProvider": SecretsProvider reference, required

The "SecretsProvider" to use to obtain the passwordSecretId. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline.

"urlEncodeCredentials": configuration expression<boolean>, optional

Set to true to URL-encoded credentials before base64-encoding them.

Default: false

"username": runtime expression<string>, required

The username to supply during authentication.

See also "Expressions".

"password": runtime expression<string>, required

The password to supply during authentication.

See also "Expressions".

"failureHandler": Handler reference, required

Dispatch to this Handler if authentication fails.

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

See also "Handlers".

"cacheHeader": boolean, optional

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

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

Default: true

"template": map or runtime expression<map>, required

A map of information taken from the request or associated contexts in TVMS.

If this property is a map, the structure must have the format Map<String, Object>. For example,

"template": {
  "name": "${contexts.userProfile.commonName}",
  "email": "${contexts.userProfile.rawInfo.mail[0]}",
  "address": "${contexts.userProfile.rawInfo.postalAddress[0]}",
  "phone": "${contexts.userProfile.rawInfo.telephoneNumber[0]}"
}

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

"template": "${contexts.attributes}"

See also "Expressions".

"secretsProvider": SecretsProvider reference, optional

The SecretsProvider object to query for JWT signing or encryption keys. For more information, see "SecretsProvider".

Default: The route's default secret service. For more information, see "Default Secrets Object".

"signature": object, optional

A JWT signature to allow the authenticity of the claims/data to be validated. A signed JWT can be encrypted.

{
  "signature": {
    "secretId":  configuration expression<secret-id>,
    "algorithm": configuration expression<string>,
    "encryption": object
  }
}

"secretId": configuration expression<secret-id>, required if signature is used

The secret ID of the key used to sign the JWT.

For information about supported formats for secret-id, see secret-id.

"algorithm": expression<string>, optional

The algorithm with which to sign the JWT.

The following algorithms are supported but not necessarily tested in TVMS:

• Algorithms described in Cryptographic Algorithms for Digital Signatures and MACs .

  For RSASSA-PSS, you must install Bouncy Castle. For information, see The Legion of the Bouncy Castle .

• From TVMS 6.1, Ed25519 described in CFRG Elliptic Curve Diffie-Hellman (ECDH) and Signatures .

Default: RS256

"encryption": object, optional

Encrypt the JWT.

{
  "encryption": {
    "secretId": configuration expression<secret-id>,
    "algorithm": configuration expression<string>,
    "method": configuration expression<enumeration>
  }
}

"secretId": configuration expression<secret-id>, optional

The secret ID of the key used to encrypt the JWT. The value is mapped to key aliases in "KeyStoreSecretStore".

For information about supported formats for secret-id, see secret-id.

"algorithm": expression<string>, required

The algorithm used to encrypt the JWT.

For information about available algorithms, see "alg" (Algorithm) Header Parameter Values for JWE .

"method": configuration expression<enumeration>, required

The method used to encrypt the JWT.

For information about available methods, see "enc" (Encryption Algorithm) Header Parameter Values for JWE .

"jwt": configuration expression<string>, required

The value of the JWT. Cannot be null.

"verificationSecretId": configuration expression<secret-id>, required to verify the signature of signed tokens

The secret ID for the secret to verify the signature of signed tokens.

If configured, the token must be signed. If not configured, TVMS does not verify the signature.

"decryptionSecretId": configuration expression<secret-id>, required if AM secures access_tokens with encryption

The secret ID for the secret to verify the encryption of tokens.

If configured, the token must be encrypted. If not configured, TVMS does not verify the encryption.

For information about how each type of secret store resolves named secrets, see "Secret Stores".

"secretsProvider": SecretsProvider reference, required to verify the signature of signed JWTs

The "SecretsProvider" to use to resolve queried secrets, such as passwords and cryptographic keys. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline.

"customizer": JwtValidatorCustomizer reference, optional

Defines a set of validation constraints for JWT claims and sub-claims. If a claim is not validated against the constraint, the JWT is not validated.

JwtValidatorCustomizer provides a ScriptableJwtValidatorCustomizer to enrich a builder object by using its methods. Get more information about the following items:

• The builder object, at "Available Objects".

• Transformer methods, to enrich the builder object, at org.forgerock.openig.util.JsonValues.

• Constraints, at org.forgerock.openig.tools.jwt.Constraints.

• Other properties for ScriptableJwtValidatorCustomizer, at "Scripts".

The following example checks that the value of the claim sub is george:

"customizer": {
  "type": "ScriptableJwtValidatorCustomizer",
  "config": {
    "type": "application/x-groovy",
    "source": [ "builder.claim('sub', JsonValue::asString, isEqualTo('george'))" ]
  }
}

The following example checks that the value of the custom sub-claim is ForgeRock:

"customizer": {
  "type": "ScriptableJwtValidatorCustomizer",
  "config": {
    "type": "application/x-groovy",
    "source": [
      builder.claim('customclaim/subclaim', JsonValue::asString, isEqualTo('ForgeRock'));
    ]
  }
}

The following example checks the value of multiple claims:

"customizer": {
  "type": "ScriptableJwtValidatorCustomizer",
  "config": {
    "type": "application/x-groovy",
    "source": [
      "builder.claim('aud', listOf(JsonValue::asString), contains('My App'))",
      "       .claim('iat', instant(), isInThePast())",
      "       .claim('exp', instant(), isInTheFuture());",
      "builder.claim('iss', JsonValue::asString, isEqualTo('ForgeRock AM'));"
    ]
  }
}

Default: Claims are not validated

"skewAllowance": configuration expression<duration>, optional

The duration to add to the validity period of a JWT to allow for clock skew between different servers. To support a zero-trust policy, the skew allowance is by default zero.

A skewAllowance of 2 minutes affects the validity period as follows:

• A JWT with an iat of 12:00 is valid from 11:58 on the TVMS clock.

• A JWT with an exp 13:00 is expired after 13:02 on the TVMS clock.

Default: zero

"failureHandler": handler reference, optional

Handler to treat the request on failure.

Provide an inline handler configuration object, or the name of a handler object declared in the heap. See also "Handlers".

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

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

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

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

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

See also "Expressions".

Service URIs are constructed from the clientEndpoint. Task that the OAuth2ClientFilter performs is determined by the service URI, as follows:

clientEndpoint/login/?discovery=user-input&goto=url

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

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

Supported with OpenAM 13 and later versions, and AM 5 and later versions.

clientEndpoint/login?registration=clientId&issuer=issuerName&goto=url

Redirect the end user for authorization with the specified registration, defined by the ClientRegistration's clientId and issuerName. For information, see "ClientRegistration".

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.

If the whole process is successful, the filter saves the authorization state in the session and redirects the user-agent to the specified URL.

clientEndpoint/logout?goto=url

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

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

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 the authorization state in the specified target location, and call the next filter or handler in the chain.

"clientEndpoint": runtime expression<uri string>, required

The URI to the client endpoint.

So that routes can accept redirects from the authorization server to the callback endpoint, the clientEndpoint must be the same as the route condition or a sub path of the route condition. For example:

• The same as the route condition:

  "condition": "${matches(request.uri.path, '^/discovery')}"

  "clientEndpoint": "/discovery"

• As a sub path of the route condition:

  "condition": "${matches(request.uri.path, '^/home/id_token')}"

  "clientEndpoint": "/home/id_token/sub-path"

The service URIs are constructed from the clientEndpoint. For example, when clientEndpoint is openid, the service URIs are /openid/login, /openid/logout, and /openid/callback. These endpoints are implicitly reserved, and attempts to access them directly can cause undefined errors.

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

See also "Expressions".

"failureHandler": handler reference, required

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

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

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

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

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

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

{
    "client_registration": "ClientRegistration name string",
    "error": {
        "realm": "optional string",
        "scope": [ "optional scope string (required by the client)", ... ],
        "error": "optional string",
        "error_description": "optional string",
        "error_uri": "optional string"
    },
    "access_token": "string",
    "id_token": "string",
    "token_type": "Bearer",
    "expires_in": "number",
    "scope": [ "optional scope string", ... ],
    "client_endpoint": "URL string",
    "exception": exception
}

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

• "access_token"

• "id_token"

• "token_type"

• "expires_in"

• "scope"

• "client_endpoint"

See also "Handlers".

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

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

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

See also "Handlers".

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

List of client registrations that authenticate TVMS to the authorization server. The list must contain all client registrations that are to be used by the client filter.

The value represents a static client registration with an authorization server, as described in "ClientRegistration".

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

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

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

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

"redirect_uris": array of URI strings, required

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

One of the registered values must match the clientEndpoint.

"client_name": string, optional

Name of the client to present to the end user.

"scope": space separated string, optional

Space separated string of scopes to request of the OpenID Provider, for example:

"scope": "openid profile"

This property is available for dynamic client registration with AM 5.5 and later versions, or with authorization servers that support RFC 7591, OAuth 2.0 Dynamic Client Registration Protocol

Use both scope and scopes to dynamically register with a wider range of identity providers.

"scopes": array of strings, optional

Array of scope strings to request of the OpenID Provider, for example:

"scopes": [
  "openid",
  "profile",
  "email"
]

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

Use both scope and scopes to dynamically register with a wider range of identity providers.

"cacheExpiration": configuration expression<duration>, optional

Duration for which to cache user-info resources.

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

Default: 10 minutes

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

For information about supported formats for duration, see duration.

"executor": executor service reference, optional

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

Default: ScheduledExecutorService

See also "ScheduledExecutorService".

"target": configuration expression<lvalue-expression>, optional

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

When the target is openid, the following information can be provided in ${attributes.openid}:

• access_token: The value of the OAuth 2.0 access_token

• client_endpoint: The URL to the client endpoint

• client_registration: The client ID of the OAuth 2.0 client that enables TVMS to communicate as an OAuth 2.0 relying party with an authorization server

• expires_in: Number of milliseconds until the token expires

• id_token_claims: The claims used in the token

• scope: The scopes associated with the token

• token_type: The type or authentication token

• user_info: The profile attributes of an authenticated user

Data is provided to the target as follows:

• If the authorization process completes successfully, the OAuth2ClientFilter injects the authorization state data into the target. In the following example, a downstream StaticRequestFilter retrieves the username and password from the target to log the user in to the sample application.

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

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

Default: ${attributes.openid}

See also "Expressions".

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

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

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

Default: return an empty page.

See also "Expressions".

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

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

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

Default: return an empty page.

See also "Expressions".

"requireHttps": configuration expression<boolean>, optional

Whether to require that original target URI of the request (originalUri in "UriRouterContext") uses the HTTPS scheme.

If the request received by the web container is not using HTTPS, the request is rejected.

Default: true.

"requireLogin": configuration expression<boolean>, optional

Whether to require authentication for all incoming requests.

Default: true.

"issuerRepository": Issuer repository reference, optional

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

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

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

See also "IssuerRepository".

"discoveryHandler": Handler reference, optional

Use this property for discovery and dynamic registration of OpenID Connect clients.

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: The default ClientHandler.

See also "Handlers", "ClientHandler".

"discoverySecretId": configuration expression<secret-id>, required for discovery and dynamic registration

Use this property for discovery and dynamic registration of OAuth 2.0 clients.

Specifies the secret ID of the secret that is used to sign a JWT before the JWT is sent to the authorization server.

If discoverySecretId is used, then the tokenEndpointAuthMethod is always private_key_jwt.

For information about supported formats for secret-id, see secret-id.

"tokenEndpointAuthMethod": configuration expression<enumeration>, optional

Use this property for discovery and dynamic registration of OAuth 2.0 clients.

The authentication method with which a client authenticates to the authorization server or OpenID provider at the token endpoint. For information about client authentication methods, see OpenID Client Authentication. The following client authentication methods are allowed:

• client_secret_basic: Clients that have received a client_secret value from the authorization server authenticate with the authorization server by using the HTTP Basic authentication scheme, as in the following example:

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

• client_secret_post: Clients that have received a client_secret value from the authorization server authenticate with the authorization server by including the client credentials in the request body, as in the following example:

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

• private_key_jwt: Clients send a signed JSON Web Token (JWT) to the authorization server. TVMS builds and signs the JWT, and prepares the request as in the following example:

  POST /token HTTP/1.1
  Host: as.example.com
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code&
  code=...&
  client_id=<clientregistration_id>&
  client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&
  client_assertion=PHNhbWxwOl ... ZT

  If the authorization server doesn't support private_key_jwt, a dynamic registration falls back on the method returned by the authorization server, for example, client_secret_basic or client_secret_post.

  If tokenEndpointAuthSigningAlg is not configured, the RS256 signing algorithm is used for private_key_jwt.

Consider these points for identity providers:

• Some providers accept more than one authentication method.

• If a provider strictly enforces how the client must authenticate, align the authentication method with the provider.

• If a provider doesn't support the authentication method, the provider sends an HTTP 400 Bad Request response with an invalid_client error message, according to RFC 6749 The OAuth 2.0 Authorization Framework, section 5.2 .

• If the authentication method is invalid, the provider sends an IllegalArgumentException.

Default:

• If discoverySecretId is used, then the tokenEndpointAuthMethod is always private_key_jwt.

• Otherwise, client_secret_basic

"tokenEndpointAuthSigningAlg": configuration expression<string>, optional

The JSON Web Algorithm (JWA) used to sign the JWT that is used to authenticate the client at the token endpoint. The property is used when private_key_jwt is used for authentication.

If the authorization server sends a notification to use a different algorithm to sign the JWT, that algorithm is used.

Default:

• If discoverySecretId is used, then the tokenEndpointAuthSigningAlg is RS256.

• Otherwise, not used.

"secretsProvider": SecretsProvider reference, required

The "SecretsProvider" to use to resolve queried secrets, such as passwords and cryptographic keys. Provide either the name of a SecretsProvider object defined in the heap, or specify a SecretsProvider object inline.

"accessTokenResolver": AccessTokenResolver reference, required

Resolves an access_token against an authorization server. Configure one of the following access_token resolvers:

• "TokenIntrospectionAccessTokenResolver"

• "StatelessAccessTokenResolver"

• "ConfirmationKeyVerifierAccessTokenResolver"

• "ScriptableAccessTokenResolver"

"cache": object, optional

Configuration of caching for OAuth 2.0 access_tokens. By default, access_tokens are not cached. For an alternative way of caching of OAuth 2.0 access_tokens, configure "CacheAccessTokenResolver".

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

(From AM 6.5.3.) When an access_token is revoked on AM, the CacheAccessTokenResolver can delete the token from the cache when both of the following conditions are true:

• The notification property of AmService is enabled.

• The delegate AccessTokenResolver provides the token metadata required to update the cache.

When a refresh_token is revoked on AM, all associated access_tokens are automatically and immediately revoked.

"cache": {
  "enabled": configuration expression<boolean>,
  "defaultTimeout": configuration expression<duration>,
  "maxTimeout": configuration expression<duration>,
  "amService": AmService reference,
  "onNotificationDisconnection": configuration expression<enumeration>
}

enabled: configuration expression<boolean>, optional

Enable or disable caching.

Default: false

defaultTimeout: configuration expression<duration>, optional

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

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

The following example caches access_tokens for these times:

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

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

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

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

Default: 1 minute

maxTimeout: configuration expression<duration>, optional

The maximum duration for which to cache OAuth 2.0 access_tokens.

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

The duration cannot be zero or unlimited.

For information about supported formats for duration, see duration.

"amService": AmService reference, required

(From AM 6.5.3.) The AmService to use for the Websocket notification service. To evict revoked access_tokens from the cache, enable the notifications property of AmService.

See also, "AmService".

onNotificationDisconnection: configuration expression<enumeration>, optional

The strategy to manage the cache when the WebSocket notification service is disconnected, and TVMS receives no notifications for AM events. If the cache is not cleared it can become outdated, and TVMS can allow requests on revoked sessions or tokens.

Cached entries that expire naturally while the notification service is disconnected are removed from the cache.

Use one of the following values:

• NEVER_CLEAR

  • When the notification service is disconnected:

    • Continue to use the existing cache.

    • Deny access for requests that are not cached, but do not update the cache with these requests.

  • When the notification service is reconnected:

    • Continue to use the existing cache.

    • Query AM for incoming requests that are not found in the cache, and update the cache with these requests.

• CLEAR_ON_DISCONNECT

  • When the notification service is disconnected:

    • Clear the cache.

    • Deny access to all requests, but do not update the cache with these requests.

  • When the notification service is reconnected:

    • Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

    • Update the cache with these requests.

• CLEAR_ON_RECONNECT

  • When the notification service is disconnected:

    • Continue to use the existing cache.

    • Deny access for requests that are not cached, but do not update the cache with these requests.

  • When the notification service is reconnected:

    • Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

    • Update the cache with these requests.

Default: CLEAR_ON_DISCONNECT

"executor": executor, optional

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

Default: ScheduledExecutorService

See also "ScheduledExecutorService".

"requireHttps": configuration expression<boolean>, optional

Whether to require that original target URI of the request (originalUri in "UriRouterContext") uses the HTTPS scheme.

If the request received by the web container is not using HTTPS, the request is rejected.

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: TVMS

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

A list of one of more scopes that the OAuth 2.0 access_token must have.

array of runtime expression<string>, required if ScriptableResourceAccess is not used

A string, array of strings, runtime expression<string>, or array of runtime expression<string> to represent one or more scopes; mutually exclusive with ScriptableResourceAccess.

ScriptableResourceAccess, required if "array of runtime expression<string>" is not used

A script that produces a list of one or more required scopes; mutually exclusive with "array of runtime expression<string>".

The script evaluates each request dynamically and returns the scopes that request needs to access the protected resource. The script must return a Promise<Set, ResponseException> or a Set<String>.

For information about the properties of ScriptableResourceAccess, see "Scripts". For an example of how to use this property, see the examples section on this page.

{
  "name": ScriptableResourceAccess-1,
  "type": "ScriptableResourceAccess",
  "config": {
    "type": string,
    "file": expression,                     // Use either "file"
    "source": string or array of strings,   // or "source", but not both.
    "args": object,
    "clientHandler": Handler reference
  }
}

"request": request configuration object, required

The request that replays the credentials. The JSON object of request is the config content of a "StaticRequestFilter".

"method": string, required

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

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

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

See also "Expressions".

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

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

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

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

When the expression evaluates to true, direct the request to a login page, extract credentials, and replay them.

When false, pass the request unchanged to the next filter or handler in the chain.

The following example expression resolves to true when the request is an HTTP GET, and the request URI path is /login:

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

"loginPageContentMarker": pattern, required unless loginPage is defined

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

See also "Patterns".

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

"algorithm": string, optional

Algorithm used for decryption.

Use the same algorithm that is used to send the encrypted credentials.

Default: AES/ECB/PKCS5Padding

"keyType": string, optional

Algorithm name for the secret key.

Default: AES

"headers": array of strings, optional

The names of header fields to decrypt.

Default: Do not decrypt any headers.

"loginPageExtractions": extract configuration array, optional

Object to extract values from the login page entity.

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

"name": string, required

Name of the field where the extracted value is put.

The names are mapped into attributes.extracted.

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

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

"pattern": pattern, required

The regular expression pattern to find in the entity.

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

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

See also "Patterns".

"amService": AmService reference, required

The AmService object to use for the following properties:

• agent, the credentials of the TVMS agent in AM. When the agent is authenticated, the token can be used for tasks such as getting the user's profile, making policy evaluations, and connecting to the AM notification endpoint.

• realm: Realm of the TVMS agent in AM.

• url, the URL of an AM service to use for session token validation and authentication.

• ssoTokenHeader, the name of the HTTP header that provides the session token created by AM

• amHandler, the handler to use when requesting policy decisions from AM.

• version: The version of the AM server.

See also, "AmService".

"pepRealm": string, optional

The AM realm where the policy set is located.

Default: The realm declared for amService.

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

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

ssoTokenSubject can take the following values:

• ${contexts.ssoToken.value}, when the SingleSignOnFilter is used for authentication

• ${contexts.ssoToken.value} or ${contexts.cdsso.token}, when the CrossDomainSingleSignOnFilter is used for authentication

When no SSO is involved (API protection), then ssoTokenSubject usually points to a header value (${request.headers.iPlanetDirectoryPro[0]}).

See also "Expressions".

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

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

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

See also "OAuth2ClientFilter" and "Expressions".

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

A representation of JWT claims for the subject.

The claim "sub" must be specified. Other claims are optional.

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

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

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

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

"application": runtime expression<string>, optional

The ID of the AM policy set to use when requesting policy decisions.

Default: iPlanetAMWebAgentService, provided by AM's default policy set

cache: object, optional

Enable and configure caching of policy decisions from AM, based on Caffeine. For more information, see the GitHub entry, Caffeine .

{
  "cache": {
    "enabled": configuration expression<boolean>,
    "defaultTimeout": configuration expression<duration>,
    "executor": executor service reference,
    "maximumSize": configuration expression<number>,
    "maximumTimeToCache": configuration expression<duration>,
    "onNotificationDisconnection": configuration expression<enumeration>,
  }
}

Default: Policy decisions are not cached.

Note

Policy decisions that contain advices are never cached.

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

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

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

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

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

For information about supported formats for duration, see duration.

enabled: configuration expression<boolean>, optional

Enable or disable caching of policy decisions.

When a policy decision is cached, TVMS can reuse the policy decision without repeatedly asking AM for a new policy decision. When caching is disabled, TVMS must ask AM to make a decision for each request.

Default: false

defaultTimeout: configuration expression<duration>, optional

The default duration for which to cache AM policy decisions.

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

Default: 1 minute

For information about supported formats for duration, see duration.

executor: executor service reference, optional

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

Default: ForkJoinPool.commonPool()

"maximumSize": configuration expression<number>, optional

The maximum number of entries the cache can contain.

Default: Unlimited/unbound.

maximumTimeToCache: configuration expression<duration>, optional

The maximum duration for which to cache AM policy decisions.

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

The duration cannot be zero or unlimited.

For information about supported formats for duration, see duration.

onNotificationDisconnection: configuration expression<enumeration>, optional

The strategy to manage the cache when the WebSocket notification service is disconnected, and TVMS receives no notifications for AM events. If the cache is not cleared it can become outdated, and TVMS can allow requests on revoked sessions or tokens.

Cached entries that expire naturally while the notification service is disconnected are removed from the cache.

Use one of the following values:

• NEVER_CLEAR

  • When the notification service is disconnected:

    • Continue to use the existing cache.

    • Deny access for requests that are not cached, but do not update the cache with these requests.

  • When the notification service is reconnected:

    • Continue to use the existing cache.

    • Query AM for incoming requests that are not found in the cache, and update the cache with these requests.

• CLEAR_ON_DISCONNECT

  • When the notification service is disconnected:

    • Clear the cache.

    • Deny access to all requests, but do not update the cache with these requests.

  • When the notification service is reconnected:

    • Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

    • Update the cache with these requests.

• CLEAR_ON_RECONNECT

  • When the notification service is disconnected:

    • Continue to use the existing cache.

    • Deny access for requests that are not cached, but do not update the cache with these requests.

  • When the notification service is reconnected:

    • Query AM for all requests that are not found in the cache. (Because the cache was cleared, the cache is empty after reconnection.)

    • Update the cache with these requests.

Default: CLEAR_ON_DISCONNECT

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

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

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

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

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

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

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

"failureHandler": handler reference, optional

Handler to treat the request if it is denied by the policy decision.

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

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

Provide an inline handler configuration object, or the name of a handler object declared in the heap. See also "Handlers".

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

"resourceUriProvider": ResourceUriProvider reference, optional

Return the resource URL to include in policy decision requests to AM. Configure one of the following ResourceUriProviders inline or in the heap:

• RequestResourceUriProvider

• ScriptableResourceUriProvider

Default: RequestResourceUriProvider

RequestResourceUriProvider

Return the resource URL to include in policy decision requests to AM by using the original URI of the request or the baseURI of the route.

"resourceUriProvider": {
  "type": "RequestResourceUriProvider",
  "config": {
    "useOriginalUri": runtime expression<boolean>,
    "includeQueryParams": runtime expression<boolean>
  }
}

useOriginalUri: runtime expression<boolean>, optional

In policy decision requests to AM, use the original URI of the request as the resource URL.

• true: Use the original URI of the request as the resource URL when requesting policy decisions from AM.

• false: Use the baseURI of the route as the resource URL when requesting policy decisions from AM.

Default: false

includeQueryParams: runtime expression<boolean>, optional

Include query parameters in the resource URL when requesting policy decisions from AM:

• true: Include query parameters in the resource URL. For example, use the following URL with a query parameter: http://microgateway.example.com:8080/login?demo=capture.

• false: Exclude query parameters from the resource URL. For example, exclude the query parameter from the previous example: http://microgateway.example.com:8080/login.

  For AM policies that specify resource URLs without query parameters, use this option to reduce the amount of cached information.

Default: true

ScriptableResourceUriProvider

Use a script to return the resource URL to include in policy decision requests to AM. The result of the script must be a string that represents the resource to be used in the policy decision request sent to AM.

"resourceUriProvider": {
  "type": "ScriptableResourceUriProvider",
  "config": {
    "type": string,
    "file": expression,                     // Use either "file"
    "source": string or array of strings,   // or "source", but not both.
    "args": object,
    "clientHandler": Handler reference
  }
}

For information about these properties, see "Scripts".

The following example script replaces existing query parameters with a single parameter:

"resourceUriProvider": {
  "type": "ScriptableResourceUriProvider",
  "config": {
    "type": "application/x-groovy",
    "source": [
      "request.uri.setQuery('fromIG=true')",
      "return request.uri.toASCIIString()"
    ]
  }
}

"amService": AmService reference, required

The AmService heap object to use for the following properties:

• agent, the credentials of the TVMS agent in AM. When the agent is authenticated, the token can be used for tasks such as getting the user's profile, making policy evaluations, and connecting to the AM notification endpoint.

• url, the URL of an AM service to use for session token validation and authentication.

• amHandler, the handler to use when communicating with AM to validate the token in the incoming request.

• realm: Realm of the TVMS agent in AM.

• version: The version of the AM server.

• sessionProperties, the list of user session properties to retrieve from AM.

  The following properties are retrieved:

  • When sessionProperties in AmService is configured, listed session properties with a value.

  • When sessionProperties in AmService is not configured, all session properties with a value.

  • Properties with a value that are required by TVMS but not specified by sessionProperties in AmService. For example, when the session cache is enabled, session properties related to the cache are automatically retrieved.

  Properties with a value are returned, properties with a null value are not returned.

This filter is compatible with AM version 5 or higher.

See also, "AmService".

"ssoToken": runtime expression<string>, optional

Location of the AM SSO token. For example, with ${request.headers['mySsoToken'].values[0]} the SSO token is the first value of the mySsoToken header in the request.

Default: ${request.cookies['AmService-ssoTokenHeader'][0].value}, where AmService-ssoTokenHeader is the name of the header or cookie where the AmService expects to find SSO tokens.