Generic HTTP Connector

Descope's HTTP Connector is a generic connector that can integrate any 3rd-party API with Descope. This connector can pull data into the flow for subsequent actions or conditionals or push data from your flow to the 3rd party endpoint.

There are many different use cases for the generic HTTP connector, but here is an example: integrating into existing user storage and pulling data on the user to store in Descope.

This guide is focused on the advanced usage of the generic HTTP connector within Descope. There is a generalized configuration example of the generic HTTP connector here.

Settings

Below is the list of settings and configurations available that you can customize for your Generic HTTP Connector.

Testing the Connector

Testing your connector from the Descope console allows you to test your connector to ensure functionality.

Below is an example of the test functionality using a generic HTTP connector against a user database and return the user details in the test results panel.

Handle HTTP Response Codes from Connectors

Descope allows you to retrieve and utilize HTTP response codes within your flow. Using these status codes returned by the API is very helpful to take your users down different flow paths.

In the example below, we showcase configuring the connector action, creating a condition based on the status codes, and configuring a flow to take the users down different paths based on 404 and 429 status codes.

This flow takes the user's email and then queries an API to verify if the email exists as a user in a 3rd party system through the HTTP Connector.

Enable Custom Error Handling

The first step is to open your connector action and configure the error handling to be Custom. If the connector action returns a 200 status code, the flow progresses and authenticates the user, but if it returns a code other than 200, we will handle that with a conditional via the custom error handling.

Add Status Code Handling via Condition

The status code of your connector action can be used with a key similar to this connectors.httpResult.statusCode. Where the httpResult is where you store the connector response within the Context Key configuration of the action.

In this example, we will capture status codes other than 200 within this condition, and handle the below scenarios.

• If the API does not find an existing user, the API returns a status code of 404, and the user is directed to a screen saying, "User Not Found, contact support."
• If a 429 rate limit error is returned, the user will return to the sign-in screen to try again.
• If there is any other HTTP response error besides 404 or 429, the user is redirected back to the start of the flow.

Connect the Flow

Once you have configured the conditional and the custom error handling for the action, this is an example of how the complete flow would look like.

Access HTTP Response Headers within Flow

Descope allows you to access the headers from the HTTP response within your flow. This is helpful if you return data in the headers from your third-party endpoint which you would like to then user during the flow execution.

To enable this feature, edit your connector and select the checkbox for Include response headers in Context. Checking this box enables the context to also store the headers returned from the connector. The context will have a body attribute and a headers attribute.

Once you have this configuration enabled, you can use the headers returned from the connector in your flow. Within this example, we utilize a custom claims action to get one of the headers and append it to the JWT. The context key in this scenario will look something like connectors.httpResult.headers.x.

Here's an example of a JWT that we added data from the custom header to:

{
  "amr": [
    "email"
  ],
  "customHeader": "My header value",
  "drn": "DS",
  "exp": 1710449474,
  "iat": 1710448874,
  "iss": "xxxx",
  "rexp": "2024-04-11T20:41:14Z",
  "sub": "xxxx"
}

Customizing HMAC Signature

Descope allows you to customize the HMAC signature to include various data from the request in the signing process. These data items include the timestamp, HTTP method, URI, body, custom headers, etc. Below, you will find an example of configuring this signature and how to validate the HMAC signature within your endpoint based on the template included in the request.

Configuring HMAC Signature template

You can configure the HMAC signature template within the HTTP Connector configuration and add the HMAC Secret. The signature template is configured as a request header with the key of x-descope-signature-template. The value of this header will depend on what data you want to use within the request's HMAC signing process.

An example of signing the request with the HTTP method, URI, timestamp, and body would be METHOD,URI,HEADER_x-descope-timestamp,BODY. See the below example of a connector configured with a signature template.

Signature Headers

When your endpoint receives the request, it will have the x-descope-signature-template and x-descope-webhook-s256 headers. The request signature (x-descope-webhook-s256) is generated using this template and the secret.

Below is an example of the headers the above configured HMAC signature template sent to an endpoint.

{
  ...
  'x-descope-webhook-s256': 'xxxxxxxx',
  'x-descope-timestamp': '1717787565548',
  'x-descope-signature-template': 'METHOD,URI,HEADER_x-descope-timestamp,',
  ...
}

Validating Signature Template

Below is an example of validating the HMAC signature based on the incoming signature template. This example parses the x-descope-signature-template and computes the HMAC to compare to the received HMAC.

import crypto from "crypto";
 
export async function validateHMAC(thisRequest) {
  const SECRET = "ConfiguredSigngingSecret";
  const method = thisRequest.method;
	const uri = thisRequest.url; // Note that the URI is already endcoded when sent from Descope
	const headers = thisRequest.headers;
	const body = JSON.stringify(thisRequest.body || {});
 
	const signatureTemplate = headers["x-descope-signature-template"] || '';
  let sig = ""
 
	// Constructing the signing string
  if (signatureTemplate.includes("BODY")){
	  sig = signatureTemplate.replace("METHOD", method).replace("URI", uri).replace("BODY", body);
  }
  else {
    sig = signatureTemplate.replace("METHOD", method).replace("URI", uri);
  }
 
	// Replace all headers specified in the signature template as header_<header_name> but only the names
  // you can later use this list to make sure which headers were signed
	const signedHeaders = signatureTemplate.match(/HEADER_([a-zA-Z0-9-_?~]+)/g);
 
  if (signatureTemplate.toLowerCase().includes("header")) {
    signedHeaders.forEach((headerTemplate) => {
      const headerKey = headerTemplate.replace('HEADER_', '');
      const headerValue = headers[headerKey];
      sig = sig.replace(headerTemplate, headerValue);
    });
  }
 
  // Sent HMAC signature from client
  const sentHmac = headers["x-descope-webhook-s256"];
 
  // Verify the HMAC signature
  if (!verifyHmacSignature(sig, SECRET, sentHmac)) {
      console.log("Invalid HMAC");
      return false;
  }
 
  console.log({ message: "HMAC verified successfully" });
  return true;
}
 
 
function verifyHmacSignature(payload, SECRET, sentHmac) {
	const computedHmac = crypto
		.createHmac("sha256", SECRET)
		.update(payload)
		.digest("base64");
	return sentHmac === computedHmac;
}

Dynamic Values in Headers

Descope allows you to utilize dynamic values as part of the HTTP Headers within the generic HTTP connector; this may be helpful if you want to pass user data or a custom field within the form as part of your HTTP header. The example below will pass the submitted email from the form and a custom test ID field to the connector as an HTTP header.

Within this example, the form.email will be populated by the form within the Descope screen, and the form.testID will be populated as a flow input. Below, you can see the configuration within the connector to send these dynamic values to the connector as part of the HTTP headers.dynamic

Below is an example of the headers populated with dynamic values received by the HTTP endpoint during the flow execution.

{
  '...': '...',
  'x-descope-testid': '12345678',
  'x-descope-form-email': 'chris+200@descope.com',
  '...': '...'
}