PingGateway 2024.9

ClientHandler

Sends requests to third-party services that are accessible through HTTP, and reconstructs the response from the received bytes. A third-party service is one that PingGateway calls for data, such as an HTTP API or AM, or one to which PingGateway submits data. When PingGateway relays a request to a third-party service, PingGateway is acting as a client of the service. PingGateway is client-side.

Consider the following comparison of the ClientHandler and ReverseProxyHandler:

ClientHandler ReverseProxyHandler

Use this handler to …​

Send requests to third-party services accessed within a route. The service can be AM or an HTTP API. The service can be an HTTP endpoint, such as AM, IDM, PingOne Advanced Identity Cloud, or any custom HTTP API.

Send requests to the final service accessed by a route. The service can be the final downstream application.

If the service does not respond in time, this handler …​

Propagates the error through the Promise flow.

If the error is not handled within the route, for example, by a FailureHandler, the handler returns a 500 Internal Server Error response.

Stops processing the request, and returns a 502 Bad Gateway response.

When uploading or downloading large files, prevent timeout issues by increasing the value of soTimeout, and using a streaming mode, as follows:

Configure the streamingEnabled property of AdminHttpApplication.

Usage

{
  "name": string,
  "type": "ClientHandler",
  "config": {
    "vertx": object,
    "connections": configuration expression<number>,
    "waitQueueSize": configuration expression<number>,
    "soTimeout": configuration expression<duration>,
    "connectionTimeout": configuration expression<duration>,
    "protocolVersion": configuration expression<enumeration>,
    "http2PriorKnowledge": configuration expression<boolean>,
    "proxyOptions": ProxyOptions reference,
    "temporaryStorage": TemporaryStorage reference,
    "tls": ClientTlsOptions reference,
    "retries": object,
    "circuitBreaker": object,
    "hostnameVerifier": configuration expression<enumeration>, //deprecated
    "proxy": Server reference, //deprecated
    "systemProxy": boolean //deprecated
  }
}

* Legacy; no longer supported

Properties

"vertx": object, optional

Vert.x-specific configuration for the handler when PingGateway is client-side. When PingGateway is acting server-side, configure the connectors:vertx property of admin.json.

When PingGateway sends requests to a proxied application or requests services from a third-party application, PingGateway is client-side. PingGateway is acting as a client of the application, and the application is acting as a server.

Vert.x options are described in HttpClientOptions.

The vertx object is read as a map, and values are evaluated as configuration expressions.

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

  • alpnVersions

  • connectTimeout

  • enabledCipherSuites

  • enabledSecureTransportProtocols

  • http2ClearTextUpgrade

  • idleTimeout

  • idleTimeoutUnit

  • keyCertOptions

  • keyStoreOptions

  • maxWaitQueueSize

  • pemKeyCertOptions

  • pemTrustOptions

  • pfxKeyCertOptions

  • pfxTrustOptions

  • port

  • protocolVersion

  • proxyOptions

  • ssl

  • trustOptions

  • trustStoreOptions

  • useAlpn

  • verifyHost

The following example configures the Vert.x configuration when PingGateway is acting client-side. When PingGateway is acting server-side, configure the connectors:vertx property of admin.json:

{
  "vertx": {
    "maxWebSocketFrameSize": 128000,
    "maxWebSocketMessageSize": 256000,
    "compressionLevel": 4,
    "maxHeaderSize": 16384
  }
}

The following example configures HTTP/2 connections when PingGateway is acting client-side. The configuration allows PingGateway to make HTTP/2 requests with large headers. When PingGateway is acting server-side, configure the connectors:vertx property of admin.json:

{
  "vertx": {
    "initialSettings": {
      "maxHeaderListSize": 16384
    }
  }
}
"connections": configuration expression<number>, optional

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

For information about the interaction between this property and waitQueueSize, see the description of waitQueueSize.

Default: 64

“waitQueueSize”: configuration expression<number>, optional

The maximum number of outbound requests allowed to queue when no downstream connections are available. Outbound requests received when the queue is full are rejected.

Use this property to limit memory use when there is a backlog of outbound requests, for example, when the protected application or third-party service is slow.

