HTTP Client node

The HTTP Client node lets you make direct HTTP(S) requests to external APIs and services from within an authentication journey. This simplifies integration with a range of external services to invoke actions or retrieve data for use in a journey.

The HTTP Client node can make GET, POST, PUT, DELETE, PATCH, and HEAD requests. Requests can include headers, request parameters, payloads, and certificates for endpoints secured using mTLS. The node can also save the response body to shared state, and you can configure the handling of response codes.

Compatibility

Product	Compatible
ForgeRock Identity Cloud	Yes
ForgeRock Access Management (self-managed)	Yes ¹
ForgeRock Identity Platform (self-managed)	Yes ¹

Product

Compatible

ForgeRock Identity Cloud

Yes

ForgeRock Access Management (self-managed)

Yes ¹

ForgeRock Identity Platform (self-managed)

Yes ¹

¹ For self-managed products, download the node from ForgeRock Marketplace.

Inputs

Any data in shared state that you need to include in the headers, parameters, or payload/body of the request.

Dependencies

This node has no specific dependencies.

If you use this node to make calls to endpoints secured with Mutual Transport Layer Security (mTLS), you must provide a valid X.509 digital certificate.

Configure the node with both the public certificate and private key in PEM format.

You can add the certificates and key values directly to the node configuration, or store the secrets as ESVs.

Configuration

Property Usage

Rest URL

The endpoint URL, including scheme, port (optional), and path (optional). For example: https://postman-echo.com/post.

You can use the values of shared state variables by including the variable name in handlebars (${variable name}). For example:

`\https://postman-echo.com/postman/${username}/account`

where username is set in the shared state.

You can also use JSONpath expressions to select specific values or branches from JSON objects stored in shared state variables. Learn more in Variable substitution.

Request Method

The request type: GET, POST, PUT, DELETE, PATCH, or HEAD.

Query Parameters

An optional set of key-value pairs added as query parameters.

You can use the values of shared state variables by including the variable name in handlebars (${variable name}). For example, to include a query parameter named user_id map this parameter to the username property in shared state as follows:

Key: user_id
Value: ${username}

You can also use JSONpath expressions to select specific values or branches from JSON objects stored in shared state variables. Learn more in Variable substitution.

Headers

An optional set of key-value pairs to be added as request headers.

You can use the values of shared state variables by including the variable name in handlebars (${variable name}). You can also use JSONpath expressions to select specific values or branches from JSON objects stored in shared state variables. Learn more in Variable substitution.

Use HTTP "Basic" Authentication

Includes an HTTP Basic Authentication header.

HTTP "Basic" Username

The username for HTTP Basic Authentication.

HTTP "Basic" Password

The password for HTTP Basic Authentication.

Body Content

An optional value to include in the request payload or body. The payload format depends on the REST endpoint and can include JSON, XML, plain text, or other data.

You can use the values of shared state variables by including the variable name in handlebars (${variable name}).

This example includes a header named X-Transaction-ID with the value of username in the shared state:
```
Key: X-Transaction-ID
Value: ${username}
```
This example includes a JSON payload with values automatically substituted from shared state variables:
```
{ "uid": "${username}", "first_name":"${givenName}", "last_name":"${sn}", "active": true }
```
This example includes a form payload (application/x-www-form-urlencoded):
```
uid=${username}&first_name=${givenName}&last_name=${sn}&active=true
```
If a requested shared state variable is not set, the node substitutes a null value.

You can also use JSONpath expressions to select specific values or branches from JSON objects stored in shared state variables. Learn more in Variable substitution.

Body Content Encoding

The request body type: XWWWFORMURLENCODED, JSON, XML, PLAIN, or CUSTOM. Use the CUSTOM type to configure a header named content-type in the Headers configuration.

Use mTLS

Enable this option for endpoints that require mTLS authentication. If enabled, also configure the mTLS Public Certificate and mTLS Private Key.

mTLS Public Certificate

The client X.509 public certificate in PEM format.

For more flexibility, store the certificate as an ESV.

mTLS Private Key

The client private key for the X.509 certificate in PEM format. Private keys should be in PKCS8 format, typically with the PEM header value of -----BEGIN PRIVATE KEY-----. Private key should not be in PKCS1 format, typically with a PEM header value of -----BEGIN RSA PRIVATE KEY-----.

If the private key is a PKCS1 key, you must convert the key to PKCS8. To make the conversion:

Execute the following openssl command:

openssl pkcs8 -topk8 -inform PEM -outform PEM \
-nocrypt -in <PKCS1_PRIVATE_KEY.pem> -out <PKCS8_PRIVATE_KEY.pem>

Use the contents of <PKCS8_PRIVATE_KEY.pem> for the value of mTLS Private Key.

For more flexibility, store the key as an ESV.

Disable Certificate Checks

If you select this option, Identity Cloud ignores certificate errors, such as expired certificates, associated with the external endpoint.

