HTTP Clients

For example, the SCIM data sources must make HTTP requests to SCIM APIs, while the JSON data source consumes a JSON-based REST API.

For this reason, the server provides configurable HTTP clients which can be used to connect to these different external services.

HTTP clients are configured separately from where they are used, under Facilities. This allows the same HTTP client to be used in multiple places.

Getting Started#

To configure an HTTP Client in the Admin UI, navigate to Facilities → HTTP Clients. From there you can create a new, or edit the existing HTTP Clients.

HTTP Client Configuration#

The following aspects of a HTTP client may be configured:

Scheme#

The scheme defines whether https or http should be used.

Use HTTPS wherever feasible. Avoid HTTP as much as possible, since it is unencrypted and insecure.

Connection Pool#

A connection pool can be enabled so that TCP connections to the same host may be re-used by a HTTP client to make separate HTTP requests.

By default, no connection pool is used.

When enabled, HTTP clients can re-use TCP connections to the same host for separate HTTP requests.

Authentication#

Different HTTP clients can have different authentication methods.

Available authentication methods:

• Basic authentication
• OAuth client credentials
• Client certificates (see below)

TLS (encryption)#

When HTTPS is used, the HTTP client will use TLS to establish encrypted connections.

Server certificates can be verified with a configured trust store, or with the default Java trust store.

A client-keystore can also be configured so that the client can utilize mutual TLS.

Hostname verification can be disabled for debugging purposes.

For more details about truststores and keystores, see Keys and Cryptography .

Proxies#

A proxy server can be configured for each HTTP client. Optionally, user credentials can be configured for proxy authentication.

Custom Headers#

Operators can attach custom HTTP request headers to every outbound request made by an HTTP client. Each entry has a name and exactly one value source:

• Static value — a configured string sent verbatim on every request.
• OAuth client — the client_id of the OAuth client of the current request. When no OAuth client is present in the request context (for example, when the HTTP client is invoked from an admin flow or a startup task), the header is silently omitted from that request and a DEBUG log line records the omission. The request itself still succeeds. This makes a given HTTP client safely reusable across OAuth and non-OAuth call paths.
• Server ID — the configured server ID of the running server.

Header names are unique within an HTTP client (the list is keyed by name). The following names are reserved and rejected at configuration time, case-insensitively: Authorization, Host, Content-Length, Content-Type, Transfer-Encoding, Connection, Upgrade, Proxy-Authorization, Expect, TE, Trailer.

Metrics#

HTTP clients can be configured to expose metrics about requests and about the connection pool (if enabled). Request metrics are defined based on the class of response status codes (successful, client error and server error) and include labels for the HTTP client and target host. Connection pool metrics expose measurements such as the pool size and the used connections, and include a label for the HTTP client. For details on the available metrics refer to Operation and Monitoring .

Note that request metrics are captured from the perspective of HTTP client consumers, which may not match the requests actually sent to the target host. For example, if a request is retried, metrics account for a single request.

See also#