Descope Connectors

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 the Knowledge Base for Connectors which covers how to configure connectors.

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 3rd Party Action 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 3rd Party Action to the Flow

From the + sign at the top left of the flow editor, select the 3rd Party Action.

Adding Descope third party action within flows.

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

Adding Descope third party configuration within flows.

3rd Party Action Settings

Setting	Details
Step Name	Editable name for your flow action.
Connector	Drop down selection of the configured connectors within your project.
Base URL	This is auto populated from the connector's configuration and is not editable.
Endpoint	This is rest of the URL of the endpoint for the connector to reach. This can include query parameters, etc.
Timeout	This is the configurable timeout used for the HTTP Request. The units are seconds.
Context Key	The response will be mapped into this key. You can use a Condition Step to later refer to this key and query its data.

Configure the 3rd Party Action

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.

Example Descope connector configuration.

Attach the 3rd Party Action within the Flow

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

Descope third party action shown within flows.

Here is an example of the 3rd Party Action'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.

Adding Descope custom claims action within flows.

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 3rd Party Action's 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 3rd Party Action 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.

Adding Descope custom claims configuration within flows.

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.

Descope custom claims action shown within flows.

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 3rd Party Action's during the custom claims action.

Was this article helpful?Yes No