> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation.

# Configure Connector-based risk engines

Use this page to configure a connector-based external risk engine integration in IDaaS.

## What is a connector-based risk engine?

A connector-based risk engine lets you integrate IDaaS with existing third-party risk services by configuring API requests and response mappings directly in IDaaS, rather than building and maintaining custom integration code.

For general background and use cases, see [Manage external risk engines](/docs/authentication-and-security/manage-external-risk-engines.md).

## Before you configure a connector

Before you configure a connector-based risk engine, identify how your provider API works. Depending on your provider, required telemetry might already be available in your application, or you might need to add new telemetry inputs. For most providers, you must define the following items first.

1. **Authentication model.** Determine how IDaaS authenticates to the provider API, for example API key, basic authentication, bearer token, or mutual TLS.
2. **Request contract.** Identify the endpoint, HTTP method, required headers, required query parameters, and request body fields.
3. **Response contract.** Identify which response fields represent risk outcomes and the data types of those fields.
4. **Result extraction and rule mapping.** Define the JSONPath expressions used in **Result Items**, and map those items to risk rules and thresholds.

After you define these provider-specific inputs, configure them in the IDaaS UI components described in the next section.

## Connector setup overview

Connector-based risk engine configuration requires four main components:

1. **Basic Settings.** Authentication method and general configuration
2. **Authentication Connector (optional).** If your risk engine requires token-based authentication, define how IDaaS obtains the auth token.
3. **Risk Connector (required).** Define how IDaaS retrieves the risk score from your risk engine.
4. **Risk Assessment Rules.** Map risk scores and outcomes to authentication decisions.

## Configure Connector-based external risk engine

This task involves completing the following:

- Configure basic settings
- Add an authentication connector
- Add risk connector
- Define risk assessment rules

### Configure basic settings

1. Click Menu icon **>** **Configuration > External Risk Engines**. The **External Risk Engines** page appears.

2. Click **Add** and then select **Connector-based Risk Engines** from the drop-down list. The **Add External Risk Engine** page appears.

3. Enter a **Name** for the external risk engine.

4. Select **Enabled** to enable the external risk engine.

note
You can also enable or disable the external risk engine after you add it from the **External Risk Engines** page.

5. From the **Authentication Method** drop-down list, select how IDaaS authenticates to the risk engine to make a risk request. Options include:

