Migrate from Identify to Evaluations

Background

Rupt's device intelligence technology has been split into two separate sub-technologies:

• Device Identification
• Fingerprinting

Device Identification is a proprietary technology primarily used for account sharing detection and prevention. Fingerprinting on the other hand is more suited for account takeover detection and prevention.

Previous versions of Rupt's device identification technology supported account takeover detection and prevention with similar accuracy to fingerprinting. However, to squeeze more benefit for account takeover scenarios, it's better to utilize our fingerprinting technology.

To simplify the code integration, we've unified all of the assessments into a single evaluate function from the front end package and included fully documented APIs to handle the server side logic.

This guide explains how to migrate from the previous Identify APIs to the new and improved evaluate APIs.

Account takeover protection flow

Migration steps:

Rupt dashboard settings

1. From your dashboard settings, navigate to the Account takeover section and enable Account takeover protection.
2. Turn off Managed challenge page so that you can handle the challenges page yourself.

Front end

1. Update the Rupt package to the latest version.
   yarnnpm

   yarn upgrade rupt@latest
   

   
   Alternatively, to always use the latest minor version of Rupt, you can import the package from a CDN:

   <script src="https://cdn.rupt.dev/js/rupt.js"></script>
   

   When using HTML script tags, be sure to wait for the script to be loaded. Rupt will be injected into the window so you can use window.Rupt instead of Rupt.

   
   
2. Replace the .identify calls with Rupt.getHash to get a client-side browser fingerprint hash.

   const fingerprintHash = await Rupt.getHash();
   

   
   This returns a fingerprint hash array which can be used to identify the browser. Send this hash to the server side in your authentication flow.

Server side

yarn add @ruptjs/core
#OR
npm install @ruptjs/core

import Rupt from "@ruptjs/core";
const rupt = new Rupt("API_SECRET");

3.1. In your authentication flow, call the evaluate method using the login action and the fingerprint hash and other user information:

const res = await rupt.evaluate({
  action: "login",
  user: "USER_ID",
  fingerprint: FINGERPRINT_HASH, // The hash returned from the browser
  ip: "IP_ADDRESS", // Optional
  email: "EMAIL", // Optional
  phone: "PHONE", // Optional
  metadata: {
    key: "value",
  },
});

curl -X POST https://api.rupt.com/v2/devices/evaluate \
  -H "Authorization: Bearer API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"action": "login", "user": "USER_ID", "fingerprint": "FINGERPRINT_HASH", "ip": "IP_ADDRESS", "email": "EMAIL", "phone": "PHONE", "metadata": {"key": "value"}}'

4.2. Rupt returns a response that looks like this:

{
  "verdict": "challenge",
  "fingerprint_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "reasons": ["new_device", "new_ip"],
  "challenge_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

The verdict will be either challenge, allow, restrict, challenge_and_restrict, or deny.

The challenge_id can be used to perform a two-factor authentication challenge using the send challenge code method. For more information, see send a challenge code.

5.3. If the verdict is challenge, a challenge_id is returned. Using the challenge_id, send the challenge code to the user and wait for the response:

const { challenge_id } = await rupt.sendChallengeCode(challenge_id);

curl -X POST https://api.rupt.com/v2/challenges/CHALLENGE_ID/send \
  -H "Authorization: Bearer API_SECRET" \
  -H "Content-Type: application/json"

This will send a challenge code to the user. For more information, see send a challenge code.

6.4. With the user provided challenge code, verify the response:

const { success } = await rupt.verifyChallengeCode(challenge_id, code);

curl -X POST https://api.rupt.com/v2/challenges/CHALLENGE_ID/verify \
  -H "Authorization: Bearer API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

For more information, see verify a challenge code.

7.5. Once you've allowed the user to login, let Rupt know that the user has successfully completed the challenge using the completeChallenge method or API endpoint. Rupt will know to trust the device and IP and will not trigger a challenge if the user attempts to login from the same device and IP in the future:

const { success } = await rupt.completeChallenge(challenge_id);

curl -X POST https://api.rupt.com/v2/challenges/CHALLENGE_ID/complete \
  -H "Authorization: Bearer API_SECRET" \
  -H "Content-Type: application/json"

For more information, see complete a challenge.