Configure waitQueueSize as follows:

  • Not set (default): The wait queue is calculated as the square of connections.

    • If connections is not configured, then its default of 64 is used, giving the waitQueueSize of 4096.

    • If the square of connections exceeds the maximum integer value for the Java JVM, the maximum integer value for the Java JVM is used.

  • -1: The wait queue is unlimited. Requests received when there are no available connections are queued without limit.

  • 0: There is no wait queue. Requests received when there are no available connections are rejected.

  • A value that is less than the square of connections:

    When the configuration is loaded, the configured value is used. PingGateway generates a warning that the waitQueueSize is too small for the connections size, and recommends a different value.

  • A value where waitQueueSize plus connections exceeds the maximum integer value for the Java JVM:

    When the configuration is loaded, the waitQueueSize is reduced to the maximum integer value for the Java JVM minus the value of connections. PingGateway generates a warning.

Consider the following example configuration of connections and waitQueueSize:

{
  "handler" : {
    "name" : "proxy-handler",
    "type" : "ReverseProxyHandler",
    "MyCapture" : "all",
    "config": {
      "soTimeout": "10 seconds",
      "connectionTimeout": "10 seconds",
      "connections": 64,
      "waitQueueSize": 100
    }
  },
  "baseURI" : "http://app.example.com:8080",
  "condition" : "${find(request.uri.path, '/')}"
}

PingGateway can propagate the request to the sample application using 64 connections. When the connections are consumed, up to 100 subsequent requests are queued until a connection is freed. Effectively PingGateway can accommodate 164 requests, although user concurrency delay means more may be handled. Requests received when the waitQueue is full are rejected.

Default: Not set

"connectionTimeout": configuration expression<duration>, optional

Time to wait to establish a connection, expressed as a duration

Default: 10 seconds

"protocolVersion": configuration expression<enumeration>, optional

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

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

A flag for whether the client should have prior knowledge that the server supports HTTP/2. This property is for cleartext (non-TLS requests) only, and is used only when protocolVersion is HTTP/2.

  • 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

"proxyOptions": ProxyOptions 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.

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

Default: A heap object named ProxyOptions.

"soTimeout": configuration expression<duration>, optional

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

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

Default: 10 seconds

"temporaryStorage": TemporaryStorage reference, optional

The TemporaryStorage object to buffer the request and response, when the streamingEnabled property of admin.json is false.

Default: A heap object named TemporaryStorage.

tls: ClientTlsOptions reference, optional

Use of a TlsOptions reference is deprecated; use ClientTlsOptions instead. For more information, refer to the Deprecated section of the Release Notes.

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.

"retries": object, optional

Enable and configure retry for requests.

During the execution of a request to a remote server, if a condition is met, a runtime exception occurs, or a matching runtime exception condition is met, PingGateway waits for a delay, then schedules a new execution of the request. PingGateway tries until the allowed number of retries is reached or the execution succeeds.

A warning-level entry is logged if all retry attempts fail; a debug-level entry is logged if a retry succeeds.

"retries": {
  "enabled": configuration expression<boolean>,
  "condition": runtime expression<boolean>,
  "executor": ScheduledExecutorService reference,
  "count": configuration expression<number>,
  "delay": configuration expression<duration>,
  "runtimeExceptionCondition": runtime expression<boolean>
  }
}
"enabled": configuration expression<boolean>, optional

Enable retries.

Default: true

"condition": runtine expression<boolean>, optional

An inline PingGateway expression to define a condition based on the response, such as an error code.

The condition is evaluated as follows:

  • If true, PingGateway retries the request until the value in count is reached.

  • If false, PingGateway retries the request only if a runtime exception occurs, until the value in count is reached.

    Default: ${false}

"executor": ScheduledExecutorService reference, optional

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

Default: ScheduledExecutorService

See also ScheduledExecutorService.

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

Retries caused by any runtime exception or triggered condition are included in the count.

Default: 5

"delay": _configuration expression<duration>, optional

The time 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

"runtimeExceptionCondition": runtine expression<boolean>, optional

An inline expression to define a condition when a runtime exception occurs. The context, request, and exception are available in the expression.

  • If true, PingGateway retries the request until the value in count is reached.

  • If false, PingGateway doesn’t retry the request.

Default: When this is not set, retry when any runtime exception occurs.

The following example configures a retry when a downstream component returns a 502 Bad Gateway response code:

"retries": {
    "enabled": true,
    "condition": "${response.status.code == 502}"
}

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 retries the request only when a runtime expression for an HTTP/2 GOAWAY error occurs:

{
    "retries": {
        "enabled": true,
        "runtimeExceptionCondition": "${exception.message.contains(\"GOAWAY\")}"
    }
}

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
      }
    }
  }
}
"circuitBreaker": object, optional

Enable and configure a circuit breaker to trip when the number of failures exceeds a configured threshold. Calls to downstream services are stopped, and a runtime exception is returned. The circuit breaker is reset after the configured delay.

{
  "circuitBreaker": {
    "enabled": configuration expression<boolean>,
    "maxFailures":  configuration expression<integer>,
    "openDuration": configuration expression<duration>,
    "openHandler": Handler reference,
    "slidingCounter":  object,
    "executor":  ScheduledExecutorService reference
  }
}
"enabled": configuration expression<boolean>, optional

A flag to enable the circuit breaker.

Default: true

"maxFailures": configuration expression<number>, required

The maximum number of failed requests allowed in the window given by size, before the circuit breaker trips. The value must be greater than zero.

When retries is set, the circuit breaker does not count retried requests as failures. Bear this in mind when you set maxFailures.

In the following example, a request can fail and then be retried three times. If it fails the third retry, the request has failed four times, but the circuit breaker counts only one failure.

{
  "retries": {
    "count": 3,
    "delay": "1 second"
  }
}
"openDuration": configuration expression<duration>, required

The duration for which the circuit stays open after the circuit breaker trips. The executor schedules the circuit to be closed after this duration.

"openHandler": Handler reference, optional

The Handler to call when the circuit is open.

Default: A handler that throws a RuntimeException with a "circuit-breaker open" message.

"slidingCounter": object, optional

A sliding window error counter. The circuit breaker trips when the number of failed requests in the number of requests given by size reaches maxFailures.

The following image illustrates how the sliding window counts failed requests:

Example sliding window error counter. 
{
  "slidingCounter":  {
    "size": configuration expression<number>
  }
}
"size": configuration expression<number>, required

The size of the sliding window in which to count errors.

The value of size must be greater than zero, and greater than the value of maxFailures, otherwise an exception is thrown.

"executor": ScheduledExecutorService reference, optional

A ScheduledExecutorService to schedule closure of the circuit after the duration given by openDuration.

Default: The default ScheduledExecutorService in the heap

"hostnameVerifier": configuration expression<enumeration>, optional
This property is deprecated; use the tls property instead to configure ClientTlsOptions. For more information, refer to the Deprecated section of the Release Notes.

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

    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

"proxy": Server reference, optional
This property is deprecated; use proxyOptions instead. For more information, refer to the Deprecated section of the Release Notes.

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.

This secret ID must point to a GenericSecret.

"secretsProvider": SecretsProvider reference, required

The SecretsProvider to query for the proxy’s password.

"systemProxy": boolean, optional
This property is deprecated; use proxyOptions instead. For more information, refer to the Deprecated section of the Release Notes.

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, refer to Java Networking and Proxies.

Default: False.

"keyManager": Key manager reference(s), optional
This property is deprecated; use the tls property instead to configure ClientTlsOptions. For more information, refer to the Deprecated section of the Release Notes.

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

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

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

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

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

"sslCipherSuites": array of strings, optional
This property is deprecated; use the tls property instead to configure ClientTlsOptions. For more information, refer to the Deprecated section of the Release Notes.

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

For information about the available cipher suite names, refer to the documentation for the Java virtual machine (JVM) where you run PingGateway. For Oracle Java, refer to the list of JSSE Cipher Suite Names.

Default: Allow any cipher suite supported by the JVM.

"sslContextAlgorithm": string, optional
This property is deprecated; use the tls property instead to configure ClientTlsOptions. For more information, refer to the Deprecated section of the Release Notes.

The SSLContext algorithm name, as listed in the table of SSLContext Algorithms for the Java Virtual Machine used by PingGateway.

Default: TLS

"sslEnabledProtocols": array of strings, optional
This property is deprecated; use the tls property instead to configure ClientTlsOptions. For more information, refer to the Deprecated section of the Release Notes.

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

Default: Allow any protocol supported by the JVM.

"trustManager": Trust manager reference(s), optional
This property is deprecated; use the tls property instead to configure ClientTlsOptions. For more information, refer to the Deprecated section of the Release Notes.

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

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

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

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

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

More information

org.forgerock.openig.handler.ClientHandlerHeaplet