- **None.** No authentication credentials are sent to the risk engine.
- **Authentication Request.** IDaaS first calls a dedicated authentication endpoint to obtain a token, then uses that token when calling the risk endpoint. If you select this option, you must add an [Authentication Connector](#add-an-authentication-connector-if-required) to define the token request and response mapping.
- **Basic Authentication.** IDaaS sends a user name and password with risk requests.
- **Mutual TLS.** IDaaS presents a client certificate trusted by the risk engine server.
- **API Key.** IDaaS sends an API key value as configured for the connector request.

### Use placeholders in connector requests

Placeholders can be used when you configure the connector URL path, authorization header value, and request body. A placeholder is a named token used when values are not available at design time. IDaaS resolves placeholder values when the connector call runs.

For examples of common runtime parameters and how providers use them across different risk signal types, see [Common risk engine categories and input requirements](/docs/authentication-and-security/manage-external-risk-engines.md#common-risk-engine-categories-and-input-requirements).

Placeholders are supported for the following:

- URL path (not in hostname/domain section)
- Authorization header (not name)
- Request Body

#### Placeholder examples

The following examples show common placeholder usage patterns:

- URL query parameter

  `https://risk.example.com/v1/score?ip={{ENV.clientIp}}&session={{REQ.sessionId}}`

- Authorization header value

  `Bearer {{AUTH}}`

- Request body

  ```json
  {
    "userId": "{{USER.userId}}",
    "accountId": "{{REQ.accountId}}",
    "transactionAmount": "{{REQ.amount}}",
    "clientIp": "{{ENV.clientIp}}"
  }
  ```

#### Placeholder restrictions

The following describes placeholder restrictions:

- Placeholders are marked by `{{}}`
- Each placeholder must start with one of the following prefixes:
  - **REQ.**: The placeholder's value comes from the Request body. The rest of placeholder after prefix REQ. must match one of the names in the transactionDetails of the request.
  - **USER.**: The value from a user's attributes.
  - **ENV.**: The environment data. Only clientIp is supported.
  - **AUTH**: The authentication information gathered from the Authentication Method used in the risk engine configuration.
- Placeholders prefixed by REQ., USER., or ENV. include dynamic data that interacts with the user's inputs. The name after the prefix must match. In contrast, AUTH is a special type of placeholder.
- Domain and subdomain in the URL are static: no placeholders are allowed.
- Placeholders cannot use delimiter symbols. The placeholders and resultItems used in the same HTTP Connector must be unique.
- A placeholder, once configured, must have its values, in one of the following:
  - **AUTH**: HTTP Connector configuration
  - **REQ.** and **ENV.**: Request payload in the transactionDetails and usage must be RBA.
  - The UI input.
  - **USER.**: User attribute configuration
- All the values are mandatory. If any placeholder cannot find its matching values, the connector call will fail.

### Add an Authentication Connector (if required)

If you selected **Authentication Request** in step 5, complete the following steps to configure how IDaaS obtains an authentication token. If you selected a different authentication method, skip to [Add a Risk Connector](#add-a-risk-connector).

6. Add an **Authentication Connector.**

note
What you include in this section depends on the risk engine and the type of information it requires to process the risk request and return an authentication token. The following steps describe the purpose of each setting, but depending on the risk engine, they may not all apply. Items with an asterisk (*) are required values.

1.   Click **Add** next to **Authentication Connector**. The **Add HTTP Connector** page appears.

2.   Enter a **Name** for the request.

3.   From the **Method** drop-down list, select the HTTP request method used to make the request to the risk engine. Options include:

     - **GET.** Retrieves data without changing server-side state.
     - **POST.** Submits data to create or process a resource.
     - **PUT.** Replaces an existing resource with the request payload.
     - **DELETE.** Removes the specified resource.
     - **PATCH.** Applies partial updates to an existing resource.

4.   In the **URL** field, enter the URL of the login endpoint of the risk engine to obtain the token. If applicable, add required parameters to the URL that are used to make the request to the risk engine.

    note

          The Domain part of the URL must be an external host name or an IP address. Internal hostnames are not allowed.

5. From the **Authorization Type**, drop-down list, select the authentication method passed to the risk engine to obtain the authentication token. Depending on the selection you make, you are prompted for additional information, as follows:

      - **Basic.** Enter the User Name and Password for the risk engine.
      - **API_Key.** Select the API Key Type and enter the API Key Value.
      - **BEARER_TOKEN.** Enter the token value used by the risk engine.

6. If required, click **Add** to add authorization **Headers** to the HTTP request, and then enter the **Header Name** and **Header Value**. You can add as many headers as required to make the request.

7.   If required, In the **Results Items** section, set the values used to return the risk assessment, as follows:

     1. Enter the **Key** that is used to assess the risk.
     2. Select the **Value Type**, which can be either a **String** or a **Numeric** value, and enter the JSONPath for the results item.
     3. Click **Add** to define additional Keys used to return the results of the risk assessment.

    note

          For more information on Query expressions for JSON, see [**RFC 9535**, *JSONPath: Query Expressions for JSON*](https://tools.ietf.org/html/rfc9535).

8. Optional. In the **Request Body**, add additional content, as required.

9.  Click **Add** to save the HTTP Connector and return to the **Add External Risk Engine**.

### Add a Risk Connector

The Risk Connector retrieves the risk score from your external risk engine. This step is required.

7. Add a **Risk Connector**. The Risk Score Connector returns the risk score from the external risk engine.
   1. Next to **Risk Score Connector**, click **Add**. The **Add HTTP Connector** page appears.

   2. Enter a **Name** for the request.

   3. From the **Method** drop-down list, select the HTTP request method used to make the request to the risk engine.

   4. In the **URL** field, enter the URL of the risk data endpoint of the risk engine to obtain the risk data. If applicable, add required parameters to the URL that are used to make the request to the risk engine.

   note
   The Domain part of the URL must be an external host name or an IP address. Internal hostnames are not allowed.

   5. From the **Authorization Type**, drop-down list, select the authentication method passed to the risk engine to obtain the authentication token. Depending on the selection you make, you are prompted for additional information, as follows:

      - **Basic.** Enter the User Name and Password for the risk engine.
      - **API_Key.** Select the API Key Type and enter the API Key Value.
      - **BEARER_TOKEN.** Enter the token value used by the risk engine.

   6. If required, click **Add** to add authorization **Headers** to the HTTP request, and then enter the **Header Name** and **Header Value**. You can add as many headers as required to make the request.

   7. If required, In the **Results Items** section, set the values used to return the risk assessment, as follows:

      1. Enter a name for the result item in the **Key** field that will be used as the risk item to compose the rules.
      2. Select the **Value Type**, which can be either a **String** or a **Numeric** value, and enter the JSONPath for the results item.
      3. Click **Add** to define additional Keys used to return the results of the risk assessment.

   note
   For more information on Query expressions for JSON, see [**RFC 9535**, _JSONPath: Query Expressions for JSON_](https://tools.ietf.org/html/rfc9535).

   note
   A result item used by a risk engine rule cannot be deleted.

   8. Optional. In the **Request Body**, add additional content, as required.

   9. Click **Add** to save the HTTP Connector and return to the **Add External Risk Engine**.

### Define risk assessment rules

8. Add **Rules** used to assess the risk score. You must add at least one rule. Follow these steps:
   1. Click **Add**. The **Add Rule** dialog box appears.
   2. Enter a **Name** for the rule that defines the risk factor.
   3. From the **Risk Item** drop-down list, select a risk item. Available risk items are based on the Result Items defined in the risk connector you created in the previous step.
   4. Select the required **Operator** from the drop-down list.
   5. Add a value in the **Value** text box.
   6. Optional: Add multiple conditions by creating a group.
      1. Click **Add Group**.
      2. Enter a **Name** for the group.
      3. Select the AND or OR operator for each added group expression.
      4. Select the **Risk Item** from the drop-down list.
      5. Select the required **Operator** from the drop-down list.
      6. Add a value in the Value text box.
      7. Click **Add Rule**.
      8. Repeat these steps to add more rules to the group.
      9. Click **Save**.
   7. Click **Save**.
   8. Repeat these steps to add more rules to the group.

### Save and verify

9. Click **Save** to save the external risk engine and return to the **External Risk Engines** page.

## Example (illustrative): configure an IP-based connector risk engine

This made-up example shows a connector-based risk engine that evaluates the current request IP address and returns a `riskLevel` from 0 (low risk) to 100 (high risk).

### Example risk API behavior

In this example, the external API behaves as follows:

- It accepts an HTTP `GET` request.
- It expects the client IP in a query parameter.
- It expects an API key in the `Authorization` header.
- It returns JSON that includes `riskLevel`.

Example request:

```http
GET https://risk.example.com/v1/score?ip=203.0.113.10
Authorization: ApiKey 1234567890abcdef
Accept: application/json
```

Example response:

```json
{
  "riskLevel": 82,
  "country": "US",
  "asn": "AS15169",
  "ipType": "hosting"
}
```

### Configure this example in IDaaS

Use this example configuration to map the external response to an IDaaS rule.

For the corresponding resource rule configuration that uses this external rule, see [Add Risk Factors](/docs/authentication-and-security/create-and-manage-resource-rules/create-resource-rules/add-a-resource-rule/add-risk-factors.md#example-apply-risk-when-risklevel-is-above-70).

1. In **Basic Settings**, set **Authentication Method** to **API Key** and enter the risk engine API key value.
2. In **Risk Score Connector**, configure these values:
   1. Set **Method** to **GET**.
   2. Set **URL** to include the client IP placeholder, for example `https://risk.example.com/v1/score?ip={{ENV.clientIp}}`.
   3. Add a header:
      - **Header Name**: `Authorization`
      - **Header Value**: `ApiKey {{AUTH}}`
3. In **Results Items**, add:
   - **Key**: `riskLevel`
   - **Value Type**: **Numeric**
   - **JSONPath**: `$.riskLevel`
4. In **Rules**, add a rule for high risk traffic:
   - **Name**: `high-ip-risk`
   - **Risk Item**: `riskLevel`
   - **Operator**: `GREATER_THAN`
   - **Value**: `70`

After you save this rule, you can reference it in the resource rule **External** risk factor so transactions with `riskLevel` above `70` apply risk.