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.

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 > 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 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.

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

  {
    "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.

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.

   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.

      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:

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

Example response:

{
  "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.

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.