Connectors in Flows

Descope enables you to enrich your Descope flows by allowing you to integrate with 3rd party vendors to fetch information or push data to the vendor during the execution of the flow utilizing connectors. Within the Descope console, connectors are configured here; within this page, you can find a generic connector template for connecting to any third-party API, as well as other out-of-the-box connectors Descope provides for various vendors.

For example, you can utilize connectors to connect to another service, gather further information on the user, store it within Descope as a custom attribute, or utilize it within the user's JWT.

For further information about connectors including examples of how to configure Descope connectors, please review Connectors which covers how to configure connectors and their use cases.

Configuring a Connector

When creating your connector, you will provide a custom name and description for it. Further details on other connector-specific configuration settings are within Descope console on the right-hand side.

Testing Connectors

If the connector supports the testing functionality, Descope will display the test functionality within the connector configuration page. Testing your connector from the Descope console allows you to test your connector to ensure functionality. Depending on the connector type, you may need to fill in the URL for the test within the console.

Below is an example of the test functionality using a generic HTTP connector with a base URL is https://random-data-api.com/api/v2, and Descope is gathering data from https://random-data-api.com/api/v2/users, only /users is provided within the test function.

The test results will be returned on the right side under Test Results. This panel will show you the response from the get request or any errors that occur during the processing of the request.

Here is an example from testing the connector for both a successful request and a failed request.

Implementing Connectors within Descope Flows

Here is a simple example of utilizing connectors within Descope flows. This example captures data from a random data generating API: https://random-data-api.com/api/v2/users using the generic HTTP connector. You can see this example's configuration of the connector in the testing section above. This example will cover adding the generic HTTP connector to your flow and adding data from it's response to the user's custom claims.

For more detailed documentation and advanced configurations for the generic HTTP connector review our Knowledge Base article here.

Add the Connector to the Flow

From the + sign at the top left of the flow editor, select the Connector:

Then select the connector type that you would like to utilize, this example uses the GET request:

Connector Settings

Configure the Connector

This is an example of how you could configure the connector to receive information from https://random-data-api.com/api/v2/users. The returned data will be available for use within later actions under the context key connectors.random.

Attach the Connector within the Flow

Once you have configured the Connector, attach it within your flow. Within this example, the action is connected after successful authentication of the user.

Here is an example of the Connector's response.

{
  "id": 646,
  "uid": "ef405e9f-d9d1-4c21-a783-7b7ec49f8adc",
  "password": "xzS4cEraHy",
  "first_name": "Dewitt",
  "last_name": "Parker",
  "username": "dewitt.parker",
  "email": "dewitt.parker@email.com",
  "avatar": "https://robohash.org/debitisvoluptatumalias.png?size=300x300&set=set1",
  "gender": "Male",
  "phone_number": "+964 (193) 613-1338 x548",
  "social_insurance_number": "118214725",
  "date_of_birth": "1979-10-03",
  "employment": {
    "title": "Dynamic Manufacturing Consultant",
    "key_skill": "Problem solving"
  }
  // continued, but this is really all you need
}

Add Data from the Connector to the User's Custom claims

From the + sign at the top left of the flow editor, select action, then search and select custom claims.

Configure Custom Claims Action

The step name can be configured to meet your needs. This example will focus on setting the Key, Type, and Value based on the date_of_birth returned by the Connector response.

The key is name of the key that will be added within the JWT, for example it is set to dob. The type will be dynamic to map the value from the connectors context key to this custom claims key. The value is based on the configuration of the connector and the format of the response. For this example, the Value is connectors.random.date_of_birth. Below is a screenshot of the configured Custom Claims Action:

Attach the Custom Claims Action within the Flow

Once you have configured the custom claims action, attach it within your flow. Within this example, the action is connected just before the end of the flow. Then save the flow.

Test the Flow

Once this has been configured and saved, you can now test and verify the added key is added to the custom claims. You can navigate to the getting started page and test your flow. Below is an example of how the custom claim is added with the dob key which was populated with the Connector during the custom claims action.

Troubleshooting Connectors in Flow Runner

Descope allows you to debug connectors within the Flow Runner. When running a flow within the flow runner, Descope logs the request sent to the connector and the response received from the connector within the runner messages. To run a flow with connectors for debugging, navigate to Flows and choose your flow, then click the blue Run button at the top right. Below is an example of the data written to the runner messages.