Configure Connector-based risk engines

Connector-based risk engines support configuration of the IDaaS API to support third-party risk engines without the need to do development. Before you begin, review the information about placeholders. Placeholders are optional and can be used in the HTTP Connector to further define the data requested from the external risk engine.

Placeholders

Connector-based risk engine configuration supports the use of placeholders. A placeholder is a symbol to mark a place and name when configuring connectors for the dynamic data and you do not have the values when composing the API call. The values are populated in when the call is made to the connector.

Placeholders are supported for the following:

URL path (not in hostname/domain section)

Authorization header (not name)

Request Body

Placeholder restrictions

The following describes placeholder restrictions:

Placeholders are marked by {{}}

Placeholder must start with any of these 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.

Configure Connector-based external risk engine

Click > Configuration > External Risk Engines. The External Risk Engines page appears.

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

Enter a Name field for the external risk engine.

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.

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

Authentication Request. The risk engine returns an authentication token. IDaaS uses the authentication token to make the authentication risk calls. If you select this option, you must add an Add Authentication Connector to configure how IDaaS makes the request to the risk engine to obtain the authentication token.

Add an Authentication Connector.Add an Authentication Connector.

Note: What you include in this section depends on the risk engine being used and they type of information it requires to make the risk request and return the 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.

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

Enter a Name for the request.

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

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.

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.

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.

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

Enter the Key that is used to assess the risk.
Select the Value Type, which can be either a String or a Numeric value, and enter the JsonPath for the results item.
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.

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

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

Basic Authentication. You are prompted to enter the username and password defined by the risk engine and include it in the risk request.

Mutual TLS. You are prompted to upload the certificate file that is shared with the risk engine server.

API key. You are prompted to enter the API key defined by the risk engine.

Add a Risk Connector. The Risk Score Connector returns the risk score from the external risk engine.Add a Risk Connector. The Risk Score Connector returns the risk score from the external risk engine.

Next to Risk Score Connector, click Add. The Add HTTP Connector page appears.

Enter a Name for the request.

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

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.

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.

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.

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

Enter a name for the result item in the Key field that will be used as the risk item to compose the rules.
Select the Value Type, which can be either a String or a Numeric value, and enter the JsonPath for the results item.
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 resultItem used by a risk engine rule cannot be deleted.

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

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

Add Rules used to assess the risk score. You must add at least one rule. Follow these steps:

Click Add. The Add Rule dialog box appears.

Enter a Name for the rule that defines the risk factor.

From the Risk Item drop-down list, select The risk items available are based on the Result Items for the risk connector you created in step 7.

Select the required Operator from the drop-down list.

Add a value in the Value text box.

Optional. Add multiple rules to the rule by creating a Group.Optional. Add multiple rules to the rule by creating a Group.

Click Add Group.
Enter a Name for the group.
Select the AND or OR operator for each added group expression.
Select the Risk Item from the drop-down list.
Select the required Operator from the drop-down list.
Add a value in the Value text box.
Click Add Rule.
Repeat these steps to add more rules to the group.
Click Save.

Click Save.

Repeat these steps to add more rules to the group.

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