Merge pull request #406 from kinde-oss/feat/Guide-for-trustpath-integration

Create trustpath-fraud-protection.mdx

Author: clairekinde11

src/content/docs/integrate/third-party-tools/trustpath-fraud-protection.mdx

@@ -0,0 +1,232 @@
+---
+page_id: a845b386-a747-4e1c-9862-71ede016f1ec
+title: Integrate fraud detection with TrustPath
+sidebar:
+  order: 8
+relatedArticles:
+  - a07f8f6b-5d6a-4096-be52-7b13b4a3b0a5
+  - 7fe91aba-930c-4a63-8996-85af6bb605a7
+---
+
+This guide shows you how to build a Fraud Detection Workflow that runs after user authentication in **Kinde**, and uses **TrustPath** to detect and block potentially fraudulent sign-ins and sign-ups.
+
+The core idea: **whenever a user signs in or registers**, Kinde sends data to TrustPath. Based on the risk score it returns, Kinde allows or denies access.
+
+TrustPath works with Kinde workflows to trigger certain actions at key points in the authentication journey, using your own code.
+
+## What you need
+
+Here’s what you need to get started.
+
+- **Kinde account** - [Create one](https://app.kinde.com/register) for free if you haven’t already. You’ll also need to set up an application in Kinde.
+- **Kinde M2M application** - Create a [dedicated M2M app](https://docs.kinde.com/developer-tools/kinde-api/connect-to-kinde-api/) for accessing the Kinde Management API
+- **TrustPath account** - [Sign up](https://console.trustpath.io/login) here if you don’t have one. A free account does not require any payment information.
+- **TrustPath API access** - Grab an API key from the [TrustPath console](https://console.trustpath.io).
+- **Git repo for storing your code** - clone [this repository](https://github.com/trust-path/kinde-trustpath-integration-example). It contains integration code that is already prepared for use with this guide. 
+
+## Step 1: Set up the workflow and connect your repo
+
+For a workflow to function in Kinde, the workflow files need to be structured and set up in a specific way. Refer to the docs to get this part right.
+
+1. [Create a new workflow](/workflows/getting-started/workflow-files/) or [clone a template workflow](https://github.com/trust-path/kinde-trustpath-integration-example).
+2. [Connect your GitHub repo](/workflows/getting-started/connect-repo-for-workflows/) to execute the workflow.
+
+## Step 2: Define the workflow entry point
+
+The workflow starts with a simple async function triggered after user authentication:
+
+```js
+export default async function FraudDetectionWorkflow(event:
+onPostAuthenticationEvent) {
+}
+```
+
+The event parameter gives us initial context—such as the user ID, IP address, and whether this is a new user. But we need to enrich this data before we can send it to TrustPath. We’ll do this in the next step.
+
+## Step 3: Fetch full user data from Kinde
+
+To make an informed decision, TrustPath. needs more than a user ID—it also needs the user's email, first name, and last name. To get this data from Kinde, do the following.
+
+1. [Set up an M2M application](/developer-tools/kinde-api/connect-to-kinde-api/) to access the Kinde Management API and switch on the `read:users` scope.
+2. Copy the Client ID and Client secret from the above application.
+3. Create two new [environment variables](/workflows/configuration/environment-variables-and-secrets/) in Kinde. Go to **Settings > Data management > Env variables**.
+4. Add the following variables:
+    
+    
+    | Key | Value | Sensitive |
+    | --- | --- | --- |
+    | KINDE_WF_M2M_CLIENT_ID | Copy from M2M application | No |
+    | KINDE_WF_M2M_CLIENT_SECRET | Copy from M2M application | Yes |
+
+Once these are set up, you can retrieve the additional data you need, using the `createKindeAPI` helper from [@kinde/infrastructure](https://github.com/kinde-oss/infrastructure), which allows us to call the Kinde Management API:
+
+```js
+const kindeAPI = await createKindeAPI(event);
+const user = await getUserData(kindeAPI, event.context.user.id);
+async function getUserData(kindeAPI: any, userId: string) {
+const { data: user } =
+await kindeAPI.get({ endpoint: `user?id=${userId}` });
+return user;
+}
+```
+
+## Step 4: Set up your TrustPath API key
+
+**TrustPath** requires an API key to authenticate your requests, in this case a request that originates from the Kinde workflow. To get your API Key:
+
+1. Log in to the [TrustPath Console](https://console.trustpath.io).
+2. On the left-hand menu, go to **[Your Name] > API Keys**.
+3. Copy either one of the API keys provided there.
+
+(Recommended) Store the API key securely as an [environment variable](/workflows/configuration/environment-variables-and-secrets/) in **Kinde**, just like the other variables mentioned above.
+
+```js
+const trustPathAPIKey = getEnvironmentVariable("TRUSTPATH_API_KEY")?.value;
+```
+
+This ensures you’re not hardcoding sensitive credentials, and it keeps your app secure and maintainable.
+
+## Step 5: Determine the event type
+
+TrustPath evaluates risk differently based on the event type. For example, account creation versus account sign in.
+
+```js
+const isNewUser = event.context.auth.isNewUserRecordCreated;
+const eventType = isNewUser ? "account_register" : "account_login";
+```
+
+We check whether the user is new and set the event type accordingly:
+
+- `account_register`: Used for new sign-ups - typically includes more rigorous fraud checks.
+- `account_login`: Used for existing users - can focus on things like account takeover detection.
+
+By classifying the event properly, you can take advantage of TrustPath's specialized rule sets.
+
+## Step 6: Define TrustPath threat detection rules
+
+TrustPath threat detection rules are individual risk assessment criteria designed to identify fraudulent activities. Each rule analyzes specific signals to detect suspicious behavior and assigns a risk score to the event.
+
+Each risk detected then contributes to the total risk score, which ranges from 0 to 100.
+
+- A score of 0 means no risk (approve)
+- A score of 100 means very risky (decline)
+
+You need to set up separate rules for `account_register` and `account_login` events.
+
+Select **Threat Rules** from the menu and choose the card labeled **Account Register** to configure it. TrustPath offers the flexibility to add your own rules, but it also provides default rules tailored to each event type.
+
+![Threat rules in TrustPath dashboard](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/eada27f8-80b4-4c2b-0f3f-a379fda7b800/public)
+
+![TrustPath Rules library](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/2b574b60-336c-4a2b-7585-e1f575537800/public)
+
+Here’s an example of how to add a rule for the account register event.
+
+1. Select **Add Rule From Library** in the top right corner.
+2. From the list, select the following rules by clicking on each rule:
+    - Email addresses are disposable.
+    - IP Address is a Tor exit node.
+    - Email server IP addresses have abuse reports.
+
+This will enable any new account registration on Kinde to perform IP and email threat signal checks.
+
+Next, configure rules for the account log in event. For this, we want to prevent users from entering the system with disposable email addresses, as well as detect rapid IP changes, which can be a sign of unusual behavior.
+
+Here’s where you configure rules for the `account_login` event.
+
+![Event type rules in TrustPath](https://imagedelivery.net/skPPZTHzSlcslvHjesZQcQ/5902e60b-45b8-470d-8ec1-4fd46e6ec100/public)
+
+You can see we have some rules switched on, and each rule has a score.
+
+The example above detects rapid IP changes and blocks users by assigning a high risk score, which signals potential issues.
+
+### Advanced rule configuration
+
+The above rule can be strengthened by adding browser fingerprinting to IP change detection. For instance, the rule might be: “*if the same user email sees more than three different IP addresses within five minutes **and** also has a new browser fingerprint”*, it’s a stronger signal of suspicious activity.
+
+When set up, this detects a user logging in from multiple locations or while traveling—where the IP may change, but the browser fingerprint typically remains consistent if they’re using the same device.
+
+TrustPath supports many advanced configurations like this. You can contact their team to help you set up any complex rules you want.
+
+## Step 7: Build the request body
+
+Now that we have the user info and event type, we can build the payload to send to TrustPath when the workflow is triggered.
+
+```js
+const requestBody = {
+ip: event.request.ip.split(",")[0].trim(), // Handles cases where multiple IPs are forwarded
+email: user.preferred_email,
+user: {
+user_id: event.context.user.id,
+first_name: user.first_name,
+last_name: user.last_name,
+
+},
+event_type: eventType,
+};
+```
+
+This information passed in the request body allows TrustPath to cross-reference behavioral history, analyze IP risk, and more.
+
+## Step 8: Call the TrustPath Risk API
+
+Once the connection is set up between APIs, data is ready to be sent to TrustPath via a standard HTTP POST request. Here’s an example:
+
+```js
+const response = await kinde.fetch(
+  "https://api.trustpath.io/v1/risk/evaluate",
+  {
+    method: "POST",
+    responseFormat: "json",
+    headers: {
+      Authorization: `Bearer ${trustPathAPIKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(requestBody),
+  }
+);
+```
+
+This request is made using `kinde.fetch`, which handles outbound API calls securely within the workflow context.
+
+## Step 9: Evaluate the response and take action
+
+When the API call to TrustPath comes back, the response will include a state field showing one of three values:
+
+- **approve** - let the user through
+- **review** - optionally flags cases for manual review
+- **decline** - block access
+
+Here's how to enforce a block for declined requests:
+
+```js
+const state = response.json.data.score.state;
+
+if (state === "decline") {
+denyAccess(
+"You are not allowed to access this resource. Request declined by TrustPath.io"
+);
+}
+```
+
+You can adapt this to handle review flags differently, or to just mark it for review.
+
+## Step 10: Test your fraud detection setup
+
+Now that everything is set up, we can test the entire flow. Starting with the `account_register event`, select a disposable email address (choosing any from your favorite search engine should be sufficient) and try to create a new account on Kinde.
+
+Once everything is set up and deployed:
+
+1. Log in or register using your test account
+2. Check TrustPath's Event History to see the result
+3. By default, new accounts will return **approve** until you define threat rules in TrustPath.
+
+You can also test the `account_login` event by simulating logins from different IP addresses—using a VPN is a simple way to do this.
+
+## Support
+
+If you need extra support, here’s where to get it.
+
+- **TrustPath support:** For questions related to fraud detection rules, API integration, or threat analysis, visit **TrustPath**, [contact the TrustPath team](https://trustpath.io/contact), or view the TrustPath [API docs](https://docs.trustpath.io/).
+- **Kinde support:** For help with authentication workflows, triggers, or general setup, refer to the [Kinde docs](https://docs.kinde.com/) or reach out to [our support team](https://kinde.com/support/).
+
+TrustPath is a German-based company. Their team wrote this guide to help Kinde users.