> For AI agents: [llms.txt](https://docs.trustedauth.com/llms.txt) provides a Markdown index of this documentation. # Generic API Risk Engine An external risk engine provider is a source of risk alerts or risk events. The IDaaS Generic API risk engine supports integration with external risk engines. IDaaS evaluates risk contexts from an external risk engine to build risk engine rules. With an external risk engine API integration, your organization implements a service that can be reached by REST. The integration works as shown in the following message sequence chart: 100% ## Step 1: Build and deploy a REST service that implements the two "Generic API" External Risk Engine endpoints Your REST service must implement the two endpoints as shown in the following table: | Endpoint | Request Method | URL | JSON Request Attributes | JSON Response Attributes | Notes | | -------------- | -------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authentication | POST | `/v1/authenticate` | `companyId` (String) `riskProvider` (String) `identifier` (String) `password` (String) | `token` (String) | The request attributes are defined when the Generic API external risk engine is created. The `password` attribute is optional. The response **token** value is sent in the `Authorization` header to the Get Risk Score endpoint. This endpoint is called initially and after the token expires. Token Expiration is configured in the Risk Engine. | | Get Risk Score | POST | `/v1/riskscore` | `companyId` (String) `riskProvider` (String) All RBA `transactionDetails` attributes `IDaaS_AccountId` (String) `IDaaS_UserId` `IDaaS_UserUuid` `IDaaS_ClientIpAddress` `IDaaS_UserAliases` (Optional) | `riskScore` (number) `companyId` (String) - Optional `userId` (String) - Optional | `riskScore` is mapped to an IDaaS Rule using the risk Risk Item. `companyId` is not used currently. `userId`: If the risk engine is configured to match this value with the IDaaS `userId` value and they do not match, the risk evaluation fails and contributes all defined risk points. `IDaaS_UserAliases` is only included if the risk engine is configured to check User ID mismatch. | IDaaS will invoke the authentication endpoint with the provided credentials when the risk engine is defined in IDaaS to verify that the service is reachable and that the credentials are valid. If you get an `Invalid username or password` error, then either the service cannot be contacted or the credentials are invalid. At runtime, when the IDaaS Authentication API is invoked, IDaaS first calls the REST service `Authentication` endpoint and cache the returned token for as many minutes as set in the **Token Expiration** attribute when the risk engine is defined in IDaaS. It then sends the token, as an Authorization header, when calling the REST `Get Risk Score` endpoint. note Notes: - The rest service host must be accessible from the Internet (hostname resolvable by DNS lookups). - The rest service must run on HTTPS with a certificate issued by a trusted CA. IDaaS trusts all CAs defined in the Java JDK truststore. ### Step 2: Create a Generic API External Risk Engine Before you begin, ensure that you know the credentials for your external risk provider. 1. Click Menu icon **>** **Configuration > External Risk Engines**. The **External Risk Engines** page appears. 2. Click **Add** and then select the **Generic API** External Risk Engine Provider from the drop-down list. The **Add External Risk Engine** page appears. 3. The **Name** field is predefined. 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. Enter the external risk engine credentials, for example the **Username/Identifier** and **Password**. This value can be an API-key or username. 6. Under **Attributes**, do the following: 1. Enter the **URL**. 2. Enter the **External Risk Provider**. 3. Enter the **Company ID** provided to you by the external risk engine. 4. Enter the **Token Expiration** for the token used by the external search engine. 5. Select **Fail evaluation when identities do not match** if the user session and the user do not match. 7. Optional. Add **Rules** as follows: 1. Click **Add**. The **Add Rule** dialog box appears. 2. Enter a **Name** for the rule that defines the risk factor. 3. Select the **Risk Item** from the drop-down list. There are two options: - **Risk**: The risk score returned by the external risk provider. - **serviceStatus**: This item is available for all external risk engines integrated with IDaaS. It can be used to decide what the system should do when the external risk engine is not available. To use this item, create a rule with `serviceStatus EQUALS FAILURE`. This rule can then be used in a resource rule in combination with other rules. If the evaluation of the external risk engine is critical to grant access to an application, you can give enough risk points to this rule so that risk score is reached and the evaluation moves into the High Risk scenario. 4. See your external risk engine documentation for a description of other risk items. 5. Select the required **Operator** from the drop-down list. 6. Add a value in the **Value** text box. 7. Optional. To add more rules to the rule, do the following: 1. Click **Add Group**. 2. Select the **AND** or **OR** operator for each added group expression. 3. Select the **Risk Item** from the drop-down list. 4. Select the required **Operator** from the drop-down list. 5. Add a value in the **Value** text box. 8. Click **Add**. 9. Repeat these steps to add more external risk engine rules. 8. Click **Save** to save the external risk engine and return to the **External Risk Engines** page. ### Step 3: Create an Authentication API 1. Click Menu icon **>** **Security > Applications**. The **Applications** page appears. 2. Click **Add**. The **Select an Application Template** page appears. 3. Do one of the following: - Select **Identity as a Service Integrations** from the search drop-down list and scroll to find the application you want to add to IDaaS. - In the **Search bar**, enter a search option to filter for the application you want to add to IDaaS. 4. Click **Authentication API**. The **Add Authentication API** page appears. 5. In the **Application Name** field, type a name for your application. 6. In the **Application Description** **field, type a** description for your application. 7. Optional. Add a custom application logo as follows: 1. Click Circle Plus icon next to **Application Logo**. The **Upload Logo** dialog box appears. 2. Click Arrow Up From Line icon to select an image file to upload. 3. Browse to select your file and click **Open**. The **Upload Logo** dialog box displays your selected image. 4. If required, resize your image. 5. Click **OK**. 8. Select **Enable passkey login** to allow users to complete passkey authentication in the Auth API. 9. Click **Next**. The **General** **Settings** page appears. 10. Select the **Source of the Client IP Address for Risk Conditions**. The options are: - **Not provided**: The IP address is not provided and is not extracted from the connection. - **Provided in the API**: The IP address is provided in the request body of the API. - **From the incoming HTTP connection**: The IP address is extracted from the connection. 11. Select **Do not use IP Address for Resource Rule Risk Factors** if you only want to use the IP address for Audits but not for the resource rule risk conditions. 12. Select **Enabled** for **User Verification Check** to allow user verification through the Auth API for Identity Provider authentication. 13. Select **Application can store values for the user** to allow the Auth API to call self-admin (internal) APIs that are used to **Manage Client Values**. 14. Click **Submit**. The **Application ID is** generated. 15. Copy and paste the **Application ID** into the IDaaS API calls being used by your application. 16. Click **Done**. ### Step 4: Add a resource rule See [Create resource rules](/docs/authentication-and-security/create-and-manage-resource-rules.md). ### Step 5: Use the Authentication API (Query User Authenticators) to send the request In this integration you use the Authentication API to send attributes required by the external risk provider as part of the Transaction Details using the risk-based authentication (RBA) usage type: ```json "transactionDetails": { {"detail": "session_id", "usage": ["RBA"], "value": "JFKG8906f09aee34449389cf7#=="}, {"detail": "risk_vector", "usage": ["RBA"], "value": "5f09aee34JFKGB906f09aee3449389cf7#17d397d5ccd417d385d5ccd4"} } ``` ### Sample REST requests Authentication endpoint Requests: ```json POST https://hostname:port/riskgateway/v1/authenticate Content-Type: application/json { "companyId": "myCompany", "riskProvider": "MyRiskProvider", "identifier": "myIdentifier", "password": "myPassword" } ``` Response: ```json { "token": "jvasdf14lkjvcg60-98vcasnmdfldcjkv" } ``` Get Risk Score endpoint Request: ```json POST https://hostname:port/riskgateway/v1/riskscore Content-Type: application/json Authorization: Bearer jvasdf14lkjvcg60-98vcasnmdfldcjkv { "companyId": "myCompany", "riskProvider": "MyRiskProvider", "session_id": "JFKG8906f09aee34449389cf7#==", "risk_vector": "5f09aee34JFKGB906f09aee3449389cf7#17d397d5ccd417d385d5ccd4", "IDaaS_AccountId": "account123", "IDaaS_UserId": "user123", "IDaaS_UserUuid": "550e8400-e29b-41d4-a716-446655440000", "IDaaS_ClientIpAddress": "1.2.3.4", "IDaaS_UserAliases": "user_alias1,user_alias2" } ``` Response: ```json { "riskScore": 75, "userId": "user123" } ```