Sunday, 23 Jun 2024
Technology

2FA SIM Swap Detection with Vonage/Nexmo Verify

nexmo 2 factor

The Vonage Verify API offers a reliable SMS with Voice fallback PIN code 2FA solution. It ensures that users are in possession of a phone with a specific phone number. However, with the increasing incidents of SIM Swap attacks, it is crucial to detect if the SIM card associated with the phone number has recently changed. To address this issue, the tru.ID SIMCheck API comes into play.

The tru.ID SIMCheck API provides valuable information about when the SIM card associated with a mobile phone number was last changed. This additional layer of security enhances your application’s login flows by identifying attempted SIM swap fraud. SIMCheck can be seamlessly integrated into existing 2FA or anti-fraud workflows.

In this tutorial, we will explore how to use the SIMCheck API to augment the Vonage Verify 2FA workflow.

Before you begin

Before diving into the project, make sure you have the following requirements:

  • Node.js
  • A tru.ID Account
  • A Vonage Account

Getting Started

To begin, clone the starter-files branch by executing the command:

git clone -b starter-files [repository_url]

Make sure you have the necessary access rights to the repository.

Getting set up with Vonage

First, you need to configure Vonage using your account credentials.

  1. Copy the values of .env.example into a .env file:
cp .env.example .env
  1. Open the .env file and configure the following values:
  • VONAGE_API_KEY: Your Vonage API key found on the developer dashboard
  • VONAGE_API_SECRET: Your Vonage API key found on the developer dashboard
  • VONAGE_BRAND_NAME: A name for your application, which will appear on the home page and in the “from” field of any SMS sent via the Verify API (up to 11 alphanumeric characters)
Tham Khảo Thêm:  How to Turn Off a Chromebook Without The Power Button

Getting set up with tru.ID

To make SIMCheck API requests, you’ll need a tru.ID Account and some Project credentials.

  1. Sign up for a tru.ID account, which comes with free credit.
  2. Install the tru.ID CLI by running the following command:
npm install -g @tru_id/cli
  1. Run tru login <YOUR_IDENTITY_PROVIDER> (replace <YOUR_IDENTITY_PROVIDER> with either ‘google’, ‘github’, or ‘microsoft’) using the Identity Provider you used when signing up. This command will open a new browser window and prompt you to confirm your login. A successful login will display a message similar to the following:
You are now logged in! Welcome, <Your Name>.
  1. Create a new tru.ID project within the root directory using the following command:
tru projects:create --name "My Project"
  1. Configure the following values in your .env file:
  • TRU_ID_CLIENT: The client ID found in the tru.<project_name>.json file in the newly created tru.ID project.
  • TRU_ID_SECRET: The client secret found in the tru.<project_name>.json file in the newly created tru.ID project.

Finally, install the project dependencies by running:

npm install

Starting the project

To start the project, run the following command in the terminal:

npm start

The project should now be up and running.

Existing app workflow

The current workflow from the base app is as follows:

  1. The app opens in /. If the user is verified, their phone number and other information are displayed along with a cancel button to “log out”. If the user is not verified, they can verify by clicking the “Verify Me” button.
  2. The user inputs their phone number and is taken to the /entercode route, where they can input the OTP (One-Time Password) generated.
  3. The user inputs the OTP code, and if it’s valid, they are redirected to /.

Workflow with the SIMCheck API

The enhanced workflow with the SIMCheck API is as follows:

  1. The app opens in /. If the user is verified, their phone number and other information are displayed along with a cancel button to “log out”. If the user is not verified, they can verify by clicking the “Verify Me” button.
  2. The user inputs their phone number, and a SIMCheck is performed before OTP generation.
  3. If the SIMCheck is successful, the user is taken to the /entercode route, where they can input the OTP generated. If the SIMCheck fails, the user is redirected to a /sim-change-detected route.
  4. The user inputs the OTP code, and if it’s valid, they are redirected to /.

Performing the SIMCheck

To perform the SIMCheck, we need to do two things:

  1. Create a tru.ID access token.
  2. Create a SIMCheck using the generated access token.
Tham Khảo Thêm:  8 Different Ways to Encourage Social Media Engagement

In order to achieve this, we need to import a few packages. Open a new terminal and run:

npm install btoa node-fetch

Creating the tru.ID Access Token

To create the access token, create a new directory called helpers, then create a createAccessToken.js file inside that directory and paste the following code:

// helpers/createAccessToken.js

const fetch = require('node-fetch');
const btoa = require('btoa');
require('dotenv').config();

async function createAccessToken() {
  const response = await fetch(`https://${process.env.TRU_ID_DATA_RESIDENCY}.api.tru.id/oauth2/v1/token`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      'Authorization': `Basic ${btoa(`${process.env.TRU_ID_CLIENT}:${process.env.TRU_ID_SECRET}`)}`
    },
    body: new URLSearchParams({
      'grant_type': 'client_credentials',
      'scope': 'sim_check'
    })
  });

  const data = await response.json();
  return data.access_token;
}

module.exports = createAccessToken;

Creating the SIMCheck

In the helpers directory, create a file named performSimCheck.js and paste the following code:

// helpers/performSimCheck.js

const fetch = require('node-fetch');
require('dotenv').config();

async function performSimCheck(phoneNumber, accessToken) {
  const response = await fetch(`https://${process.env.TRU_ID_DATA_RESIDENCY}.api.tru.id/sim_check/v0.1/checks`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    },
    body: JSON.stringify({
      'phoneNumber': phoneNumber
    })
  });

  const data = await response.json();
  return data;
}

module.exports = performSimCheck;

Handling Failure

We need to handle the following failure scenarios:

  • The SIM changed recently (indicated by simChanged being true).
  • tru.ID cannot perform a lookup on the phone number, resulting in numberSupported being false.

To handle these scenarios, create a file named error.pug in the views directory and paste the following code:

//- views/error.pug

extends layout

block content
  h1 Error
  p= error

Integrating our helper functions

Next, we need to integrate our helper functions.

Add the following imports to the top of server.js:

// server.js

const createAccessToken = require('./helpers/createAccessToken');
const performSimCheck = require('./helpers/performSimCheck');

Update the app.post('/verify', (req, res) => {} function with the following code (remember to make the function async):

app.post('/verify', async (req, res) => {
  const { phoneNumber } = req.body;

  try {
    const accessToken = await createAccessToken();
    const simCheckResult = await performSimCheck(phoneNumber, accessToken);

    if (simCheckResult.simChanged) {
      res.render('error', { error: 'SIM card recently changed. Possible SIM swap attack.' });
    } else if (!simCheckResult.numberSupported) {
      res.render('error', { error: 'Phone number not supported.' });
    } else {
      // Continue with Vonage Verify API code
    }
  } catch (error) {
    // Error handling
    res.render('error', { error: 'An error occurred.' });
  }
});

Wrapping up

That’s it! You have successfully added SIM Swap detection to your existing Vonage Verify 2FA application using tru.ID’s SIMCheck API.

Tham Khảo Thêm:  Network Discovery Guide

For a visual comparison between the Vonage base and the finished app, you can refer to this GitHub repository.

Frequently Asked Questions

Coming soon…

Conclusion

By incorporating the tru.ID SIMCheck API into your Vonage Verify 2FA application, you can efficiently detect SIM swap attacks and enhance the security of your user login flows. The powerful combination of Vonage and tru.ID offers a robust solution to safeguard your users’ accounts. For more detailed information, you can refer to the following resources:

Note: For more information about Eireview, please visit Eireview website.