Http Client service

The new Http Client service lets you create named instances that you can reference from a next-generation script.

On each instance, define secret labels that are mapped to certificates in ESVs and used during mTLS connections.

The service also provides settings for connection and response timeouts and for disabling some or all certificate checks on your instances.

Example: Send a request using mTLS

Configure the httpclient to use mTLS to exchange data securely when making an HTTP request to an external service.

Follow these example steps to send an HTTP request using mTLS:

Configure an instance of the HTTP Client service
Map a client certificate to a secret label
Create a script to send the request

Configure the Http Client service

Complete these steps to configure an instance of the Http Client service.

The instance defines settings such as timeout values and the client certificate or truststore secret labels required by the httpclient script binding to make a TLS connection.

For details about these settings, refer to Configuration (Realm defaults).

In the AM admin UI (native console), go to Realms > Realm Name > Services.
Click Add a Service and select Http Client Service from the service type drop-down list.
Enable the service and save your changes.
On the Secondary Configurations tab, click Add a Secondary Configuration.
Provide a name for the HTTP client instance; for example, myHttpClient, and click Create.
Enable the instance and save your changes.

On the TLS Configuration tab, enter an identifier to be used in your secret label in the Client Certificate Secret Label Identifier field.

For example, testCrt creates the dynamic secret label, am.services.httpclient.mtls.clientcert.testCrt.secret.

To specify a truststore to verify the target server’s certificate, provide a value for Server Trust Certificates Secret Label Identifier.

This creates the dynamic secret label, am.services.httpclient.mtls.servertrustcerts.identifier.secret.

Save your changes.

Map a base64-encoded PEM certificate to the secret label

To prepare a certificate for TLS connections, it must be:

Base64-encoded
A file containing both a private and public key
Uploaded as an ESV using the API

Complete these steps to generate a key pair and map the secret to the dynamic secret label created in the previous step.

Generate a private key and a public key, as described in Generate an RSA key pair.

You should now have a .pem file that contains a base64-encoded key pair. PingOne Advanced Identity Cloud shares the public key and uses the private key to sign the request.
Get an access token for the realm.

Specify the access token in a REST API call to create a PEM-encoded ESV secret.

For example, to create a secret named esv-mtls-cert:

$ curl \
--request PUT 'https://<tenant-env-fqdn>/environment/secrets/<esv-mtls-cert>' \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--header 'Accept-API-Version: protocol=1.0;resource=1.0' \
--data-raw '{
    "encoding": "pem",
    "useInPlaceholders": false,
    "valueBase64": "<base64-encoded PEM-file>"
}'

You must specify the encoding type as pem for the API to recognize the value as a certificate.

Map the secret against the secret label created when you configured the Http Client service, for example:

Secret Label

am.services.httpclient.mtls.clientcert.testCrt.secret

alias

esv-mtls-cert

The certificate is now uploaded and mapped to the secret label.

Create a script to send the HTTP request

Write a next-generation decision node script to send a request using the HTTP client instance in the request options.

In your script, specify your HTTP client instance as the value for clientName in requestOptions.

For example:

 var requestOptions = {
    "clientName": "<myhttpclient>"   (1)
 }
var res = httpClient.send("https://example.com",
                                    requestOptions).get(); (2)
action.withHeader(Response code: ${res.status});

if (res.status == 200) {
  action.goTo("true").withDescription(response.text());
} else {
  action.goTo("false");
};

1	The `clientName` attribute must reference an enabled instance of the Http Client service.
2	The `httpClient` sends the request to an mTLS endpoint that checks for a certificate.

Create a simple journey that includes the scripted decision node to test your changes.
Verify that the HTTP request is sent successfully.

Configuration (Realm defaults)

The following settings appear on the Realm Defaults tab:

Enabled: Enable this Http Client service to use the secondary configurations when making HTTP requests.

Secondary configurations

This service has the following secondary configurations.

Configure instances of the Http Client service to control how and which certificates AM uses in TLS connections.

A secondary configuration instance has the following tabs:

Configuration

Enabled: Enable this Http Client instance.

TLS Configuration

Client Certificate Secret Label Identifier

PingOne Advanced Identity Cloud uses this identifier to create a specific secret label, using the template am.services.httpclient.mtls.clientcert.identifier.secret where identifier is the value of Client Certificate Secret Label Identifier.

The identifier can only contain alphanumeric characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

If this field is empty, the Http Client service doesn’t attach a client certificate to HTTP requests that use mTLS to connect with a target server.

Server Trust Certificates Secret Label Identifier

PingOne Advanced Identity Cloud uses this identifier to create a specific secret label, using the template am.services.httpclient.mtls.servertrustcerts.identifier.secret where identifier is the value of Server Trust Certificates Secret Label Identifier.

The identifier can only contain alphanumeric characters a-z, A-Z, 0-9, and periods (.). It can’t start or end with a period.

If this field is empty, the system truststore is used when attempting to verify the target server’s certificate during a TLS connection.

Disable Certificate Revocation Check

If enabled, Advanced Identity Cloud doesn’t check certificate revocation lists when performing a TLS connection with the target server.

Trust All Certificates

If enabled, all certificates are trusted when performing a TLS connection with the target server.

Don’t enable this setting in a production environment. It is intended for testing purposes only.

Timeouts

Use Instance Timeouts: If enabled, Advanced Identity Cloud uses the connection and response timeouts defined in this Http Client service instance.
Connection Timeout (secs): The maximum time (in seconds) to wait for a connection to be established before failing.

Default value: 10
Response Timeout (secs): The maximum time (in seconds) to wait for a response from the target server before failing.

Default value: 10