9.65.2 REST Client Agent Configuration

Owned by Jenni Wallin
Last updated: Jul 31, 2024 by Hazren Sulaiman
5 min read

You open the REST Client agent configuration dialog from a workflow configuration: you can right-click the agent icon and select Configuration..., or double-click the agent icon.

Basic Tab

The Basic tab contains settings related to the location and authentication of the remote server.

REST Client agent configuration - Basic tab

SettingDescription
Base URL

Enter the base URL of the HTTP API: <protocol>://hostname:<optional-port>/<optional-path>

This is the target URL for requests from the REST Client agent.

The supported protocols are HTTP and HTTPS. If no port is specified, the agent will default to 80 for HTTP and 443 for HTTPS.

Keystore

When the protocol in the base URL is set to https, the keystore path and keystore password will be enabled.

Use Key Profile

If enabled, configures the keystore and password using an Encryption Key Profile.

Key ProfileYou can click the Browse button to open the Configuration Selection dialog box from where any existing profile can be selected.
Keystore PathThe option to include the path to a file that can contain both the keystore and truststore. It is available when HTTPS is set in the base URL.
Keystore PasswordEnter the password of the keystore/truststore file.

Note!

To generate the keystore file using , please refer to the 2.2.12 keytool command.

Note!

When the protocol is set to https but both keystore path and keystore password fields are left empty, the REST Client agent will trust all certificates.


Advanced Tab

The Advanced tab contains settings related to the HTTP/HTTPS connection and handling of incoming requests.

REST Client agent configuration - Advanced tab

SettingDescription
Timeout (ms)

Enter the maximum response time from the remote server in milliseconds.

If the response time from the server exceeds this value, the REST Client agent updates the Error field of the outgoing RESTCycleUDR. 

For further information about UDR types, see 9.52.3 REST Client UDR Types.

The default value is 5000 ms.

Max Outstanding Requests

Enter the maximum number of outstanding requests that the agent can handle simultaneously. A request that is received by the agent is considered outstanding until a corresponding response is received from the remote server.

If the number of requests exceeds this value, the REST Client agent updates the Error field of the outgoing RESTCycleUDR. New requests are not sent by the agent until the number of outstanding requests decreases.

For further information about UDR types, see 9.52.3 REST Client UDR Types.

The default value is 100 requests.

You will also be able to define the max-chunk-size and max-content-length of the requests received by the agent. You can set the properties on the EC running the REST Client agent or on a container that are running the EC's with the REST Client agents. For details on the properties, you can refer to 2.6.3 Execution Context Properties or 2.6.2 Container Properties.

Authentication Tab

The Authentication tab contains settings related to the supported authentication types that can be used by the REST Client agent. Different settings are available for the various authentication types. These include:

  • None - No authentication (default value)
  • Basic - Authentication according to the 'Basic' HTTP Authentication Scheme (RFC 7617)
  • OAuth 2.0 - Authentication according to the OAuth 2.0 Authorization Framework (RFC 6749)

None

When you select None in Authentication Type, there are no additional settings.

Basic 

Basic authentication requires a username and a password, which are base64 encoded and sent in the header of the request.

When you select Basic in Authentication Type, the following settings are available:

 

REST Client agent configuration - Authentication tab (basic)


SettingDescription
UsernameEnter a username for an account on the remote server. The username must not include colon (:) characters.
PasswordEnter the password associated with the username.

OAuth 2.0

RFC 6749 specifies four grant types for authentication. At the time of writing, the only available grant types are "Client Credentials" and "Resource Owner Password Credentials". These types require additional parameters that are sent to an authorization server. 

Client Credentials

The agent fetches the access token from the Access Token URI during initialization, using client id and client secret for basic authentication. 

The response contains an access token, which is then used in subsequent requests. 

Resource Owner Password Credentials

The agent fetches the access token from the Access Token URI during initialization, using the following credentials for authentication:

  • Client ID
  • Client Secret
  • Username
  • Password

The response contains an access token, which is then used in subsequent requests. 

Token Expiry

A request that is using invalid token, e g due to expiry,  will fail and an error code will be set in the corresponding RESTCycleUDR that the agent routes back to the workflow. 

For an expired token, server will send error response that contains header WWW-Authenticate=Bearer,error=invalid_token.

To trigger the agent to obtain a new token, you must configure the APL to resend the failed RESTCycleUDR that contains the error response back to the agent. 

Settings

REST Client agent configuration - Authentication tab (OAuth 2.0)

When you select OAuth 2.0 in Authentication Type, the following settings are available:

SettingDescription
Grant Type

Select the grant type:

  • Client Credentials - See Client Credentials above.

  • Resource Owner Password Credentials - See Resource Owner Password Credentials above

Client Auth Type

Select the client authentication method:

  • client_secret_basic - The credentials are base64 encoded and sent in the header of the request.
  • client_secret_post - The credentials are sent in the body of the request.
Client ID

Enter the unique client identifier issued by the authorization server.

Client Secret

Enter the client secret.

UsernameEnter the resource owner username, i e end-user granting access to a protected resource. This field is required when you have selected Resource Owner Password Credentials from the drop-down list Grant Type.
PasswordEnter the password associated with the username. This field is required when you have selected Resource Owner Password Credentials from the drop-down list Grant Type.
Access Token URIEnter the URI where the access token can be obtained.
Base URL Field

Some authentication servers may provide a base URL in the response body that the REST client agent must use in subsequent requests. When this is applicable, enter the name of the key in the JSON formatted string that holds the base URL. The value extracted from the response overrides, the Base URL, that you have configured in the Basic tab.

In the following example, the base URL is available in instance_url.

Example - Base URL in response from authentication server

{"access_token":"00D5E0000008lbR...",
"instance_url":"https://cs84.example.com",
"id":"https://example.com/id/00D5E0000008lbRUAQ/0055E000000HRCHQA4",
"token_type":"Bearer","issued_at":"1490699031149",
"signature":"tWccV/a3r0y/JoMRTUbpiviwmslJD2J29yTtSz7yDHE="}
Additional Parameters

Some authentication servers may require additional parameters in the body of the token requests. To add a parameter, click the Add button and then enter the name of the parameter in the Key field and the value of the parameter in the Value field.

Do not use escape characters in the value field, these will be added automatically by the REST Client agent. For instance, "https://example.com/" will be sent as "https%3A%2F%2example.com%2F".

If you need to have dynamically configurable client credentials for OAuth 2.0, you may also use the OAuth2UDR for this, see 9.65.3 REST Client UDR Types for further information.

Next:

9.65.3 REST Client UDR Types