Set up a digest-based HTTP connection

You can build integrations with apps that use the HTTP application connector, even if the specific app connector is not already provided by integrator.io.

Before creating the connection, review your app’s API guide. It will provide the information you need, such as the kind of authentication that the app requires and its URI. Every app puts its documentation – guides and reference material – in different places. You can often find it by searching for “API guide” or “API documentation” on the company’s website.

Tip: Some companies put their documentation on third-party sites. If you can’t find the guide on their website, you can also try a web search.

Why use the Digest authentication type?

Although the HTTP/1.0 protocol includes a Basic authentication scheme, this is not considered to be a secure method of user authentication, as the username and password are passed over the network in an unencrypted form. The Digest authentication type, on the other hand, does not send the password in cleartext, thus avoiding the most serious flaw of Basic authentication. However, it does not meet all security needs and does not encrypt message content.

1. Create the HTTP connection

1. Sign in to integrator.io.
2. From the Resources menu, select Connections. The resulting page displays a list of all of the connections in your account. If you are in the Flow Builder, create a new flow step and select HTTP from the Applications list, then skip to the next section.
3. Click + Create connection at the top right. The Create connection pane opens.
4. Select HTTP from the list of connection types. (It is usually quickest to enter a few characters to start searching.)
5. Give your connection a name that is meaningful to your integration and that can help you identify it later in a list of connections, and click Next.

2. Identify the location where the HTTP application is running

Note: For on-premise mode, an agent must first be installed and configured. If the system you want to connect to is behind a firewall, the agent helps connect you without having to whitelist any IPs.

Mode (required): Choose either... 

• Cloud – Connect to an app on the cloud.
• On-premise – An on-premise app runs locally on the company’s servers. This mode requires an integrator.io agent:
  
  • From the Agent dropdown, select an installed agent.

3. Authorize the connection

Continuing in the Create connection pane, at a minimum you must provide your username and password to establish a connection with Digest authentication.

Authentication type (required): Select Digest. (Cookie-based, custom, OAuth 2.0, and token authentication are treated separately.) This authentication method adds Base64-encoded username and password values in the Authentication HTTP request header.

Configure HTTP headers (optional): Specify additional parameters as name-value pairs to pass in the header, as needed for your integration.

Base URI (required): Enter the base URI, which is the path to the app’s API, as documented in the API guide. 

Media type (required): Choose the format for your records.

Encrypted (optional): If the application expects any value to be set in its URI, header or body, use Encrypted and Unencrypted fields to store values. Use {{{connection.http.encrypted.<keyName>}}} in the places where you would like to store sensitive values.

Unencrypted (optional): If the application expects any value to be set in its URI, header or body, use Encrypted and Unencrypted fields to store values. Use {{{connection.http.unencrypted.<keyName> in the places where you would like to store other values.

Username (required): Enter the Digest authentication username for the server. Username and password information will be used in generating the digested string and added in the Authorization header during API calls.

Password (required): Enter the password. Multiple layers of protection are in place, including AES 256 encryption, to keep your password safe.  

4. Test and save the connection

Ping method (optional): Select the HTTP method to use when making the ping request.

Ping URI (required): Enter the relative URI to a specific resource, as documented in your app’s API guide. (The ping URI is relative to the base URI.) This field is required for testing the connection.

Ping success path (optional): Provide the location of custom error codes, as documented in the error schema in your app’s API guide.

A success path is necessary only if your app returns errors outside of the standard 4xx and 5xx status codes. For example, Slack sets a field in the response body and returns a 200 HTTP status code, whether or not the ping HTTP request failed. In such cases, for the Ping success path value, you can specify the JSON path of a field in the response body that should instead be used to determine if a ping request succeeded. For example, if you are building a connection to the Slack API, set this field to ok (see Slack API docs for more info).

Ping success values (optional): Enter the values to test whether a connection succeeded. This optional field is used in conjunction with the Ping success path field. The value found in the HTTP response at the path provided is compared against this list of success values. If there is an exact case-sensitive match of any of the values, then the request is considered successful.

Click Test connection to try connecting before you save these values. If the connection fails, double-check the provided settings, and test again.