This option applies only to server certificate validation checks, and not to client certificates. Trusting expired and invalid certificates can have serious security implications. Don’t disable certificate checks in a production environment.

Timeout (seconds)

The timeout value (in seconds) for the request. The same timeout value is used for establishing the connection to the endpoint and for awaiting a response.

Response Codes

By default, this node logs Default Response and Error outcomes. Optionally, specify other response codes to add new outcomes. For example, you can add 200 and 401 codes to add two additional outcomes for handling OK and Unauthorized outcomes.

Use response code classes to handle a range of response codes. For example, to capture all client error responses in the range 400-499 and server error responses in the range 500-599, add the values 4xx and 5xx. This results in two additional outcomes that can be handled appropriately in the journey.

Any matched JSON Response Outcome takes precedence over the defined response code outcome.

Status Code Shared State Variable

(Optional) The shared state variable in which to store the response code.

Returned Body Shared State Variable

(Optional) The shared state variable in which to store the response body.

JSON Response Handler

For REST calls that return a JSON formatted response, specific returned values or JSON paths of the response are mapped to shared state variables. Define the key-value pairs where key is the shared state variable name and value is the JSONpath expression of the data to be saved. Learn more about JSONpath expressions in Variable substitution.

JSON Response Outcome Handler

Returned values from JSON formatted response can be evaluated and used to trigger appropriate outcomes from the node. Subsequent journey steps can handle the evaluated outcomes appropriately.

Outcomes are defined by key-value pairs, where key is the name of the outcome, and value is the JSONpath expression. The value is evaluated on the returned JSON data. JSONpath expressions act as filters on JSON arrays of data. An expression that results in a non-empty array is considered a successful match and should trigger the associated outcome. Learn more about JSONpath expressions in Variable substitution.

An outcome matched by the JSON Response Outcome Handler overrides any outcome defined by a response code. For example, if a response code outcome is defined for code "200", but the JSON Response Outcome Handler is also matched, then the outcome of the JSON Response Outcome Handler will be followed.

Variable substitution

A number of this node’s configuration properties let you retrieve values from or save values to shared state variables. For these properties, you can use variable substitution in the format ${variable}. For example, to include the username in a URL path, you can use an expression similar to:

`\https://postman-echo.com/postman/${username}/account`

where username is the name of a variable currently set in shared state.

If the value in shared state is a JSON object, you can use JSONpath notation to select specific values, array items, or complete branches of the JSON object.

To use JSONpath expressions for variable substitution, use an expression of the form ${shared state variable.$.path}. Assume, for example, the shared state variable objectAttributes containing the following JSON data:

{
"username": "bob",
"firstName": "Bob",
"lastname": "Fleming",
"telephoneNumber": "+1(555)1231234",
"bookingIDs": [ 29872, 23884, 48382 ],
"membershipTier": "platinum"
}

The firstname and lastname attributes can be selected as ${objectAtttributes.$.firstname} and ${objectAttributes.$.lastname}, respectively. The last bookingID can be selected as ${objectAttributes.$.bookingIDs[2]} or ${objectAttributes.$.bookingIDs[-1]}.

You can use similar notation with the JSON Response Handler property to save returned JSON response values to shared state.

For example, if the JSON object is the response to a REST API call, the following JSON Response Handler configuration selects the telephone number from the response and saves it to the phone shared state variable:

Key: phone
Value: $.telephoneNumber

The JSON Response Outcome Handler can be filtered with a suitable JSONpath expression to look for matching responses. A matching outcome is triggered when the JSONpath expression, when applied to an array containing the JSON response, finds at least one match. For example, if the previous JSON object is the response to a REST API call, the following JSON Response Outcome Handler configuration triggers the Priority outcome:

Key: Priority
$.[?(@.membershipTier == 'platinum')]

Learn more about JSONpath expressions in the README.

Outputs

Response code values and response body can be saved to shared state for use by subsequent nodes in the journey. Learn more in Configuration.

Outcomes

Matching JSONpath Outcomes: You can add outcomes for specific JSON response data. Learn more in the JSON Response Outcome Handler property.
Response Codes: You can configure outcomes dynamically for specific response codes, such as 401, and response code classes, such as 2xx. Learn more in the Response Code property.
Default Response: The request is completed, but no other JSON response or response code outcomes were matched.

This outcome indicates that a request and response were successfully processed, including responses indicating errors such as 4xx, (client error). If you want to handle error responses separately, consider adding response code outcomes.

Error: An error occurred causing the request to fail. Check the response code, response body, or logs for details of the error.

In cases where multiple outcomes could apply, JSON response outcomes take precedence. For example, a REST call could result in both a matching JSON response outcome and a 200 response code outcome. The matched JSON response outcome is triggered in this case.

Troubleshooting

If this node logs an error, review the log messages to find the reason for the error and address the issue appropriately. You can use many publicly accessible test endpoints, such as https://httpstat.us and https://postman-echo.com, to test and troubleshoot this node.