Forem: tru.ID

Web-Based Secure Password Reset with tru.ID and Vonage

Greg Holmes — Wed, 22 Mar 2023 15:55:39 +0000

The tru.ID SubscriberCheck API confirms the ownership of a mobile phone number by confirming the presence of an active SIM card with the same number. A mobile data session is created with a request to a Check URL unique to this SIM card.

tru.ID then resolves a match between the phone number entered by the user and the phone number that the mobile network operator (MNO) identifies as the owner of the mobile data session.

Any website or mobile application that requires some form of authentication using an email or username and a password will have a password reset flow. Usually, this flow involves the user providing identifying information (email, username, phone number, etc.) and then receiving a code via email or SMS or being asked to answer a secret question.

This is how phishing attackers often gain fraudulent access to online accounts by intercepting the code or secret answer. With tru.ID, this exploitation is no longer possible.

In this tutorial, you will start with a basic web application that doesn't yet provide any form of password reset flow.

As you progress through the tutorial, you will adapt your codebase first to check whether the phone number associated with a user’s account is a phone number from a mobile network operator supported by tru.ID. If the phone number is supported, then the tru.ID SubscriberCheck flow will begin – firstly, to check that the phone number and the data connection match, and secondly, to check the SIM card hasn't recently swapped.

By the end of this tutorial, you will have successfully implemented a password reset flow with tru.ID's SubscriberCheck as the primary method of multi-factor authentication, and Vonage's Verify API as the secondary. If the SubscriberCheck is the triggered flow, the user will have a seamless verification process with no action required and no attack vector.

Before you begin

To follow along with this tutorial, you'll need the following:

A tru.ID Account
Node.js installed locally on your computer
A mobile phone with an active data SIM card

Getting started

A tru.ID Account is needed to make the SubscriberCheck API requests, so make sure you've created one.

You're also going to need some Project credentials from tru.ID to make API calls. So sign up for a tru.ID account, which comes with some free credit. We've built a CLI for you to manage your tru.ID account, projects, and credentials within your Terminal. To install the tru.ID CLI run the following command:

npm install -g @tru_id/cli

Run tru login <YOUR_IDENTITY_PROVIDER> (this is one of google, github, or microsoft) using the Identity Provider you used when signing up. This command will open a new browser window and ask you to confirm your login. A successful login will show something similar to the below:

Success. Tokens were written to /Users/user/.config/@tru_id/cli/config.json. You can now close the browser

Note: The config.json file contains some information you won't need to modify. This config file includes your Workspace Data Residency (EU, IN, US), your Workspace ID, and token information such as your scope.

Create a new tru.ID project within the root directory with the following command:

tru projects:create password-reset-web --project-dir .

Make a note of these tru.ID credentials because you'll need them later in the tutorial.

Note: The users set up in the database for test purposes are configured based on tru.ID's SubscriberCheck Sandbox conditions.

In your Terminal, clone the starter-files branch with the following command:

git clone -b starter-files git@github.com:tru-ID/web-based-password-reset-tutorial.git

If you're only interested in the finished code in main, then run:

git clone -b main git@github.com:tru-ID/web-based-password-reset-tutorial.git

The starter-files branch already contains some third-party libraries needed to get you started. So in your Terminal, within the project directory, run the following command to install these third-party libraries:

npm install
npx sequelize-cli db:migrate # to create the database, and run the migrations.
npx sequelize-cli db:seed:all # to seed the test users into the database.

First, you'll need to expose your project to the Internet for a callback. So to initialize the ngrok tunnel by running the following command:

npx ngrok http 3000

Next, to run the web server, run the following command in your Terminal, in the project directory:

npm start

Once you've started the server, you'll have also created a ngrok tunnel, which shows output similar to what's shown in the example below:

[nodemon] 2.0.16
[nodemon] to restart at any time, enter `rs`
[nodemon] watching path(s): *.*
[nodemon] watching extensions: js,mjs,json
[nodemon] starting `node index.js`
Example app listening at http://localhost:4000
Starting Ngrok now
Ngrok connected, URL: https://<subdomain>.ngrok.io

Below is a screenshot of the landing page you'll be shown when you open localhost:4000 or your ngrok URL in your browser:

The Login screen reached by clicking the Login button will show you a page similar to what's shown in the image below:

Implementing tru.ID SubscriberCheck

Install tru.ID Web SDK

To carry out a SubscriberCheck, we'll be using the tru.ID Web SDK. Install this SDK into your application with the following command:

npm install @tru_id/tru-sdk-web

tru.ID Access Token

You'll want to avoid hardcoding credentials and sensitive information in your codebase; for this, we'll be using Environment Variables. Install dotenv package into your project:

npm install dotenv

Inside src/server.js find the line: const port = 4000; and below this add the following:

require('dotenv').config()

Now, create a .env file in the root directory of your project and add the following:

TRU_ID_CLIENT_ID=
TRU_ID_CLIENT_SECRET=
EXTERNAL_URL=

Note: Populate the values of the above with your own tru.ID client_id and client_secret, while the EXTERNAL_URL is your ngrok URL.

To make API requests to tru.ID you will need to generate an access token with your client_id and client_secret. First, create a new directory called api within your src directory. And within this new directory, create the tru.js file. Populate this file with the following:

const moment = require("moment");
const fetch = require("node-fetch");
const httpSignature = require("http-signature");
const jwksClient = require("jwks-rsa");

const tru_api_base_url = 'https://eu.api.tru.id';
const keyClient = jwksClient({
  jwksUri: `${tru_api_base_url}/.well-known/jwks.json`,
});

// token cache in memory
const TOKEN = {
  accessToken: undefined,
  expiresAt: undefined,
};

async function getAccessToken() {
  // check if existing valid token
  if (TOKEN.accessToken !== undefined && TOKEN.expiresAt !== undefined) {
    // we already have an access token. Let's check if it's not expired
    // by removing 1 minute because the access token is about to expire, so it's better to refresh anyway
    if (
      moment()
        .add(1, "minute")
        .isBefore(moment(new Date(TOKEN.expiresAt)))
    ) {
      // token not expired
      return TOKEN.accessToken;
    }
  }

  const url = `${tru_api_base_url}/oauth2/v1/token`;

  const toEncode = `${process.env.TRU_ID_CLIENT_ID}:${process.env.TRU_ID_CLIENT_SECRET}`;
  const auth = Buffer.from(toEncode).toString('base64');

  const requestHeaders = {
    Authorization: `Basic ${auth}`,
    "Content-Type": "application/x-www-form-urlencoded",
  };

  const res = await fetch(url, {
    method: "post",
    headers: requestHeaders,
    body: new URLSearchParams({
      grant_type: "client_credentials",
      scope: "phone_check coverage subscriber_check",
    }),
  });

  if (!res.ok) {
    return res.status(400).body("Unable to create access token")
  }

  const json = await res.json();

  // update token cache in memory
  TOKEN.accessToken = json.access_token;
  TOKEN.expiresAt = moment().add(json.expires_in, "seconds").toString();

  return json.access_token;
}

Reachability

Creating the Coverage Check

The first step is to determine whether the data connection from the device is a cellular data connection and is supported by tru.ID – a Coverage check. Within your tru.js file, add the following new method:

async function checkCoverage(req, res) {
  const accessToken = await getAccessToken()
  const ip = req.headers['x-forwarded-for'] || req.connection.remoteAddress;

  const deviceCoverageResponse = await fetch(
    `${tru_api_base_url}/coverage/v0.1/device_ips/${ip}`,
    {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    },
  )

  if (deviceCoverageResponse.status === 200) {
    // Loop through products to double check we cover SubscriberCheck for this MNO
    const data = await deviceCoverageResponse.json()

    for (var counter = 0, length = data.products.length; counter < length; counter++) {
      if (data.products[counter] !== null) {
        if (data.products[counter].product_id === 'SUK') {
          return true
        }
      }
    }
  } else if (deviceCoverageResponse.status === 400) {
    // tru.ID has no coverage for this mobile network operator default to SMS
    console.log('tru.ID has no coverage for this mobile network operator. Sending an SMS OTP')
    return false
  } else if (deviceCoverageResponse.status === 412) {
    // Default to SMS
    console.log('IP address is not a mobile IP Address, here, you could suggest the user disabled WiFi. Sending an SMS OTP')
    return false
  } else {
    // Unexpected result from device coverage check. Default to SMS
    console.log('Unexpected result from coverage check. Sending an SMS OTP')
    return false
  }
}

module.exports = {
  getAccessToken,
  checkCoverage
}

Create a new routes file within /src/routes called tru.js. This file will contain the API routes your server needs to process the tru.ID SubscriberCheck flow.

Within this new file, add the following functionality. This functionality takes the IP address of the device accessing the web page to determine whether it is on a mobile network IP address or tru.ID and the mobile network operator has coverage.

const truApi = require('../api/tru')

async function checkCoverage(req, res) {
  try {
    const coverageCheckRes = await truApi.checkCoverage(req, res)

    return res.status(200).json({coverage: coverageCheckRes})
  } catch (error) {
    console.log(error)
    res.sendStatus(500)
  }
}

module.exports = {
  checkCoverage,
}

Now you need to expose this new endpoint through the server. So, open /src/routes.js, and at the top, add the import for your tru.js routes file:

const tru = require('./routes/tru')

Within your routes() function, add the following definition for this /api/coverage endpoint, which will be called from the user's browser:

  router.get('/api/coverage', tru.checkCoverage)

Calling the Coverage Check

To call this coverage check, you need to update the password-reset endpoint's template. Open src/views/password-reset.hbs, and at the bottom of the file, add the following:

<script src="https://cdn.jsdelivr.net/npm/axios/dist/axios.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@tru_id/tru-sdk-web/dist/tru-id-sdk.umd.js"></script>

<script>
  // Step 1 - Do coverage check
  async function checkCoverage(ev) {
    try {
      const deviceCoverageResult = await axios.get('/api/coverage', {
        validateStatus: (status) => status >= 200 && status <= 412,
      })

      // If there's no coverage, prompt the user to turn off WiFi if it's enabled and recheck.
      if (deviceCoverageResult.status === 200 && deviceCoverageResult.data.coverage === true) {
        // tru.ID has coverage.
        await createSubscriberCheck(ev)
      } else if (deviceCoverageResult.status === 400 || deviceCoverageResult.status === 412) {
        // No coverage continue with POST request
        console.log('no coverage')
        return true
      } else {
        // Unexpected result, continue with POST request
        console.log('unexpected result')
        return true
      }
    } catch (ex) {
      // Unexpected result, continue with POST request
      console.log('error')
      console.log(ex)
      return true
    }
  }

  // Step 2 - If covered, do SubscriberCheck(based on the email address....)
  async function createSubscriberCheck(ev) {

  }

  document
    .getElementById('password_reset')
    .addEventListener('submit', async (event) => {
      const coverage = await checkCoverage()
      if (coverage !== true) {
        event.preventDefault()
      }
    })
</script>

The above code imports axios (A promise-based HTTP client for the browser) and tru.ID's SDK. Following the import, the code creates a function called checkCoverage.

Within this function, a GET request is made to your /api/coverage endpoint to check whether the device is supported based on its IP address. At the bottom of this code, you'll see an event listener. This listener can only call the checkCoverage function when the user has submitted the button.

SubscriberCheck

Creating the SubscriberCheck

The SubscriberCheck flow is as follows:

1 - Your Backend makes a POST request to tru.ID to create a check.
2 - tru.ID returns in the response a check_url.
3 - Your web application in the user's browser opens that check_url in the background.
4 - This check_url is direct to that user's mobile network operator (MNO). The MNO verifies the request.
5 - Your backend makes a PATCH request to tru.ID with the code returned at the redirect_url defined when creating the check.

So, open your /src/api/tru.js file and add the following code for this functionality from your Backend's actions:

async function createSubscriberCheck(phone) {
  // Create SubscriberCheck resource
  const token = await getAccessToken()

  const subscriberCheckCreateResult = await fetch(`${tru_api_base_url}/subscriber_check/v0.2/checks`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      phone_number: phone,
      redirect_url: `${process.env.EXTERNAL_URL}/api/sck-password-reset-code`,
    }),
  });

  if (subscriberCheckCreateResult.status === 201) {
    const data = await subscriberCheckCreateResult.json()

    return data
  }

  return false
}

async function patchSubscriberCheck(check_id, code) {
  const url = `${tru_api_base_url}/subscriber_check/v0.2/checks/${check_id}`
  const body = [{ op: 'add', path: '/code', value: code }]

  const token = await getAccessToken()
  const requestHeaders = {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json-patch+json',
  }

  const subscriberCheckPatchResult = await fetch(url, {
    method: 'PATCH',
    headers: requestHeaders,
    body: JSON.stringify(body),
  });

  if (subscriberCheckPatchResult.status === 200) {
    const data = await subscriberCheckPatchResult.json()

    return data
  }

  return {}
}

async function getSubscriberCheckStatus(checkId) {
  const url = `${tru_api_base_url}/subscriber_check/v0.2/checks/${checkId}`

  const token = await getAccessToken()
  const requestHeaders = {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  }

  const subscriberCheckResult = await fetch(url, {
    method: 'GET',
    headers: requestHeaders,
  });

  if (subscriberCheckResult.status === 200) {
    const data = await subscriberCheckResult.json()

    return data
  }

  return {}
}

Now update the exports:

module.exports = {
  getAccessToken,
  checkCoverage,
  createSubscriberCheck,
  patchSubscriberCheck,
  getSubscriberCheckStatus
}

You may have noticed that you've added three functions. All of these will be used through the next steps of this tutorial.

Open /src/routes/tru.js; at the top, add the following two imports:

const db = require('../models')
const { getHashedPassword } = require('../utils/auth')

As previously explained, this file will handle all routes relevant to tru.ID and the SubscriberCheck. So within this file, as well as the checkCoverage function, you'll also have:

createSubscriberCheck - This endpoint takes the phone number and redirect_url, making a POST request to tru.ID, requesting a check_url to be returned to the device.
SubscriberCheckCallback - The endpoint for the previously defined redirect_url, where the web application will end up following the check_url. This request will contain the request_id and code, which will be sent as a PATCH request to tru.ID to complete the flow.
getScPasswordResetCode - Checks the user has an active SubscriberCheck in progress, then renders the template form for the user to enter their email address and their new password.
postScPasswordResetCode - Checks the user has an active SubscriberCheck in progress, then saves the user's new password.

Within the tru.js file, add the following functions:

async function createSubscriberCheck(req, res) {
  const { email } = req.body

  if (!email) {
    return res
      .status(400)
      .json({ error_message: 'email parameter is required' })
  }

  const user = await db.User.findOne({ where: { email: email } })

  if (!user) {
    return res.redirect('password-reset')
  }

  try {
    const subscriberCheckRes = await truApi.createSubscriberCheck(
      user.phone
    )

    if (subscriberCheckRes === false) {
      return res.sendStatus(400)
    }

    // Select data to send to client
    return res.status(200).json({
      check_id: subscriberCheckRes.check_id,
      check_url: subscriberCheckRes._links.check_url.href
    })
  } catch (error) {
    console.log(error)
    return res.sendStatus(500)
  }
}

async function subscriberCheckCallback(req, res) {
  const subscriberCheckResult = await truApi.patchSubscriberCheck(req.query.check_id, req.query.code)

  if (subscriberCheckResult === {}) {
    return res.redirect('/password-reset-code')
  } else if (subscriberCheckResult.match === false || subscriberCheckResult.no_sim_change === false) {
    // Not a match or sim changed, return to reset password with a message.
    var message = 'Unable to verify, please contact support.'
    var messageClass = 'alert-danger'

    return res.redirect(`/login?message=${message}&messageClass=${messageClass}`)
  } else {
    // Success! Move the user to the reset password form.
    return res.redirect(`/sc-password-reset-code?check_id=${req.query.check_id}`)
  }
}

async function getScPasswordResetCode(req, res) {
  const { check_id } = req.query

  if (!check_id) {
    return res.redirect('/login')
  }

  const subscriberCheckStatus = await truApi.getSubscriberCheckStatus(check_id)

  if (subscriberCheckStatus === {} || subscriberCheckStatus.match === false || subscriberCheckStatus.no_sim_change === false) {
    return res.redirect('/login')
  }

  res.render('sc-password-reset-code', { check_id: check_id })
}

async function postScPasswordResetCode(req, res) {
  const { check_id, email, password, password2 } = req.body

  if (!check_id) {
    return res.redirect('/login')
  }

  const subscriberCheckStatus = await truApi.getSubscriberCheckStatus(check_id)

  if (subscriberCheckStatus === {} || subscriberCheckStatus.match === false || subscriberCheckStatus.no_sim_change === false) {
    return res.redirect('/login')
  }

  const user = await db.User.findOne({ where: { email: email } })

  if (!user) {
     return res.render('login', {
      message: 'Invalid email',
      messageClass: 'alert-danger'
    })
  }

  if (password !== password2) {
    return res.render('login', {
      message: 'Passwords don\'t match',
      messageClass: 'alert-danger'
    })
  }

  const hashedPassword = await getHashedPassword(password)
  await user.update({ password: hashedPassword })
  await user.save()

  var message = 'Password has been reset, please log in.'
  res.redirect(`/login?message=${message}&messageClass=alert-success`)
}

Now update the exports at the bottom of the file:

module.exports = {
  createSubscriberCheck,
  checkCoverage,
  subscriberCheckCallback,
  getScPasswordResetCode,
  postScPasswordResetCode
}

Now create the routes for these endpoints to be accessed. Open /src/routes.js and locate the line router.get('/api/coverage', tru.checkCoverage).

Below this line, add the following four new routes:

  router.post('/api/subscriber-check', tru.createSubscriberCheck)
  router.use('/api/sck-password-reset-code', tru.subscriberCheckCallback)

  router.get('/sc-password-reset-code', tru.getScPasswordResetCode)
  router.post('/sc-password-reset-code', tru.postScPasswordResetCode)

You may have noticed a template called sc-password-reset-code.hbs in the new code above. You'll need this, so in /src/views create a new file called sc-password-reset-code.hbs and add the following:

<div class="row justify-content-md-center" style="margin-top: 100px">
    <div class="col-md-6">

        {{#if message}}
            <div class="alert {{messageClass}}" role="alert">
                {{message}}
            </div>
        {{/if}}

        <form method="POST" action="/sc-password-reset-code">
            <input name="check_id" type="hidden" value="{{check_id}}">
            <div class="form-group">
                <label for="emailInput">Email address</label>
                <input name="email" type="email" class="form-control" id="emailInput" placeholder="Enter email">
            </div>
            <div class="form-group">
                <label for="passwordInput">New Password</label>
                <input name="password" type="password" class="form-control" id="passwordInput" placeholder="New Password">
            </div>
            <div class="form-group">
                <label for="passwordInput2">Re-enter your new Password</label>
                <input name="password2" type="password" class="form-control" id="passwordInput2" placeholder="Re-enter New Password">
            </div>
            <button type="submit" class="btn btn-primary">Reset my Password</button>
        </form>
    </div>
</div>

Now, back within /src/views/password-reset.hbs, you'll need the functionality to call these new routes and complete the SubscriberCheck section of the flow. Find the Step 2 Line for the function async function createSubscriberCheck(ev) {. Within this function, add the following:

    console.log('creating subscriber check')
    try {
      const emailInput = document.getElementById('emailInput')

      let emailValue = emailInput.value
      // strip spaces out of the phone number and replace them within an input
      emailValue = emailValue.replace(/\s+/g, '')
      emailInput.value = emailValue
      emailInput.blur()

      // Create SubscriberCheck resource
      const subscriberCheckCreateResult = await axios.post('/api/subscriber-check', {
        email: emailValue
      })

      if (subscriberCheckCreateResult.status === 200) {
        // Step 3 - Open Check URL. If successful, end up on `password-reset-code`. If it fails, call the fallback endpoint. (SMS)
        console.log('opening check url')
        console.log(subscriberCheckCreateResult)
        await tru.ID.openCheckUrl(subscriberCheckCreateResult.data.check_url, {
          checkMethod: 'image',
          debug: true,
          // we don't care here as we are already doing
          // the device coverage check automatically on page load
          // through the node server
          checkDeviceCoverage: false,
        })
      } else {
        return true
      }
    } catch (error) {
      console.log(error)

      if (error.response.status === 400) {
        console.log('Your Mobile Network is not supported or you may be on WiFi, if so disconnect from WiFi.')
      } else {
        console.log('An error occurred while creating a SubscriberCheck.')
      }
      return true
    }

The above piece of code first creates the SubscriberCheck; then, if you've successfully created a check, it will open the check_url returned from the API request and complete the flow. Otherwise, the user will be redirected to the Vonage Verify flow.

Vonage Verification

If the device's IP address is not a mobile network or the network provided is not supported by tru.ID, a fallback is required. We'll use Vonage's Verification flow for this tutorial to send the verification code via SMS. However, you can define the workflow in Vonage's documentation.

To start implementing Vonage's Verify API into the flow, in your Terminal, in the project's root directory, run the following command:

npm install @vonage/server-sdk

Open your .env file and update it with the following extra variables. These variables are of your Vonage API credentials:

VONAGE_API_KEY=
VONAGE_API_SECRET=
BRAND_NAME=
WORKFLOW_ID=6 # SMS only.

Next, create a new file within the api directory to handle your Vonage API calls. Create api/vonage.js and populate this file with the following:

const { Vonage } = require('@vonage/server-sdk')

async function createVerification(phoneNumber) {
  const vonage = new Vonage({
    apiKey: process.env.VONAGE_API_KEY,
    apiSecret: process.env.VONAGE_API_SECRET
  })

  const resp = await vonage.verify.start({
    number: phoneNumber,
    brand: process.env.BRAND_NAME,
    workflow_id: process.env.WORKFLOW_ID
  })  

  if (resp.status === '0') {
    // Success
    return resp.request_id
  }

  return null
}

async function verify(request_id, code) {
  const vonage = new Vonage({
    apiKey: process.env.VONAGE_API_KEY,
    apiSecret: process.env.VONAGE_API_SECRET
  })

  console.log(request_id, code)
  const verify = await vonage.verify.check(request_id, code)

  if (verify.status === "0") {
    // Success
    return verify.request_id

  }

  return null
}

module.exports = {
  createVerification,
  verify
}

This new file you've just created has two functions. The first is to initialise the Verify flow; the second is to handle the response from the user once they receive the code and enter it into the application.

For the Verify flow to work, you'll need to associate a user with a Verify request_id. So first, open /src/models/user.js and, within User.init add the following new field:

requestId: DataTypes.STRING

Now in your Terminal, within the project's root directory, run the following command:

npx sequelize-cli migration:create --name modify_users_add_new_fields

Next, find the new file in /src/migrations. It will be named <timestamp>-modify_users_add_new_field.js.

Within the async up() of this file, replace the contents with:

    return Promise.all([
      queryInterface.addColumn(
        'Users', // table name
        'requestId', // new field name
        {
          type: Sequelize.STRING,
          allowNull: true,
        },
      ),
    ]);

And within the async down() replace the contents with:

    return Promise.all([
      queryInterface.removeColumn('Users', 'requestId'),
    ]);

In your Terminal, run the following command to run the migration:

npx sequelize-cli db:migrate

Locate the /src/routes/auth.js file and add the following import at the top of the file:

const vonage = require('../api/vonage')

Next, within this file, find the function postPasswordReset and replace the last four lines of code:

  res.render('login', {
    message: 'Reset Password Link sent via Email',
    messageClass: 'alert-danger'
  })

With the following:

  const vonageRes = await vonage.createVerification(user.phone)

  if (vonageRes !== null) {
    await user.update({ requestId: vonageRes })
    await user.save()

    return res.redirect('password-reset-code')
  }

  return res.redirect('login')

You'll now need to handle the input from the user, which will contain their email, the verification code, and two copies of their password. Find postPasswordResetCode() and populate this function with the following:

  const { email, password, password2, code } = req.body

  // Check if the user with the same email is also registered
  const user = await db.User.findOne({ where: { email: email } })

  if (!user) {
    res.redirect('/login?message=Invalid email&messageClass=alert-danger')
  }

  if (password !== password2) {
    res.render('register', {
      message: 'Passwords do not match.',
      messageClass: 'alert-danger'
    })
  }

  const vonageRes = await vonage.verify(user.requestId, code)

  if (vonageRes !== null) {
    const hashedPassword = getHashedPassword(password)

    await user.update({ requestId: null, password: hashedPassword })
    await user.save()

    let message = 'Password successfully reset. Please log in with your new credentials.'
    let messageClass = 'alert-success'

    return res.redirect(`/login?message=${message}&messageClass=${messageClass}`)
  }

  let message = 'No password-reset in progress. Please restart.'
  let messageClass = 'alert-danger'

  return res.redirect(`/login?message=${message}&messageClass=${messageClass}`)

Wrapping up

That's it! You've now introduced a secure password reset flow within your web application using tru.ID's SubscriberCheck API, and a Vonage Verify backup in case the SubscriberCheck is not possible.

The SubscriberCheck verifies that the user is the owner of that phone number, SIM card, and active data connection, and that the SIM card has not recently been swapped.

Resources

SSH Multi-factor Authentication with tru.ID

Greg Holmes — Thu, 05 May 2022 12:28:46 +0000

Secure Shell (SSH) is a network protocol that enables users to securely connect from one computer to another remotely. The majority of people that use SSH are system administrators, and the most common use for this protocol is to manage a server remotely.

It doesn't matter what point of your technical career you are at; if you deal with servers, you will have needed SSH as a protocol to modify or maintain remote servers on countless occasions. You may have increased security on your server by using an SSH certificate instead of a username and password. However, someone with malicious intent could still gain access to these authentication methods. That’s why it’s worth enabling multi-factor authentication (MFA) for your SSH server.

The tru.ID PhoneCheck API confirms the ownership of a mobile phone number by checking for the presence of an active SIM card with the same number. As well as creating a frictionless user experience, this method is significantly more secure than legacy methods such as SMS OTP. tru.ID APIs call the mobile network directly rather than relying on vulnerable SS7 protocols, providing a real-time SIM card check in under 2 seconds.

Before you begin

To follow along with this tutorial, you'll need:

A tru.ID Account
A mobile phone with an active data SIM card
Docker installed locally
Node installed locally

Getting started

A repository branch has been created on GitHub containing the foundation code needed to get you started.

In your Terminal, clone the starter-files branch for this repository with the following command:

git clone -b starter-files git@github.com:tru-ID/tru-id-ssh-auth.git

If you're interested in the finished code, you can find the complete example in the main branch. To get this code, run:

git clone -b main git@github.com:tru-ID/tru-id-ssh-auth.git

A tru.ID Account is required to make the PhoneCheck API requests, so before proceeding, make sure you've created one.

Now navigate to the tru.ID console and create a project. Once created, before you close the window or navigate away, be sure you download the tru.json credentials file and move it to the root directory of your tru-id-ssh-auth project directory.

Within the credentials file, you'll find your project_id, project_name, the scopes available to your project, and your client_id and client_secret, which you'll use to create an auth token to make API requests.

Define core variables

Throughout your code, you'll be reusing several bits of information; these are variables such as the PhoneCheck URL and the destination directory where your project is installed, for example. Below the line VERSION=1 in the file ssh-auth, add the following:

# Base URL information
DATA_RESIDENCY=eu
BASE_URL="https://$DATA_RESIDENCY.api.tru.id"

# API Check URLs
PHONE_CHECK_URL="$BASE_URL/phone_check/v0.2/checks"
GET_PHONE_CHECK_URL="$BASE_URL/phone_check/v0.2/checks/"
CREATE_AUTH_TOKEN_URL="$BASE_URL/oauth2/v1/token"

APP_ROOT=`dirname $0`
CONFIG_FILE="$APP_ROOT/tru-id-ssh-auth.conf"
DEST_DIRECTORY="/usr/local/bin/"

# Empty Global Variables
BASIC_AUTH_USER=
BASIC_AUTH_PASSWORD=
ACCESS_TOKEN=

The only two values available for you to change are:

DATA_RESIDENCY, which could be either of the two supported data residencies; eu or in,
DEST_DIRECTORY, which is the destination for the project once installed.

Create the install

The majority of this project will be within one single bash file, with multiple commands available. The first is the install command, which copies the relevant code to the desired installation directory. You'll also apply a ForceCommand to the SSHd config file, which you will add later in the tutorial.

Start by locating the function require_curl within the ssh-auth file. Below this require_curl function, add the following code, which is your new install() function:

function install() {
    config_file="${DEST_DIRECTORY}tru-id-ssh-auth/tru-id-ssh-auth.conf"

    set -e
    echo "Making directory in ${DEST_DIRECTORY}"
    mkdir "/usr/local/bin/tru-id-ssh-auth"
    set +e

    if [[ ! -r `dirname "${DEST_DIRECTORY}"` ]]
    then
      echo "${DEST_DIRECTORY} is not writable. Try again using sudo"
      return $FAIL
    fi

    echo "Copying /root/tru-id-ssh-auth/ to ${DEST_DIRECTORY}..."
    cp -r "/root/tru-id-ssh-auth" "${DEST_DIRECTORY}"

    echo "Setting up permissions..."
    chmod 755 $DEST_DIRECTORY

    if [[ ! -f ${config_file} ]]
    then
      echo "Generating initial config on ${config_file}..."
      echo "header=tru.ID SSH Auth initialised." > "${config_file}"
    else
      echo "A config file was found on ${config_file}. Edit it manually if you want to change the API key"
    fi

    chmod 644 ${config_file}

    echo ""
    echo "To enable tru.ID authentication on a user the following command: "
    echo ""

    echo "   ${DEST_DIRECTORY}tru-id-ssh-auth/ssh-auth register-user <username> <phone-number-inc-country-code>"
    echo "   Example: ${DEST_DIRECTORY}tru-id-ssh-auth/ssh-auth register-user test 447000000000"

    echo ""
    echo "To uninstall tru.ID SSH type:"
    echo ""
    echo "   ${DEST_DIRECTORY}tru-id-ssh-auth/ssh-auth uninstall"
    echo ""
    echo "      Restart the SSH server to apply changes"
    echo ""
}

There are several steps included in this new function. These are:

Make the directory for the location of the installed application, /usr/local/bin/tru-id-ssh-auth.
Check the directory is writeable. If not, then throw an error.
Copy the project files to the newly created destination directory.
Check if a config file exists. If not, then create one.
Output text to Terminal, instructing users how to use and uninstall the application.

As previously mentioned, more functionality is needed to uninstall this script. Below your newly created install() function, add the following uninstall() function:

function uninstall() {
    find_sshd_config

    if [[ $1 != "quiet" ]]
    then
      echo "Uninstalling tru.ID SSH from $SSHD_CONFIG..."
    fi

    if [[ -w $SSHD_CONFIG ]]
    then
        sed -ie '/^ForceCommand.*tru-id-ssh-auth.*/d' $SSHD_CONFIG
    fi

    if [[ $1 != "quiet" ]]
    then
        echo "tru.ID SSH was uninstalled."
        echo "Now restart the ssh server to apply changes and then remove ${DEST_DIRECTORY}/tru-id-ssh-auth"
    fi
}

The first line within this new function is to call a function called find_sshd_config(), so let's add this:

function find_sshd_config() {
    echo "Trying to find sshd_config file"
    if [[ -f /etc/sshd_config ]]
    then
        SSHD_CONFIG="/etc/sshd_config"
    elif [[ -f /etc/ssh/sshd_config ]]
    then
        SSHD_CONFIG="/etc/ssh/sshd_config"
    else
        echo "Cannot find sshd_config in your server. tru.ID SSH Auth will be enabled when you add your specific ForceCommand to the sshd config file."
    fi
}

The new function locates your server's sshd_config file and stores this file location as a global variable.

Both the install() and uninstall() functions are inaccessible until you add them as a parameter. In the list of commands for this project, find the line:

case $1 in

This section of code contains the functionality that understands various arguments in the command when running your bash script. So below the case line, add the following two new command-line arguments:

install)
    check_dependencies
    install
    ;;
uninstall)
    uninstall
    ;;

Registering users

The SIM authentication process requires users to be enabled individually by entering their phone number and linking it with their username to allow them to verify with tru.ID's PhoneCheck API.

To register a new user, create a new register_user() function by copying the below example in your ssh_auth file:

function register_user() {
  config_file="${DEST_DIRECTORY}tru-id-ssh-auth/tru-id-ssh-auth.conf"

  if [[ $2 && $3 ]]
  then
      echo "user=$2:$3" >> ${config_file}
      echo "" >> ${config_file}
      echo "User was registered"
  else
      echo "Cannot register user"
  fi
}

Your new register_user() function finds the tru-id-ssh-auth.conf file and adds the following as a new line: user={username}:{phone number}.

Near the bottom of the file, find the line case $1 in. Below this line, enable the register_user() function as a command-line argument by adding the following:

    register-user)
        check_dependencies
        register_user "$@"
        ;;

Allow the User in

Once the PhoneCheck is successful, the function run_shell will be called, which tells the plugin the user is allowed access to their SSH session, in the ssh-auth file, add the following function:

# Once successful, allows user to proceed with access to server
function run_shell() {
    if [[ "$SSH_ORIGINAL_COMMAND" != "" ]]
    then
        exec /bin/bash -c "${SSH_ORIGINAL_COMMAND}"
    elif [ $SHELL ]
    then
        exec -l $SHELL
    fi

    exit $?
}

Creating a PhoneCheck

Retrieve credentials

To make calls to the tru.ID API, you'll need to retrieve your project's credentials, which you can find in the tru.json file you moved into your project earlier. The get_credentials() function below retrieves your project's client_id and client_secret from this file, then sets them as two global variables: BASIC_AUTH_USER and BASIC_AUTH_PASSWORD. Add this new function to your ssh-auth file:

function get_credentials() {
  FILE="${DEST_DIRECTORY}tru-id-ssh-auth/tru.json"

  if [ -f "$FILE" ]; then
    BASIC_AUTH_USER=$(jq -r ".credentials[].client_id" ${FILE})
    BASIC_AUTH_PASSWORD=$(jq -r ".credentials[].client_secret" ${FILE})

    return $OK
  fi

  echo "Unable to retrieve project credentials. Please make sure your project directory has a `tru.json` file."
  exit $FAIL
}

Create access tokens

The next part to creating a PhoneCheck via API is to add functionality to generate access tokens using your tru.ID project's credentials. This new functionality will make a POST request to https://{DATA_RESIDENCY}.api.tru.id/oauth2/v1/token, with a header containing your BASIC_AUTH_USER and BASIC_AUTH_PASSWORD, concatenated with a : in between, and then the entire string encoded with base64. The access token received will be what you use to make further secure API requests to tru.ID's API.

Copy the create_access_token() function below into your ssh_auth file.

# Creates an access token needed to create a PhoneCheck request.
function create_access_token() {
    get_credentials

    CREDENTIALS=$(echo -ne "$BASIC_AUTH_USER:$BASIC_AUTH_PASSWORD" | base64 -w 0);

    # Make request to get access token
    response=`curl \
        --header "Authorization: Basic $CREDENTIALS" \
        --header "Content-Type: application/x-www-form-urlencoded" \
        --request POST $CREATE_AUTH_TOKEN_URL\
        --data-urlencode "grant_type=client_credentials" \
        --data-urlencode "scope=phone_check coverage" --silent`

    curl_exit_code=$?

    # Parses response to get the access token
    ACCESS_TOKEN=$(jq -r .access_token <<< "${response}" )

    if [ $curl_exit_code -ne 0 ]
    then
        echo $curl_exit_code
        echo "Error running curl"
    fi
}

Create a PhoneCheck

You've created functions that allow you to retrieve your project's credentials from your tru.json file; your next function then uses the credentials from this file to generate an access token that you're going to use to make authenticated API calls.

The next step in this tutorial is to initialise the PhoneCheck, which will do the following:

Retrieve the current user attempting to log in.
Read the config file to find whether this user has their phone number registered to require the MFA step.
Make a POST request to https://{DATA_RESIDENCY}.api.tru.id/phone_check/v0.2/checks" with the user's phone number.

Copy the function below into your ssh_auth file to add the functionality described into your project:

function create_check() {
    config_file="${DEST_DIRECTORY}tru-id-ssh-auth/tru-id-ssh-auth.conf"
    current_user=$USER;
    phone_number="";

    while read line; do
        if [[ $line =~ user=$current_user: ]] ; then
            phone_number=$(echo "${line}" | sed s/user=${current_user}://g);
        fi
    done <${config_file}

    if [ "$phone_number" == "" ]; then
        echo "Phone Number is empty"

        return 0
    fi

    # Checking Credentials are installed
    get_credentials

    # Creating an Access Token
    create_access_token

    # Making a Phone Check request"
    response=`curl \
        --header "Authorization: Bearer $ACCESS_TOKEN" \
        --header "Content-Type: application/json" \
        --request POST $PHONE_CHECK_URL\
        --data-raw "{\"phone_number\":\"${phone_number}\"}" --silent`

    curl_exit_code=$?

    if [ $curl_exit_code -ne 0 ]
    then
        echo "Error running curl"
        return 1;
    fi

    # Handling Phone Check Response
    check_id=$(jq -r .check_id <<< "${response}" )
    status=$(jq -r .status <<< "${response}" )
    check_url=$(jq -r ._links.check_url.href <<< "${response}" )

    return $CHECK_STATUS;
}

Generate a QR code

When the user has created a PhoneCheck, the next step in the MFA flow is for the user's device to open their mobile network operator's check URL.

The easiest way for the user to open the URL is with a QR code. If you check your Dockerfile within your project directory, you've already installed the library qr when you built the Docker container. So the next step is to take the check_url retrieved from the PhoneCheck response. This check_url needs to be converted into a QR code and displayed for the user.

Inside create_check(), find the line check_url=$(jq -r ._links.check_url.href <<< "${response}" ), and below it, add the following:

# Generate QR code
qr --ascii "${check_url}" > "qrcode.txt"

sleep 1

cat ~/qrcode.txt

Set up polling

The next step in this process is for your application to check tru.ID's API endpoint https://{DATA_RESIDENCY}.api.tru.id/phone_check/v0.2/checks/{check_id} to determine whether there was a match between the phone number and the request to the check URL or not. There is a two-minute window when the check is created for the user to open the URL. The application will make requests to the API every five seconds for a status update.

If the status value is COMPLETED and the response body contains the value of match as true, then allow the user through; otherwise, refuse entry to the server.

Copy the new start_polling() function into your ssh_auth file:

function start_polling() {
    # Check every 5 seconds for status on Check.
    interval_in_seconds=5
    CHECK_STATUS=$FAIL

    while true;
    do
        # Check status of phone check
        response=`curl \
            --header "Authorization: Bearer $ACCESS_TOKEN" \
            --header "Content-Type: application/json" \
            --request GET $GET_PHONE_CHECK_URL/${check_id}  --silent`

        curl_exit_code=$?

        if [ $curl_exit_code -ne 0 ]
        then
            echo "Error running curl"

            return $FAIL;
        fi

        status=$(jq -r .status <<< "${response}" )
        match=$(jq -r .match <<< "${response}" )

        # If check is complete, output
        if [[ "$status" != "PENDING" && "$status" != "ACCEPTED" ]]; then
            if [ "$status" == "COMPLETED" ]; then
                if [ "$match" == "true" ]; then
                  CHECK_STATUS=$OK;

                  run_shell
                else
                  echo "No match found!"
                  CHECK_STATUS=$FAIL

                  return $FAIL;
                fi
            elif [ "$status" == "EXPIRED" ]; then
                echo "Check Expired";
                CHECK_STATUS=$FAIL

                return $FAIL;
            elif [ "$status" == "ERROR" ]; then
                echo "Check Error Received";
                CHECK_STATUS=$FAIL

                return $FAIL;
            else
                echo "$status"
                echo "404, no status was found";
                CHECK_STATUS=$FAIL

                return $FAIL;
            fi

            break;
        fi

        # Otherwise continue
        sleep $interval_in_seconds;
    done
}

You need to call this new function within your create_check() function. Find the line cat ~/qrcode.txt, and below this, add the following to trigger the start_polling functionality:

# Start polling
start_polling

Add the create_check as a command-line argument by finding the line: case $1 in, and adding the following:

    create-check)
        check_dependencies
        create_check "$@"
        ;;

Add ForceCommand

In your ssh-auth file, you've already called the function add_force_command, but it doesn't yet exist to add the ForceCommand to your sshd_config file. So add this function:

function add_force_command() {
    echo "Trying to add force command to $SSHD_CONFIG"
    find_sshd_config
    auth_ssh_command="$1"

    if [[ -w $SSHD_CONFIG ]]
    then
      echo "Adding 'ForceCommand ${auth_ssh_command} login' to ${SSHD_CONFIG}"
      uninstall "quiet" # remove previous installations

      echo -e "\nForceCommand ${auth_ssh_command} login" >> ${SSHD_CONFIG}
      echo ""

      check_sshd_config_file

      echo "    MAKE SURE YOU DO NOT MOVE/REMOVE ${auth_ssh_command} BEFORE UNINSTALLING tru.ID SSH Plugin"
      sleep 5
    fi
}

If you're following along with this tutorial using Docker, open the sshd_config file within your project directory and at the bottom of this file add the following force command:

ForceCommand /usr/local/bin/tru-id-ssh-auth/ssh-auth create-check

Once added you can skip to Complete PhoneCheck. However, if you're installing this on a server, please continue with the instructions below:

Note: If you're following along with this tutorial using the Docker container, you won't need this code snippet; however, when installing on a server other than Docker, the line is needed and needs to be uncommented. Find the line chmod 644 ${config_file} inside your install() function and add the following; you'll also need to uncomment it.

    # When following this tutorial, leave the line below commented out.
    # Restarting your SSH server within Docker will restart the whole Docker container.
    # add_force_command "${DEST_DIRECTORY}tru-id-ssh-auth/ssh-auth create-check"

Complete PhoneCheck

The final step in the PhoneCheck process is to complete the PhoneCheck. When the mobile device opens the mobile network operator's check URL, they're eventually redirected back to your redirect_url, which on the final request, will have a response containing a code. This code needs to be submitted through the API with your credentials to complete the PhoneCheck.

In your starter-files repository, you will find a template webserver built in node. This is the webserver that will contain the code of your redirect_url that will carry out this functionality.

Install third party dependencies

In your Terminal, navigate to the webserver directory and run the following command to install the third party libraries required for this tutorial. These libraries include express for the webserver functionality, ngrok to provide a publicly accessible URL, and http-signature to verify the signature in the API request.

npm install

Create the webhook

Find the endpoint:

app.get("/", async (req, res) => {
  res.send('hello');
});

And replace it with:

app.get("/complete-check", async (req, res) => {
  if (!req.query) {
    res.status(400).send("body missing");

    return;
  }

  const { code, check_id } = await req.query;

  if (!code) {
    res.status(400).send("code missing");

    return;
  }

  if (!check_id) {
    res.status(400).send("check_id missing");

    return;
  }

  if (req.query.redirect_url) {
    const verified = await tru.verifySignature(req.query.redirect_url);

    if (!verified) {
      res.status(400).send("signature not verified");

      return;
    }
  }

});

In the above example, you're creating a new webhook /complete-check which is accessible with a GET request. This request takes three parameters in the URL, check_id, code, and redirect_url. These parameters are used to complete the PhoneCheck. Once checks have been made to make sure they've been included, the code verifys the signature is valid for the redirect url.

Next, within the webserver directory, create a new file tru.js which is where you're going to add the tru.ID API functionality. In this file, the first thing is to add the dependencies that will be used, as well as defining the global variables and objects. Add the following:

const moment = require("moment");
const fetch = require("node-fetch");
const httpSignature = require("http-signature");
const jwksClient = require("jwks-rsa");
const config = require("../tru.json");

const tru_api_base_url = 'https://eu.api.tru.id';
const keyClient = jwksClient({
  jwksUri: `${tru_api_base_url}/.well-known/jwks.json`,
});

// token cache in memory
const TOKEN = {
  accessToken: undefined,
  expiresAt: undefined,
};

When making a request to an endpoint in tru.ID's API, you'll need an access token:

async function getAccessToken() {
  // check if existing valid token
  if (TOKEN.accessToken !== undefined && TOKEN.expiresAt !== undefined) {
    // we already have an access token let's check if it's not expired
    // I'm removing 1 minute just in case it's about to expire better refresh it anyway
    if (
      moment()
        .add(1, "minute")
        .isBefore(moment(new Date(TOKEN.expiresAt)))
    ) {
      // token not expired
      return TOKEN.accessToken;
    }
  }

  const url = `${tru_api_base_url}/oauth2/v1/token`;

  const toEncode = `${config.credentials[0].client_id}:${config.credentials[0].client_secret}`;
  const auth = Buffer.from(toEncode).toString('base64');

  const requestHeaders = {
    Authorization: `Basic ${auth}`,
    "Content-Type": "application/x-www-form-urlencoded",
  };

  const res = await fetch(url, {
    method: "post",
    headers: requestHeaders,
    body: new URLSearchParams({
      grant_type: "client_credentials",
      scope: "phone_check coverage",
    }),
  });

  if (!res.ok) {
    return res.status(400).body("Unable to create access token")
  }

  const json = await res.json();

  // update token cache in memory
  TOKEN.accessToken = json.access_token;
  TOKEN.expiresAt = moment().add(json.expires_in, "seconds").toString();

  return json.access_token;
}

A new function patchPhoneCheck is needed, which will make a PATCH request to tru.ID's API: /phone_check/v0.2/checks/${checkId}, with the code contained in the body. This is a method to verify the owner of the SIM card was the one that requested the PhoneCheck. In your tru.js file add the following new function:

async function patchPhoneCheck(checkId, code) {
  const url = `${tru_api_base_url}/phone_check/v0.2/checks/${checkId}`;
  const body = [{ op: "add", path: "/code", value: code }];

  const token = await getAccessToken();
  const requestHeaders = {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json-patch+json",
  };

  const res = await fetch(url, {
    method: "patch",
    headers: requestHeaders,
    body: JSON.stringify(body),
  });

  if (!res.ok) {
    return res;
  }

  const json = await res.json();

  return json;
}

As previously explained, you need to verify the signature provided with the redirect_url, to ensure it hasn't been altered in any way. This can be carried out with the following function, so add this to your file:

async function verifySignature(originalUrl) {
  try {
    const url = new URL(originalUrl);
    const signature = Buffer.from(
      url.searchParams.get("authorization"),
      "base64"
    ).toString("utf-8");
    const date = Buffer.from(url.searchParams.get("date"), "base64").toString(
      "utf-8"
    );

    url.searchParams.delete("authorization");
    url.searchParams.delete("date");

    const originalRequest = {
      url: `${url.pathname}${url.search}`,
      method: "get",
      hostname: url.hostname,
      headers: {
        date,
        host: url.host,
        authorization: signature,
      },
    };

    const parsedOriginalRequest = httpSignature.parseRequest(originalRequest, {
      clockSkew: 300,
    });

    const jwk = await keyClient.getSigningKey(parsedOriginalRequest.keyId);
    const verified = httpSignature.verifySignature(
      parsedOriginalRequest,
      jwk.getPublicKey()
    );
    return verified;
  } catch (err) {
    console.error(err);
    return false;
  }
}

The two new functions patchPhoneCheck and verifySignature need to be accessed in your index.js file, so at the bottom of the tru.js file add the following exports for these two:

module.exports = {
  patchPhoneCheck,
  verifySignature
};

Back in your index.js file, at the top among the requires, add the line:

const tru = require("./tru");

Find the complete-check endpoint, and at the bottom of this function, add the following:

  try {
    const check = await tru.patchPhoneCheck(check_id, code);

    if (check.status === "COMPLETED" && check.match) {
      res.status(200).send('Verification complete, please close this tab and return to your SSH session.');

      return;
    } else {
      // verification failed = user not authenticated
      res.status(401).send("Verification failed, false match");

      return;
    }
  } catch (err) {
    console.log(err);

    if (err.status) {
      res.status(err.status || 500).send(err.message);
    } else {
      res.status(500).send("Unexpected Server error");
    }

    return;
  }

The above code calls the patchPhoneCheck created in your tru.js file, which makes a PATCH request to the tru.ID API with the body containing the code needed to complete the PhoneCheck process.

Now in your Terminal, inside the webserver directory, run the following command and make note of the ngrok url output:

npm start

In your ssh-auth file, find the line: # API Check URLs and below this add the following, replacing <Your NGROK URL>, with the ngrok URL you made a note of in the previous step:

BACKEND_SERVER="<Your NGROK URL>"
REDIRECT_URL="$BACKEND_SERVER/complete-check"

To have the final redirect be your specified webhook URL, find the line below:

--data-raw "{\"phone_number\":\"${phone_number}\"}" --silent`

And replace it with:

--data-raw "{\"phone_number\":\"${phone_number}\", \"redirect_url\":\"${REDIRECT_URL}\"}" --silent`

Setting up the Docker container

This tutorial makes use of a Docker container for development purposes. To build this Docker container and have it running, you'll need to:

Build and run your Docker container. This process will also map the internal port 22 (ssh) to an externally accessible port 223.
Open the Docker container with a bash session.

So, in your Terminal, run the following two commands:

docker-compose up --build -d
docker-compose exec ssh bash

Installing the SSH Plugin

You've now added multi-factor authentication to your SSH authentication process. With your Docker container built and running, change to the project directory in the same terminal instance. For this, the default directory is /root/tru-id-ssh-auth/. Then run the command ./ssh-auth install to install your copy of your project directory over to /usr/local/bin/.

Note: This is defined in your Dockerfile at the line: ADD . /root/tru-id-ssh-auth

cd /root/tru-id-ssh-auth/
./ssh-auth install

The command ./ssh-auth install will do the following:

Copy your project directory from /root/tru-id-ssh-auth/ to /usr/local/bin/tru-id-ssh-auth/.
Create a /usr/local/bin/tru-id-ssh-auth/tru-id-ssh-auth.conf config file.

Registering a user

With the plugin installed, you now need to enable the check for the user(s). This stores the user's name and phone number into your recently created config file. The application will then compare this with the credentials entered when the user attempts to log in. Still in the same Terminal, run the following command, swapping out the placeholders for your valid details:

Note: The Docker user and password are both test.

/usr/local/bin/tru-id-ssh-auth/ssh-auth register-user <username> <phone-number-inc-country-code>
# For example: /usr/local/bin/tru-id-ssh-auth/ssh-auth register-user test 447000000000

Login attempt

You've now set everything up. To check everything is working, open a new Terminal session and run the following command to SSH into your SSH server:

ssh test@127.0.0.1 -p 223

The Docker config example uses the username test and the password test.

Wrapping up

That's it! You've now introduced a multi-factor authentication step for your server's SSH authentication process using tru.ID's PhoneCheck API. The beauty of this is it limits the user's input, by only having to require the user to enter their SSH credentials and then scan the QR code, they don’t need to wait for a code to come through SMS or other means for example. The MFA process is all carried out in the background once the QR code has been scanned on their mobile device.

Resources

SIM Card Based Mobile Authentication with iOS

Greg Holmes — Mon, 08 Nov 2021 15:11:00 +0000

tru.ID SubscriberCheck offers both mobile phone number verification and SIM swap detection. SubscriberCheck achieves this by combining the workflows of PhoneCheck, which confirms the ownership of a mobile phone number by verifying the possession of an active SIM card with the same number, with SIMCheck, which provides information on when a SIM card associated with a mobile phone number was last changed. SubscriberCheck can be used when augmenting existing 2FA or anti-fraud workflows.

If you'd prefer to go directly to the completed code, it's in the sim-card-auth-ios Github repository.

Before you begin

For development you'll need:

Xcode 12
An Apple developer account via the Apple Developer Portal
An iPhone or an iPad with a SIM card with an active data connection
Node.js installed for the tru.ID CLI

With the above in place, let's dive straight into adding SubscriberCheck functionality to your iOS applications.

Set-up the tru.ID CLI and Run a Development Server

tru.ID provides a tru.ID CLI to quickly set up a development environment and provide a development server on your machine.

The development server acts as a proxy in between your mobile app and the tru.ID servers. It also opens up a local tunnel that makes the server publicly accessible over the Internet, so your mobile device can still connect to it when on cellular data. This architecture means you can focus on the mobile application development during this tutorial.

Your production architecture should mirror this client/server architecture (but may not be the same API), with your servers acting as a secure proxy to the tru.ID APIs. See the SubscriberCheck Workflow Integration guide for more details.

With the background information out of the way, sign up for a tru.ID account account. The account comes with some free credits, which you can use during the development and to test your app against the production environment when it is ready.

Next, install the tru.ID CLI:

npm install -g @tru_id/cli

Run the tru setup:credentials command with the credentials you can copy from the tru.ID console:

Install the CLI development server plugin:

tru plugins:install @tru_id/cli-plugin-dev-server

Create a new tru.ID project:

tru projects:create iOSAuthDemoServer

This saves a tru.json tru.ID project configuration to ./iosauthdemoserver/tru.json.

Run the development server by pointing it to the newly created project directory and configuration.

tru server -t --project-dir ./iosauthdemoserver

Check that the URL that is shown in the terminal is accessible in your web browser. The URL is in the format https://{subdomain}.loca.lt. This is the public accessible URL to your local development server.

Create a New iOS Project

With the tru.ID account created and the development server up and running, we can make a start with the application. You can skip this step if you already have an iOS project. Otherwise;

Launch your Xcode
File -> New -> Project
In the "Choose a template for your new project" modal, select App and click Next
Set "sim-card-auth-ios" as the Product Name, however, you can use whatever the name of your project is
Select your Team, and make sure to assign an organization identifier using a reverse domain notation
Keep it simple, and use a Storyboard, UIKit App Delegate and Swift as the development language
Uncheck Use Code Data if it is checked, and click Next
Select the folder you want to store your project in and click Next

As you see, it is a pretty simple project with a single ViewControlller. At this point, you do not need to worry about the AppDelegate or SceneDelegate. This is enough to demonstrate SubscriberCheck.

If you already have Xcode and have added your developer account (Xcode->Preferences->Accounts), Xcode takes care of generating necessary certificates and provisioning profiles in order to install the app on the device.

Build the User Interface

Navigate to the Main.storyboard. You need to add a few UI components to receive input from the user, and provide feedback:

Add a UILabel to the View Controller's view as a title with a text "Verification"
A UIActivityIndicator (Large) to show/hide progress when you perform a SubscriberCheck
A UILabel with a text "Phone number" to indicate what the next text field is for
A UITextField so that the user can enter their phone number
A UIButton to trigger the SubscriberCheck request
A UImageView to show whether SubscriberCheck is successful or not

All UI components are "Horizontally" aligned in the container using constraints. You should also need to define constraints to anchor the components as well.

Start with the top "Verification" UILabel and specify the alignment between the Safe Area and the label. Do the same for all other components, define a constraint for the Top space, and where necessary, add additional constraints for width and height.

The view layout should look like this:

There are a few configuration options you should add for these UI components.

Phone number UITextField: Select the text field, and on the Attributes Inspector, scroll to Text Input Traits and change the Content Type to Telephone Number. Also, change the Keyboard Type to Phone Pad.
UIActivityIndicator: Select the activity indicator, and on the Attributes Inspector check Hides When Stopped
UIImageView: Select the UIImageView, and on the Attributes Inspector, scroll to Drawing, and check Hidden

Now, you need to define Outlets in the ViewController so that you can control the UI state. Let's select ViewController in Xcode, and then by using the ⌥ select Main.storyboard file. Both ViewController.swift and Main.storyboard should be opened side by side.

Select the UIActivityIndicator you inserted to the storyboard, and with ⌃ key pressed, drag a connection from the storyboard to the ViewController.swift. Xcode indicates possible places in the Editor where you can create an Outlet.

When you are happy, release the keys and mouse/trackpad. You will be prompted to enter a name for the variable; type busyActivityIndicator.

You need to connect the UITextField, UIButton and the UIImageView as well. Let's perform the above steps for these as well respectively, and name them as follows:

phoneNumberTextField
nextButton
checkResults

This allows you to retrieve the phone number entered by the user, and control the state to provide feedback. You now have one last task to do related to the storyboard.

Let's insert an action. When a user taps on the Next button, you want the ViewController to know that the user wants to initiate the SubscriberCheck. So select the Next button, and with your ⌃ key pressed drag a connection from the storyboard to the ViewController.swift. Xcode indicates possible places where you can create an IBAction. When you are happy, release the keys and mouse/trackpad. You will be prompted to enter a name for the method: type next and Xcode will insert the method with a IBAction annotation.

It is time to write some code to manage the UI state. The first method you are going to add is controls(enabled: Bool). This method helps us show or hide the checkResults, and busyActivityIndicator. You should also disable the phoneNumberTextField when the SubscriberCheck flow is in progress.

// MARK: UI Controls Configure || Enable/Disable

private func controls(enabled: Bool) {

    if enabled {
        busyActivityIndicator.stopAnimating()
    } else {
        busyActivityIndicator.startAnimating()
    }

    phoneNumberTextField.isEnabled = enabled
    nextButton.isEnabled = enabled
    checkResults.isHidden = !enabled
}

private func configureCheckResults(match: Bool, noSimChange: Bool) {

    if match {
        let image = UIImage(systemName: "person.fill.checkmark")
        self.checkResults.image = image?.withRenderingMode(.alwaysTemplate)
        self.checkResults.tintColor = .green
    } else {
        let image = UIImage(systemName: "person.fill.xmark")
        self.checkResults.image = image?.withRenderingMode(.alwaysTemplate)
        self.checkResults.tintColor = .red
    }
}

You will use these methods later in the next(_ sender: Any) that is triggered by the user tapping the Next button.

Models, Structs & Protocols

Now is the time to create a new group called service in the Project Navigator. In here you'll implement Model layer classes, structs, protocols and enums. Note that none of the files in this group should be importing UIKit.

Create a Swift file in the service group called SessionEndpoint.swift. In this file, we define a protocol called Endpoint and NetworkError of type Enum and a class which implements the protocol. Let's define the protocol Endpoint and NetworkError enum as in the following in this file.

import Foundation

protocol Endpoint {
    var baseURL: String { get }
    func makeRequest<U: Decodable>(urlRequest: URLRequest,
                     handler: @escaping (Result<U, NetworkError>) -> Void)

    func createURLRequest(method: String,
                          url: URL,
                          payload:[String : String]?) -> URLRequest
}

enum NetworkError: Error {
    case invalidURL
    case connectionFailed(String)
    case httpNotOK
    case noData
}

The purpose of the Endpoint protocol is to hide implementation details from the client of this protocol. It has two methods and a variable baseURL. It represents one REST API endpoint. We'll come back to this in more detail later.

Next, define our model object which holds SubscriberCheck results.

Create a Swift file called SubscriberCheck.swift in the service, and implement a struct with the same name as below:

import Foundation

// Response model based on https://developer.tru.id/docs/reference/api#operation/create-subscriber-check
struct SubscriberCheck: Codable {
    let check_id: String?
    let check_url: String?
    let status: SubscriberCheckStatus?
    let match: Bool?
    let no_sim_change: Bool?
}

enum SubscriberCheckStatus: String, Codable {
    case ACCEPTED
    case PENDING
    case COMPLETED
    case EXPIRED
    case ERROR
}

tru-ID REST API documentation provides us the basis for this struct. In production, your architecture and servers may expose a different REST response model. Also important to note that SubscriberCheck implements the Codable protocol as this will help JSONSerialization.data(..) to decode the json response to the SubscriberCheck easily.

Next, define a protocol which will help the View layer to talk to the Model layer implementation.

The View layer of our application is concerned about what the user is going to request. At this layer, you shouldn't be concerned about "how" it is going to be done. Since it is all about SubscriberCheck, simple Subscriber protocol which defines a function to receive a phone number and provides a closure for the SubscriberCheck results should be sufficient.

Create a Swift file in the service group called SubscriberCheckService.swift. In this file, define the Subscriber protocol as the following:

protocol Subscriber {
    func check(phoneNumber: String,
               handler: @escaping (Result<SubscriberCheck, NetworkError>) -> Void)
}

Create a class called SubscriberCheckService in the existing SubscriberCheckService.swift file which implements the Subscriber protocol.

final class SubscriberCheckService: Subscriber {
    let path = "/subscriber-check"

    init(){
    }

    public func check(phoneNumber: String, handler: @escaping (Result<SubscriberCheck, NetworkError>) -> Void) {
     //Implement the workflow
    }
}

A variable called path is defined to hold the path for the development server endpoint to perform the necessary calls. The path is /subscriber-check for the local development server. The check(phoneNumber: ...) method will contain the logic for the workflow.

Implement the User Action

At this point, the UI is almost ready to execute the SubscriberCheck workflow. Let's first define a variable of Subscriber type in our ViewController and then implement the next(_ sender: Any) IBAction we previously created.

Add the following code to the ViewController.

var subscriberService: Subscriber!

override func viewDidLoad() {
    super.viewDidLoad()
    subscriberService = SubscriberCheckService()
}

This initialises subscriberService with a concrete implementation SubscriberCheckService which you defined in the previous section. SubscriberCheckService knows how to execute the workflow and all ViewController needs to do is to call check(phoneNumber: String, ..) method and control the UI state. It is time to implement the next(_ sender: Any). It looks as follows:

@IBAction func next(_ sender: Any) {

    guard let phoneNumber = phoneNumberTextField.text else {
        return
    }

    if !phoneNumber.isEmpty {
        // Ideally you should validated phone number against e164 spec
        // Without leading + or 0's
        // For example: {country_code}{number}, 447940448591
        // Remove double 00's
        var strippedPhoneNumber = phoneNumber.trimmingCharacters(in: .whitespacesAndNewlines)
        if let range = strippedPhoneNumber.range(of: "00") {
            strippedPhoneNumber.replaceSubrange(range, with: "")
        }

        controls(enabled: false)

        subscriberService.check(phoneNumber: strippedPhoneNumber) { [weak self] (checkResult) in

            DispatchQueue.main.async {
                switch checkResult {
                case .success(let subscriberCheck):
                    self?.configureCheckResults(match: subscriberCheck.match ?? false, noSimChange: subscriberCheck.no_sim_change ?? false)
                case .failure(let error):
                    print("\(error)")
                }
                self?.controls(enabled:true)
            }

        }
    }

}

The implementation of the next method first checks whether there is text in the phoneNumberTextField and whether it is empty or not.

Note that in a production code, you should validate the phone number against the E.164 specification. We are keeping it simple for the purposes of this tutorial by only removing 00 from the beginning of the phone number (if it exists) and trimming.

The second step is to disable parts of the user interface, show the activity indicator and let it spin when the user taps the Next button. The third step is to call the check(phoneNumber:) method of the subscriberService. The handler will provide a checkResult which is of type Result<SubscriberCheck,NetworkError>. Note that this closure will not be called in the main queue, therefore you need to wrap any code which accesses UIKit in a DispatchQueue.main.async.

If the workflow executes successfully then you can access the model details and reconfigure the UI. Note that the .success case doesn't necessarily mean that validation is successful, it is simply an indication that workflow executed without encountering any network errors.

In order to understand if you validated the phone number you need to inspect the .success payload which is of type SubscriberCheck. The following line will ensure that validation results are reflected in the UI:

self?.configureCheckResults(match: subscriberCheck.match ?? false, noSimChange: subscriberCheck.no_sim_change ?? false)

In any case, you restore the UI controls back to their original state with the following code so that the user can re-execute the workflow, if needed:

self?.controls(enabled:true)

Setup the Network and Define Endpoints

Your app may have its own ways for defining and access external service URLs, and these endpoints may be stored in configuration files such as a plist, or in your Swift code. In this tutorial, you store the development and production base URLs in a plist called TruIdService-Info.plist. These server endpoints proxy some of the requests through to the tru.ID API.

Create a group called util in the Project Navigator. Next, create the Property List:

File -> New -> File
Select Property List in the dialog
Click Next
Select where you want to store the file (default selected folder should be fine)
Type TruIdService-Info as the file name
Click Create

You should see this file created in the util group. Now, let's add two keys to this plist file; one for the development endpoints and one for the production endpoints. The values should be String type.

development_server_base_url
production_server_base_url

You must ensure to assign the correct value to the development_server_base_url in order to complete this tutorial and successfully run the app on your device. This value is the one you are provided from the Terminal when you set up and ran your development server at the beginning of this tutorial (e.g. https://{subdomain}.loca.lt). For production setup, you should implement your own backend and add this URL here in the production_server_base_url.

In order to read the plist, create a struct called AppConfiguration, which deals with loading the correct endpoint so you do not have to worry when you are implementing the use cases.

import Foundation

struct AppConfiguration {

    let defaultConfigurationName = "TruIdService-Info"
    var configuration: [String : Any]?

    mutating func loadServerConfiguration() {
        if  let path = Bundle.main.path(forResource: defaultConfigurationName, ofType: "plist"),
            let xml = FileManager.default.contents(atPath: path)
        {
            self.configuration = (try? PropertyListSerialization.propertyList(from: xml,
                                                                              options: .mutableContainersAndLeaves,
                                                                              format: nil)) as? [String : Any]
        }
    }

    func baseURL() -> String? {
        var key = "production_server_base_url"
        #if DEBUG
        key = "development_server_base_url"
        #endif
        return configuration?[key] as? String
    }

}

The AppConfiguration struct simply reaches into the main bundle and searches for a plist called TruIdService-Info. If found, it reads the plist as a dictionary and binds that to the configuration variable. This URL is provided to the clients of the struct via the baseURL() -> String? method.

Now, implement a class called SessionEndpoint within the existing service/SessionEndpoint.swift file. This is our implementation of simple network requests using URLSession. You can implement this protocol using URLSession, or with Alamofire. For the purposes of this tutorial, let's keep it simple and implement the protocol using URLSession.

final class SessionEndpoint: Endpoint {

    let baseURL: String
    private let session: URLSession

    init() {
        var configuration = AppConfiguration()
        configuration.loadServerConfiguration()
        baseURL = configuration.baseURL()!//Fail early so that you know there is something wrong
        session = SessionEndpoint.createSession()
    }

    private static func createSession() -> URLSession {

        let configuration = URLSessionConfiguration.ephemeral //you do not want OS to cache or persist
        configuration.allowsCellularAccess = true
        configuration.waitsForConnectivity = true
        configuration.networkServiceType = .responsiveData

        return URLSession(configuration: configuration)
    }

    // MARK: Protocol Implementation
    func makeRequest<U: Decodable>(urlRequest: URLRequest,
                     handler: @escaping (Result<U, NetworkError>) -> Void) {

        let task = session.dataTask(with: urlRequest) { (data, response, error) in

            if let error = error {
                handler(.failure(.connectionFailed(error.localizedDescription)))
                return
            }

            guard let httpResponse = response as? HTTPURLResponse,
                  (200...299).contains(httpResponse.statusCode) else {
                handler(.failure(.connectionFailed("HTTP not OK")))
                return
            }

            guard let data = data else {
                handler(.failure(.noData))
                return
            }

            print("Response: \(String(describing: String(data: data, encoding: .utf8)))")

            if let dataModel = try? JSONDecoder().decode(U.self, from: data) {
                    handler(.success(dataModel))
                return
            }
        }

        task.resume()
    }

    func createURLRequest(method: String, url: URL, payload:[String : String]?) -> URLRequest {

        var urlRequest = URLRequest(url: url)
        urlRequest.setValue("application/json; charset=utf-8", forHTTPHeaderField: "Content-Type")
        urlRequest.httpMethod = method

        if let payload = payload {
            let jsonData = try! JSONSerialization.data(withJSONObject: payload, options: .prettyPrinted)
            urlRequest.httpBody = jsonData
        }

        return urlRequest
    }
}

The init() method of the class loads a base URL from the AppConfiguration which you defined earlier. It returns a URL for either a development server or a production server, depending on the build scheme. The final line of the init() creates a URLSession using a private static method. Note that the createSession() method creates a session configuration which doesn't cache or persist network related information; it is ephemeral for additional security.

The rest of the file contains the Endpoint protocol implementation. The first method, makeRequest<>.., creates a data task using the URLRequest provided and initiates the call. When the response is received, the method calls the handler closure for success or failure cases. If data exists and there are no error scenarios, it attempts to decode the data to the model type provided.

The Result<> generic type refers to a model object and an Enum which provides error cases.

The createURLRequest(..) method receives three parameters; HTTP method name, the URL and an optional payload if the request is a POST request, for instance. The method returns a URLRequest object, which is then used by the makeRequest<>.. method during the execution of the workflow.

Implement the Workflow

Now that you have defined the user interface and network request/response mechanics, let's bridge the two and implement the business logic. It is time to talk about the SubscriberCheck workflow before you dive more into the coding.

The SubscriberCheck workflow has 3 steps:

Create a SubscriberCheck via the server. This will return a check_id and check_url.
Then request the check_url retrieved in step 1 using the tru.ID iOS SDK
As soon as check_url request returns, retrieve the SubscriberCheck results using the check_id retrieved in step 1

The following sequence diagram shows each step, including the server to tru.ID API interactions:

Let's implement the workflow in SubscriberCheckService using some helper methods and the classes you created in the previous sections.

First, let's add a variable called endpoint to the SubscriberCheckService and initiate it in the init() method. The SubscriberCheckService class uses a concrete implementation of Endpoint protocol called SessionEndpoint which you defined in the previous sections. This class makes it easier to execute network calls.

final class SubscriberCheckService: Subscriber {
    let path = "/subscriber-check"
    let endpoint: Endpoint

    init(){
        self.endpoint = SessionEndpoint()
    }
    ...
}

Let's also define three methods, each corresponding to the steps mentioned above. Later, we will stitch the steps of the workflow in check(phoneNumber: ...) method.

The first method is createSubscriberCheck(phoneNumber:...). It makes a POST request to the server to create a SubscriberCheck. This call can be made over any type of network (cellular/wifi). The server should return a SubscriberCheck check_url.

Add the following method to the SubscriberCheckService class:

private func createSubscriberCheck(phoneNumber: String,
                                     handler: @escaping (Result<SubscriberCheck, NetworkError>) -> Void) {
    let urlString = endpoint.baseURL + path

    guard let url = URL(string: urlString) else {
        handler(.failure(.invalidURL))
        return
    }

    let phoneNumberDict = ["phone_number" : phoneNumber]
    let urlRequest = endpoint.createURLRequest(method: "POST", url: url, payload: phoneNumberDict)
    endpoint.makeRequest(urlRequest: urlRequest, handler: handler)
}

This method receives a phone number, constructs the full URL using the endpoint.baseURL and the SubscriberCheck path which is defined by the server. It creates a payload (just the phone number), and a URLRequest using the endpoint.createURLRequest(..) method. Then the method uses the makeRequest(..) method of the endpoint and passes the urlRequest and the handler.

Our next method is called retrieveSubscriberCheck(..). Add it to the SubscriberCheckService class:

private func retrieveSubscriberCheck(checkId: String,
                                     handler: @escaping (Result<SubscriberCheck, NetworkError>) -> Void) {

    let urlString = endpoint.baseURL + path + "/" + checkId

    guard let url = URL(string: urlString) else {
        handler(.failure(.invalidURL))
        return
    }

    let urlRequest = endpoint.createURLRequest(method: "GET", url: url, payload: nil)

    endpoint.makeRequest(urlRequest: urlRequest, handler: handler)
}

This is very similar to the first method you defined, with a few differences. You are now calling the endpoint with an extra checkId parameter, and this time it is a GET call. This method will get the results of the check performed.

The third method we need to create is doing the heavy lifting using the tru.ID SDK. Let's create a method called requestSubscriberCheckURL(..):

private func requestSubscriberCheckURL(subscriberCheckURL: String,
                                       handler: @escaping () -> Void) {

}

This method requests the check_url which will be returned by the createSubscriberCheck(..). In order to do that you need the tru.Id iOS SDK. Let's add it to our project.

The tru.ID iOS SDK ensures that certain network calls are done on a Cellular network type, which is needed to run SubscriberCheck workflow. You have two options to add the SDK to your project.

Using Swift Package Manager

Xcode integrates well with Github, and you can add Swift Packages very easily. In your Xcode, go to File -> Swift Packages -> Add Package Dependency...

Type https://github.com/tru-ID/tru-sdk-ios.git, and tap Next.

Xcode will find the package, select the latest version and then tap Finish to add it. Now that the SDK is added, you can import it when you are implementing the workflow.

Using CocoaPods

While we recommend using Swift Package Manager, tru.ID iOS SDK also supports adding your dependencies via CocoaPods. If you are familiar with CocoaPods and prefer using it, all you need to do is to create a Podfile and add the tru.ID pod the following way:

target 'MyApp' do
  pod 'tru-sdk-ios'
end

Make sure to run pod install in your project directory. After the CocoaPods install all necessary pods, and configure your project, don't forget to open the workspace rather than the project file.

Request the check_url

Let's go back to the SubscriberCheckService and import the TruSDK:

import TruSDK

Then use the SDK within requestSubscriberCheckURL(..) to request the check_url:

private func requestSubscriberCheckURL(subscriberCheckURL: String,
                                       handler: @escaping () -> Void) {

    let tru = TruSDK()

    tru.openCheckUrl(url: subscriberCheckURL) { (something) in
        handler()
    }
}

It's that simple.

As discussed, the SDK will ensure that this call will be made over the cellular network. When the openCheckUrl(..) calls the closure, you call the handler as well.

You are yet to implement the SubscriberCheckService check(phoneNumber:...) method, and chain the methods in our check(phoneNumber: String.. method. So, let's do that:

public func check(phoneNumber: String, handler: @escaping (Result<SubscriberCheck, NetworkError>) -> Void) {

    createSubscriberCheck(phoneNumber: phoneNumber) { (createResult) in
        var checkURL = ""
        var checkID = ""

        switch createResult {
        case .success(let subscriberCheck):
            // The server returns the SubscriberCheck results to the device.
            checkURL = subscriberCheck.check_url!
            checkID = subscriberCheck.check_id!
            print("Got the subscriber check URL: \(String(describing: subscriberCheck.check_url)) ")
        case .failure(let error):
            handler(.failure(error))
            return
        }

        print("Using the SDK to request check URL over mobile network")
        self.requestSubscriberCheckURL(subscriberCheckURL: checkURL) { [weak self] in

            guard let self = self else {
                return
            }

            print("SDK successfully returned, let's call our server to retrieve check results.")
            self.retrieveSubscriberCheck(checkId: checkID) { (checkResult) in
                switch checkResult {
                case .success(let checkResultModel):
                    handler(.success(checkResultModel))
                case .failure(let error):
                    handler(.failure(error))
                }

            }
        }
    }

}

First, you make a call using the createSubscriberCheck(phoneNumber: phoneNumber) ... method. The callback to this method inspects the Result<>. If it is a success, it fetches the checkURL and checkID and stores them in local variables which will be used later.

Within the callback you execute the second step using requestSubscriberCheckURL(...). This method uses the tru.ID iOS SDK and makes a call to check_url. The SDK makes this call over the cellular network, so the user must have a data plan. Behind the scenes, this call will redirect and eventually return OK. All this will be handled by the SDK.

The third step is to make a final request to the server using the checkID that you've got as a result of making the first call. This call will return the SubscriberCheck result; whether the check is successful or not.

Perform your first SubscriberCheck

Now that our code is complete, you can run the application on a real device. Bear in mind that SIM card based authentication is not possible on a Simulator, as you require a SIM Card with an active data connection.

You've now integrated SubscriberCheck into an iOS application, enabling you to both verify a phone number and check if the SIM card associated with the phone number has changed recently. All powered by SIM card based mobile authentication.

Where next?

The completed sample app can be found in the tru.ID sim-card-auth-ios Github repository.
Take a look at the tru.ID iOS SDK on GitHub

Troubleshooting

If you have any questions please raise an issue on the GitHub repo.

Mobile Data is Required

Don't forget that the SubscriberCheck validation requires your mobile device to have a data plan from your network operator, and that you should enable mobile data.

Get in touch

If you have any questions, get in touch via help@tru.id. Or throw me a message on Twitter

SIM Card Based Mobile Authentication with Android

Greg Holmes — Thu, 14 Oct 2021 08:47:48 +0000

Validating user identity is incredibly important in mobile applications. The most common approaches to this are social login or, as seen with apps such as WhatsApp, Telegram, Line, WeChat and many more, the mobile phone number. Using a mobile phone number as a unique identifier on a mobile application, verified via an SMS PIN code, makes logical sense. Unfortunately, there are flaws with SMS-based verification that result in poor UX such as long waits, failed delivery, and the risk of SIM Swap attacks.

The solution? Authentication based on the SIM card, which can confirm the ownership of a mobile phone number by verifying the possession of an active SIM with the same number. It also indicates when the SIM card associated with a phone number was last changed as a signal for SIM swap detection.

Along with adding cryptographically secure phone verification to an application and protecting the user from SIM swap attacks, SIM card based authentication improves the user experience. No more one-time code exchange, custom logic to handle mistyped PINS, or retries due to SMS delivery failure. The user never leaves the app and the entire verification happens seamlessly.

Fewer dependencies, better security and a better experience.

In this tutorial we'll cover how to add SIM card based phone authentication to and Android application using tru.ID SubscriberCheck.

The completed Android sample app in the sim-card-auth-android repo on GitHub. The repo includes a README with documentation for running and exploring the code.

Let's run through building this application step by step.

Before you Begin

To complete this tutorial you'll need an up to date version of Android Studio installed, some basic knowledge of Kotlin programming and Node.js installed. You'll also need a physical Android device with an active SIM card because SubscriberCheck verifies a phone number by making a web request over a mobile data session.

Get Setup with tru.ID

npm install -g @tru_id/cli

Run tru setup:credentials using the credentials from the tru.ID console:

tru setup:credentials {YOUR_CLIENT_ID} {YOUR_CLIENT_SECRET}

Install the CLI development server plugin:

tru plugins:install @tru_id/cli-plugin-dev-server@canary

Create a new tru.ID project:

tru projects:create AuthDemo

This will save a tru.json tru.ID project configuration to ./authdemo/tru.json.

Run the development server, pointing it to the directly containing the newly created project configuration. This will also open up a localtunnel to your development server, making it publicly accessible to the Internet so that your mobile phone can access it when only connected to mobile data.

tru server -t --project-dir ./authdemo

Open up the URL that is shown in the terminal, which will be in the format https://{subdomain}.loca.lt, in your desktop web browser to check that it is accessible.

With the development server setup we can move on to building the Android application.

Creating a New Android Project

First, you have to create a new Android application using Android Studio. The app name is "SIMAuthentication". The package name is id.tru.authentication.demo.
Click through the wizard, ensuring that "Empty Activity" is selected. Leave the "Activity Name" set to MainActivity, and leave the "Layout Name" set to activity_main.

The tru-sdk-android is available on Android devices with minimum Android SDK Version 21 (Lollipop), therefore select minSdkVersion = 21 once creating the project.

Phone Number Authentication UI

The first screen will be our Verification screen on which the user has to enter their phone number. After adding their phone number, the user will click on a "Verify my phone number" button to initiate the verification worflow.

The user interface is straight forward: a ConstraintLayout with one TextInputEditText phone_number inside a TextInputLayout input_layout for phone number input and a Button to trigger the verification, followed by a progress_bar where the user is updated on the progress, as we will see later on. Update activity_main.xml with the following:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MainActivity"
    android:paddingLeft="36dp"
    android:paddingTop="220dp"
    android:paddingRight="36dp">


    <TextView
        android:id="@+id/sign_in_header"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:text="To experience tru.ID verification, please enter your phone number"
        android:textStyle="bold"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent" />

    <com.google.android.material.textfield.TextInputLayout
        android:id="@+id/input_layout"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:errorEnabled="true"
        app:counterEnabled="true"
        app:counterMaxLength="13"
        android:layout_marginTop="20dp"
        style="@style/Widget.MaterialComponents.TextInputLayout.OutlinedBox"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/sign_in_header">

        <com.google.android.material.textfield.TextInputEditText
            android:id="@+id/phone_number"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:gravity="top|center"
            android:hint="Phone number"
            android:inputType="phone"
            android:imeOptions="actionDone"
            app:layout_constraintEnd_toEndOf="parent"
            app:layout_constraintStart_toStartOf="parent"
            app:layout_constraintTop_toBottomOf="@+id/textView" />
    </com.google.android.material.textfield.TextInputLayout>

    <Button
        android:id="@+id/verify"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:layout_marginTop="20dp"
        android:background="#6200EE"
        android:text="Verify my phone number"
        android:textAllCaps="false"
        android:textColor="@android:color/white"
        android:enabled="false"
        app:layout_constraintBottom_toBottomOf="@+id/input_layout"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="@+id/progress_bar"
        app:layout_constraintVertical_bias="0.698" />

    <com.google.android.material.progressindicator.LinearProgressIndicator
        android:id="@+id/progress_bar"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:indeterminate="true"
        android:visibility="invisible"
        android:layout_marginTop="100dp"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toBottomOf="@+id/verify"/>

</androidx.constraintlayout.widget.ConstraintLayout>

Make sure to update the dependencies for ConstraintLayout and Material Components with the latest available versions with app/build.gradle:

implementation 'com.google.android.material:material:1.3.0'
implementation 'androidx.constraintlayout:constraintlayout:2.0.4'

The main screen will look like this:

To enable view binding that allows you to more easily write code that interacts with views set the viewBinding build option to true in the app/build.gradle file and :

android {
    buildFeatures {
        viewBinding true
    }
}

Bind the verification workflow to the verify button within app/src/main/java/id/tru/authentication/demo/MainActivity.kt:

class MainActivity : AppCompatActivity() {

    private var _binding: ActivityMainBinding? = null
    private val binding get() = _binding!!

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        _binding = ActivityMainBinding.inflate(layoutInflater)
        setContentView(binding.root)

        binding.verify.setOnClickListener {
            initVerification()
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        _binding = null
    }

    private fun initVerification() {
        Log.d(TAG, "Verify button clicked")
    }

    companion object {
        private const val TAG = "MainActivity"
    }
}

Each time a verification is started we invalidate the UI, making sure all fields are reset, in order to cater for subsequent verification attempts:

    /** Called when the user taps the verify button */
    private fun initVerification() {
        Log.d(TAG, "phoneNumber " + binding.phoneNumber.text)
        // close virtual keyboard when sign in starts
        binding.phoneNumber.onEditorAction(EditorInfo.IME_ACTION_DONE)

        invalidateVerificationUI(false)
    }

    private fun invalidateVerificationUI(isEnabled: Boolean) {
        if (isEnabled) {
            binding.progressBar.hide()
            binding.phoneNumber.setText("")
        } else {
            binding.progressBar.show()
        }
        binding.verify.isEnabled = isEnabled
        binding.phoneNumber.isEnabled = isEnabled
    }

Now, let's proceed to initiate a SubscriberCheck workflow, as described in the next section.

SubscriberCheck Workflow

The sequence diagram below shows the complete SubscriberCheck Workflow. For this tutorial we'll focus on the Device and Device -> Server logic.

Create a app/tru-id.properties file and set the value of EXAMPLE_SERVER_BASE_URL to be the public URL of your development server:

EXAMPLE_SERVER_BASE_URL="https://{subdomain}.loca.lt"

To perform network operations in your application such as making requests to the verification server, your AndroidManifest.xml must include android.permission.INTERNET and android.permission.ACCESS_NETWORK_STATE permissions. Also, some mobile network operator check requests are over HTTP (and not HTTPS) so the application must also allow cleartext network traffic. Note that no data is sent over the HTTP request. The request is used by the MNO to verify that the device is connected to their mobile data network.

Your AndroidManifest.xml will look as follows:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="id.tru.authentication.demo">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <application
        android:usesCleartextTraffic="true"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.MaterialComponents.Light.NoActionBar">

        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

Both the Internet and ACCESS_NETWORK_STATE permissions are normal permissions, which means they're granted at install time and don't need to be requested at runtime.

In order to communicate with our local server the app needs to read in the app/tru-id.properties file containing the server URL and set a build configuration field. We want to include Retrofit, relevant JSON converters and OkHttp. Finally, include kotlinx-coroutine:

Update app/build.gradle with the following additions:

def props = new Properties()
file("tru-id.properties").withInputStream { props.load(it) }

android {
    defaultConfig {
        buildConfigField("String", "SERVER_BASE_URL", props.getProperty("EXAMPLE_SERVER_BASE_URL"))
    }

    dependencies {
        implementation 'com.squareup.retrofit2:retrofit:2.9.0'
        implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
        implementation 'com.squareup.okhttp3:okhttp:4.9.0'
        implementation 'com.squareup.okhttp3:logging-interceptor:4.9.0'
        implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.7'
        implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.0'
    }
}

1. Create a SubscriberCheck

To start the phone number verification flow in an Android app, the user enters their phone number and either presses the done keyboard key or touch the "Verify my phone number" button. The application then sends the phone number to your verification server that will create a SubscriberCheck resource on the tru.ID platform.

So, in order to create a SubscriberCheck a phone_number is required, and once created, the SubscriberCheck will contain a check_url and a check_id.

Let's create these required models for our network operations in a new file data/Model.kt:

data class SubscriberCheckPost(
    @SerializedName("phone_number")
    val phone_number: String
)

data class SubscriberCheck(
    @SerializedName("check_url")
    val check_url: String,
    @SerializedName("check_id")
    val check_id: String
)

Next, create an ApiService interface in api/ApiService.kt that makes use of the models, making a POST request to the /subscriber-check endpoint on the development server:

interface ApiService {
    @Headers("Content-Type: application/json")
    @POST("/subscriber-check")
    suspend fun createSubscriberCheck(@Body user: SubscriberCheckPost): Response<SubscriberCheck>
}

Create a new file, api/RetrofitBuilder.kt, and within it create a Retrofit instance using Retrofit.Builder, passing the ApiService interface to generate an implementation.

We are also adding the HttpLoggingInterceptor so we can check what is going on every step of the way.

object RetrofitBuilder {
    val apiClient: ApiService by lazy {

        val httpLoggingInterceptor = HttpLoggingInterceptor()
        httpLoggingInterceptor.setLevel(HttpLoggingInterceptor.Level.BODY);

        val okHttpClient = OkHttpClient()
            .newBuilder()
            //httpLogging interceptor for logging network requests
            .addInterceptor(httpLoggingInterceptor)
            .build()

        Retrofit.Builder()
            .baseUrl(BuildConfig.SERVER_BASE_URL)
            .client(okHttpClient)
            .addConverterFactory(GsonConverterFactory.create())
            .build()
            .create(ApiService::class.java)
    }
}

Note that the BuildConfig.SERVER_BASE_URL will be set with the value of EXAMPLE_SERVER_BASE_URL you defined in tru-id.properties.

Now we are ready to inform the user the verification process has started and create the SubscriberCheck using the provided phone number within MainActivity.kt:

    /** Called when the user taps the verify button */
    private fun initVerification() {
        Log.d(TAG, "phoneNumber " + binding.phoneNumber.text)
        // close virtual keyboard when sign in starts
        binding.phoneNumber.onEditorAction(EditorInfo.IME_ACTION_DONE)

        invalidateVerificationUI(false)
        createSubscriberCheck()
    }

    private fun createSubscriberCheck() {
        CoroutineScope(Dispatchers.IO).launch {

            val subscriberCheck = RetrofitBuilder.apiClient.createSubscriberCheck(
                SubscriberCheckPost(binding.phoneNumber.text.toString())
            )
        }
    }

2. Use the tru.ID SDK to Request the SubscriberCheck URL

At this point you're going to add the tru-sdk-android SDK to your project to enable the SubscriberCheck URL to be requested over a mobile data connection.

Edit the build.gradle at your project's root and add the following code snippet to the allprojects/repositories section:

allprojects {
    repositories {
        google()
        jcenter()
        maven {
            url "https://gitlab.com/api/v4/projects/22035475/packages/maven"
        }
        maven { url 'https://jitpack.io' }
    }
}

Add the SDK dependency to app/build.gradle and sync the project.

implementation 'id.tru.sdk:tru-sdk-android:0.0.+'

Initialize the TruSDK within onCreate in MainActivity.kt:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    TruSDK.initializeSdk(applicationContext)

    _binding = ActivityMainBinding.inflate(layoutInflater)
    setContentView(binding.root)

    binding.verify.setOnClickListener {
        initVerification()
    }
}

Create api/RedirectManager.kt to encapsulate obtaining a TruSDK instance and performing the network request with SubscriberCheck URL over the mobile data connection.

class RedirectManager {
    private val truSdk = TruSDK.getInstance()

    fun openCheckUrl(checkUrl: String) {
        truSdk.openCheckUrl(checkUrl)
    }
}

Update the createSubscriberCheck function in MainActivity.kt to use the RedirectManager to request the SubscriberCheck URL from the previous step. This enables the mobile network operator and the tru.ID platform to verify the phone number is associated with the mobile data session.

    private val redirectManager by lazy { RedirectManager() }

    private fun createSubscriberCheck() {
        CoroutineScope(Dispatchers.IO).launch {
            val response = RetrofitBuilder.apiClient.createSubscriberCheck(
                SubscriberCheckPost(binding.phoneNumber.text.toString())
            )

            if (response.isSuccessful && response.body() != null) {
                val subscriberCheck = response.body() as SubscriberCheck
                openCheckURL(subscriberCheck)
            }
            else {
                updateUIonError("Error Occurred: ${response.message()}")
            }
        }
    }

    private fun openCheckURL(check: SubscriberCheck) {
        CoroutineScope(Dispatchers.IO).launch {
            redirectManager.openCheckUrl(check.check_url)
        }
    }

    private suspend fun updateUIonError(additionalInfo: String) {
        Log.e(TAG, additionalInfo)
        withContext(Dispatchers.Main) {
            invalidateVerificationUI(true)
        }
    }

3. Get the SubscriberCheck Results

Once the SubscriberCheck URL has been requested the tru.ID platform now knows the check request has been performed. Your mobile application should query the result via your server application. This will in turn trigger the tru.ID platform to fetch the SubscriberCheck match result from the MNO (Mobile Network Operator).

Add the SubscriberCheckResult model to Model.kt:

data class SubscriberCheckResult(
    @SerializedName("match")
    val match: Boolean,
    @SerializedName("check_id")
    val check_id: String,
    @SerializedName("no_sim_change")
    val no_sim_change: Boolean
)

Add a getSubscriberCheckResult function to the ApiService interface:

interface ApiService {
    @Headers("Content-Type: application/json")
    @POST("/subscriber-check")
    suspend fun createSubscriberCheck(@Body user: SubscriberCheckPost): Response<SubscriberCheck>

    @GET("/subscriber-check/{check_id}")
    suspend fun getSubscriberCheckResult(@Path("check_id") checkId: String): Response<SubscriberCheckResult>
}

Now it's time to find out if the phone number was verified successfully. Create a new getSubscriberCheckResult function in MainActivity.kt and call it after the redirectManager.openCheckUrl. The call to getSubscriberCheckResult must be done within the coroutine to ensure the check URL request has completed.

    private fun openCheckURL(check: SubscriberCheck) {
        CoroutineScope(Dispatchers.IO).launch {
            redirectManager.openCheckUrl(check.check_url)

            getSubscriberCheckResult(check)
        }
    }

    private fun getSubscriberCheckResult(check: SubscriberCheck) {
        CoroutineScope(Dispatchers.IO).launch {
            val response = RetrofitBuilder.apiClient.getSubscriberCheckResult(check.check_id)
            if(response.isSuccessful && response.body() != null) {
                val subscriberCheckResult = response.body() as SubscriberCheckResult

                updateUI(subscriberCheckResult)
            }
        }
    }

    private suspend fun updateUI(subscriberCheckResult: SubscriberCheckResult) {
        Log.d(TAG, "TODO: update the UI")
    }

There you go, based on the subscriberCheckResult you may notify the user that the authentication has completed.

    private suspend fun updateUI(subscriberCheckResult: SubscriberCheckResult) {
        withContext(Dispatchers.Main) {
            if (subscriberCheckResult.match && subscriberCheckResult.no_sim_change) {
                Snackbar.make(binding.container, "Phone verification complete", Snackbar.LENGTH_LONG).show()
            } else {
                Snackbar.make(binding.container, "Phone verification failed", Snackbar.LENGTH_LONG).show()
            }

            invalidateVerificationUI(true)
        }
    }

The value of no_sim_change indicates if the SIM card has not been changed in the last 7 days. For example, in the case of match = true but no_sim_change = false the phone number has been verified but the fact the SIM card has changed recently means that it's good practice to perform additional user checks before allowing them to register or login.

In an application that contains more than a login or signup activity you would now show either a screen to capture more user information or the successfully registered/logged-in screen.

Try Out SIM Card Based Authentication

Now that your code is complete, you can run the application on a real device. Bear in mind that SIM card based authentication is not be possible against an emulator.

Enter the phone number for the mobile device in the UI in the format +{country_code}{number} e.g. +447900123456.

Touch the "Verify my phone number" button.

Congratulations! You've finished the SIM Card Based Mobile Authentication for Android Tutorial.

Where next?

You can view a completed version of this sample app in the sim-card-auth-android repo on GitHub.

Optional step: Client side phone number pre-validation

The minimum phone number pre-validation that can be achieved on the client side is to validate the phone number format with libphonenumber.

Update app/build.gradle to include this library:

implementation 'com.googlecode.libphonenumber:libphonenumber:8.12.10'

And create a util/PhoneNumberUtil.kt utility that validates the phone number format +{country_code}{number} e.g. +447900123456

fun isPhoneNumberFormatValid(phoneNumber: String): Boolean {
    val phoneNumberUtil = PhoneNumberUtil.getInstance()
    return try {
        phoneNumberUtil.isValidNumber(phoneNumberUtil.parse(
                phoneNumber, Phonenumber.PhoneNumber.CountryCodeSource.UNSPECIFIED.name))
    } catch (e: NumberParseException) {
        false
    }
}

Now invoke the phone number pre-validation on createSubscriberCheck:

private fun createSubscriberCheck() {
    if (!isPhoneNumberFormatValid(binding.phoneNumber.text.toString())) {
        invalidateVerificationUI(true)
        Snackbar.make(binding.container, "Phone number invalid", Snackbar.LENGTH_LONG).show()
        return
    }

Optional step: check if mobile data is enabled at runtime

The SubscriberCheck validation requires the device to have mobile data enabled. We can programmatically check if this is the case and launch Internet Connectivity settings dialog if required.

Firstly, add a utility method isMobileDataEnabled to your MainActivity.kt to check if the mobile data is enabled:

    @RequiresApi(Build.VERSION_CODES.O)
    private fun isMobileDataEnabled(): Boolean {
        val tm = getSystemService(TELEPHONY_SERVICE) as TelephonyManager
        return tm.isDataEnabled
    }

The Activity Result APIs provide components for registering for a result, launching the result, and handling the result once it is dispatched by the system.

To get started, add the dependencies:

implementation 'androidx.activity:activity-ktx:1.2.0'
implementation 'androidx.fragment:fragment-ktx:1.3.0'

The next step is to create a custom result contract data/ConnectivitySettingsContract.kt, this class would extend ActivityResultContract which requires defining input and output classes.

class ConnectivitySettingsContract : ActivityResultContract<Int, Uri?>() {
    @RequiresApi(Build.VERSION_CODES.Q)
    override fun createIntent(context: Context, input: Int) = Intent(Settings.Panel.ACTION_INTERNET_CONNECTIVITY)

    override fun parseResult(resultCode: Int, result: Intent?): Uri? {
        println("Result code $resultCode")

        if (resultCode != Activity.RESULT_OK) {
            return null
        }

        return result?.data
    }
}

Next, we register a callback for an activity result, we do that by defining registerForActivityResult() which takes the ConnectivitySettingsContract and ActivityResultCallback and returns an ActivityResultLauncher which is used to launch the other activity:

    private val startSettingsForResult = registerForActivityResult(ConnectivitySettingsContract()) {
        Log.i(TAG, "Internet Connectivity Setting dismissed")
        initVerification()
    }

If the mobile data is disabled we launch the previously created ActivityResultLauncher, as follows:

    private fun initVerification() {
        Log.d(TAG, "phoneNumber " + binding.phoneNumber.text)
        // close virtual keyboard when sign in starts
        binding.phoneNumber.onEditorAction(EditorInfo.IME_ACTION_DONE)

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            if (!isMobileDataEnabled()) {
                startSettingsForResult.launch(CONNECTIVITY_SETTINGS_ACTION)
                return
            }
        }
        startVerification()
    }

    companion object {
        private const val TAG = "MainActivity"
        const val CONNECTIVITY_SETTINGS_ACTION = 1
    }

Programmatically reading the device Phone Number

If you're trying to create a even more magical phone number verification experience, you can make the phone number input part of the app's responsibility.

One option is to use Play Services auth-api-phone library hint picker that prompts the user to choose from the phone numbers stored on the device and thereby avoid having to manually type a phone number.

Troubleshooting

Mobile Data is Required

Don't forget the SubscriberCheck validation requires the device to enable mobile data.

Check the HTTP Logging Output

Because we have attached a HttpLoggingInterceptor you can use adb logs to debug your SubscriberCheck:

I/okhttp.OkHttpClient: --> POST https://mylocalserver.example/subscriber-check
I/okhttp.OkHttpClient: {"phone_number":"+447XXXXXXXXX"}
I/okhttp.OkHttpClient: --> END POST (32-byte body)
I/okhttp.OkHttpClient: <-- 200 https://mylocalserver.example/check (1479ms)
I/okhttp.OkHttpClient: {"check_id":"NEW_CHECK_ID","check_url":"https://eu.api.tru.id/subscriber_check/v0.1/checks/NEW_CHECK_ID/redirect"}
I/okhttp.OkHttpClient: <-- END HTTP (157-byte body)

D/RedirectManager: Triggering open check url https://eu.api.tru.id/subscriber_check/v0.1/checks/NEW_CHECK_ID/redirect
I/SDK::checkUrl: Triggering check url
I/System.out: Response to https://eu.api.tru.id/subscriber_check/v0.1/checks/NEW_CHECK_ID/redirect
D/LoginActivity: redirect done [7961ms]
I/okhttp.OkHttpClient: --> GET https://mylocalserver.example/subscriber-check/NEW_CHECK_ID
I/okhttp.OkHttpClient: --> END GET
I/okhttp.OkHttpClient: <-- 200 https://mylocalserver.example/subscriber-check/NEW_CHECK_ID (749ms)
I/okhttp.OkHttpClient: {"match":true,"check_id":"NEW_CHECK_ID","no_sim_change":true}
I/okhttp.OkHttpClient: <-- END HTTP (64-byte body)

Check the Development Server Logging

The development server also logs information out to the terminal including request and response payloads. Check that output for any errors or unexpected values.

Get in touch

If you have any questions, get in touch via help@tru.id.

Passwordless Mobile Authentication with Android

Greg Holmes — Fri, 27 Aug 2021 13:27:38 +0000

Before we begin, let's discuss why you would want to use tru.ID PhoneCheck in your onboarding workflows.

20-30% of signup attempts fail on mobile due to incomplete authentication; an SMS is delayed or not delivered at all, an email ends up in spam or is undelivered, a voice call fails, or the user makes a mistake as they navigate the poor UX of a signup flow which uses current legacy authentication options. tru.ID PhoneCheck offers a new way to verify a user, reducing UX friction and improving onboarding conversion rates.

It works by confirming the ownership of a mobile phone number by verifying the possession of an active SIM card with the same number. A mobile data session is created to a unique Check URL for the purpose of this verification. tru.ID then resolves a match between the phone number being verified and the phone number that the mobile network operator identifies as the owner of the mobile data session.

If you just want to dive into the finished code for this tutorial, you can find it on Github.

Before you begin

Before you begin you'll need the following:

Android capable IDE (Android Studio recommended)
An Android phone with mobile data connection
Node.js

Getting Started

Clone the starter-files branch via:

git clone -b starter-files --single-branch https://github.com/tru-ID/passwordless-auth-android.git

Create a tru.ID account and you'll end up on the Console containing CLI setup instructions.

Install the tru.ID CLI via:

npm i -g @tru_id/cli

Input your tru.ID credentials, which can be found within the tru.ID console.

Install the tru.ID CLI development plugin server.

Create a new tru.ID project within the root directory via:

cd passwordless-auth-android && tru projects:create --project-dir .

Run the development server, pointing it to the directory containing the newly created project configuration. This will also open up a localtunnel to your development server, making it publicly accessible to the Internet so that your mobile phone can access it when only connected to mobile data.

tru server -t --project-dir .

Starting the project

Open the project up in your Android capable IDE, connect your phone to your computer so it can be used for running the Android project, and run the application from your IDE.

The project should look like this:

The project's onboarding workflow includes four screens: splash, get started, sign up and signed up.

Click the Get Started button to navigate to the signupFragment UI. It looks like this:

Creating a PhoneCheck

The first step is to create the PhoneCheck. In order to do this, we need to send a POST request with the user's phone number to /phone-check.

We then get back a check_url and check_id which we will use for subsequent calls.

First, add the following dependencies for data fetching in app/build.gradle:

dependencies {
     // retrofit and converter
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
}

Next, create a folder (package) in src/main/java/com/example/tru_phonecheck called api and within that create a subfolder (package) called data.

Within data, create a class called PhoneCheck.kt and add the following code:

package com.example.tru_phonecheck.api.data

import com.google.gson.annotations.SerializedName

data class PhoneCheck(  @SerializedName("check_url")
                        val check_url: String,
                        @SerializedName("check_id")
                        val check_id: String) {
}

data class PhoneCheckPost (
    @SerializedName("phone_number")
    val phone_number: String
)

Here we have two data model classes: PhoneCheck, whose constructor accepts the values of the response, and PhoneCheckPost, whose constructor accepts the user's phone number.

We also use @SerializedName to ensure the values match the expected input / response.

Next, navigate back to the api folder and create another folder (package) named retrofit. Within it, create an interface named RetrofitService and replace its contents with the following:

package com.example.tru_phonecheck.api.retrofit

import com.example.tru_phonecheck.api.data.PhoneCheck
import com.example.tru_phonecheck.api.data.PhoneCheckPost
import retrofit2.Response
import retrofit2.http.*

interface RetrofitService {
    @Headers("Content-Type: application/json")
    @POST("/phone-check")
    suspend fun createPhoneCheck(@Body user: PhoneCheckPost): Response<PhoneCheck>
    companion object {
        // set up base_url in the format https://{subdomain}.loca.lt gotten from localTunnel URL
        const val base_url = "https://{subdomain}.loca.lt"
    }
}

Here we make use of the model we created to make the POST request. We also create a companion object, which allows us to access base_url as an object (i.e. RetrofitService.base_url).

Remember to swap out the placeholder URL in base_url with the localTunnel URL.

We now need to grab the user's phone number when the user touches the button and initiate the POST request.

First, head over to src/main/java/com/example/tru_phonecheck/fragments/onboarding/screens/signupFragment.kt and add a function that disables the UI when the button is touched:

  private fun setUIStatus (button: Button?, input: EditText, enabled: Boolean){
      activity?.runOnUiThread {
              button?.isClickable = enabled
              button?.isEnabled = enabled
              input.isEnabled = enabled
      }
  }

Next, add the following to create the Retrofit service:

//retrofit setup
private fun rf(): RetrofitService {
    return  Retrofit.Builder().baseUrl(RetrofitService.base_url).addConverterFactory(GsonConverterFactory.create()).build().create(RetrofitService::class.java)
}

Finally, add the following before return view in the onCreateView function:

...
view.submitHandler.setOnClickListener {
    // get phone number
    val phoneNumber = phoneNumberInput.text.toString()
    Log.d("phone number is", phoneNumber)

    // close virtual keyboard
    phoneNumberInput.onEditorAction(EditorInfo.IME_ACTION_DONE)

    // if it's a valid phone number begin createPhoneCheck
    if(!isPhoneNumberFormatValid(phoneNumber)) {
        Snackbar.make(container as View, "Invalid Phone Number", Snackbar.LENGTH_LONG).show()
    } else {
        println("valid number")

        // disable the UI
        setUIStatus(submitHandler, phoneNumberInput, false)

        CoroutineScope(Dispatchers.IO).launch {
          try {
              val response = rf().createPhoneCheck(PhoneCheckPost(phoneNumber))

              if(response.isSuccessful && response.body() != null){
                  val phoneCheck = response.body() as PhoneCheck

                  // open checkURL

                  // get PhoneCheck result
              }
          } catch(e: Throwable){
              Snackbar.make(container as View, e.message!!, Snackbar.LENGTH_SHORT).show()
          }

          // enable the UI
          setUIStatus(submitHandler, phoneNumberInput, true)
        }
    }
}

Here we attach a click listener to the button with the ID submitHandler. When the button is clicked, we grab the phone number and check if it is valid via a utility function located in src/main/java/com/example/tru_phonecheck/utils/PhoneNumberUtil.kt. If it is a valid number, we disable the UI via setUIStatus and make a network request to create the PhoneCheck using therf().createPhoneCheck function.

Opening the Check URL

The next stage is to open the Check URL returned to us. To do this, we need to use the tru.ID Android SDK. The SDK forces the Check URL network request to go over the mobile data connection so that the mobile network operator and tru.ID can verify the phone number.

Head back to build.gradle and add the following dependency:

dependencies {
  ...
    // tru.ID Android package
    implementation 'id.tru.sdk:tru-sdk-android:0.0.3'
}

Next, we need to initialize the SDK on startup. To do that, head over to MainActivity.kt and update it to the following:

package com.example.tru_phonecheck

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import id.tru.sdk.TruSDK

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {

        // initialize Tru SDK
        TruSDK.initializeSdk(applicationContext)

        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        supportActionBar?.hide()
    }
}

Head back to SignupFragment.kt and add the following above onCreateView:

private val truSDK = TruSDK.getInstance()

Use the SDK to open the Check URL in the setOnClickListener function:

if(response.isSuccessful && response.body() != null){
    val phoneCheck = response.body() as PhoneCheck

    // open checkURL
    truSDK.openCheckUrl(phoneCheck.check_url)

    // get PhoneCheck result
}

We have now successfully opened the Check URL.

Getting the PhoneCheck Response

The last thing we need to do is get the PhoneCheck response.

Head over to PhoneCheck.kt and update its contents:

package com.example.tru_phonecheck.api.data

import com.google.gson.annotations.SerializedName

data class PhoneCheck(  @SerializedName("check_url")
                        val check_url: String,
                        @SerializedName("check_id")
                        val check_id: String) {
}

data class PhoneCheckPost (
    @SerializedName("phone_number")
    val phone_number: String
)

data class PhoneCheckResponse(
    @SerializedName("check_id")
    val check_id: String,
    @SerializedName("match")
    val match: Boolean
)

We added a new model, PhoneCheckResponse, which contains two fields: check_id and match. The latter is used to verify the phone number.

Next, head over to RetrofitService.kt and update the code support getting the PhoneCheck resource:

@GET("/phone-check")
suspend fun getPhoneCheck(@Query("check_id") checkId: String): Response<PhoneCheckResponse>

Here we added a GET function to /phone-check?check_id={check_id} where we pass the check_id value dynamically when it is called.

We also map the model type PhoneCheckResponse to the Response object we're expecting.

Let's now head over to SignupFragment.kt and add the functionality to get the PhoneCheck result:

if(response.isSuccessful && response.body() != null){
    val phoneCheck = response.body() as PhoneCheck

    // open checkURL
    truSDK.openCheckUrl(phoneCheck.check_url)

    // get PhoneCheck result
    val response = rf().getPhoneCheck(phoneCheck.check_id)

    if(response.isSuccessful && response.body() != null){
        val phoneCheckResponse = response.body() as PhoneCheckResponse

        // update UI with phoneCheckResponse
        if(phoneCheckResponse.match){
            findNavController().navigate(R.id.action_signupFragment_to_signedUpFragment)

        } else {
            Snackbar.make(container as View, "Registration Failed", Snackbar.LENGTH_LONG).show()
        }
    }
    else {
        Snackbar.make(container as View, "An unexpected problem occurred", Snackbar.LENGTH_LONG).show()
    }
}

Finally, we get the result of the PhoneCheck using the phoneCheck.check_id we previously got with the PhoneCheck response. If the phone number has been verified, we navigate the user to the signedUpFragment view. If the verification failed (phoneCheckResponse.match is false) we render a "failure" toast.

The signedUpFragment UI looks as follows:

That's it!

Wrapping Up

With everything in place, we now have a seamless signup onboarding flow with minimal UX friction, resulting in no user drop-offs.

There you have it: you’ve successfully integrated tru.ID PhoneCheck into your Android onboarding workflow.

Announcing the tru.ID CLI

Phil Leggetter — Wed, 03 Mar 2021 01:55:09 +0000

As a developer-first and API-first company, we prioritise tools that will make you, the developer, successful. Today we're excited to announce the tru.ID CLI: built on top of our public APIs, open sourced, and your go-to developer tool when building on the tru.ID platform.

Why a CLI?

Many of us spend a lot of time in the terminal, so a CLI enables you to work from where you already are. IDEs such as Visual Studio Code and Android Studio come with in-built terminals. But having a CLI also allows us to build integrations into existing development workflows, via scripts, outside of the IDE. For example, Xcode behaviours or integration into CI/CD workflows.

Using Oclif & Open Source

The tru.ID CLI is built upon the excellent oclif open CLI framework by Heroku. Oclif provides a foundation for CLI functionality such as subcommands, command arguments and flags, plugin support and lots of utilities that enable us to focus on features instead of building our own CLI framework.

If you'd like to see how we've used Oclif the tru.ID CLI is on GitHub. Within the GitHub repo you'll find two branches:

main for the latest stable release
canary if you'd like to try out the latest features

We'd love to hear what you think so please ask questions, share ideas and raise PRs on the tru-ID/cli repo.

Install and Setup the tru.ID CLI

For the moment the only installation option is via NPM so you'll need Node.js installed.

With Node.js installed you install the tru.ID CLI as follows:

$ npm install -g @tru_id/cli

Or, if you prefer Yarn:

$ yarn global add @tru_id/cli

To try out the latest features use @tru_id/cli@canary.

With the tru command installed, setup the CLI with the credentials you'll find within the tru.ID console.

$ tru setup:credentials {client_id} {client_secret} eu

eu is the region where your account data is stored and, at the time of this blog post, is the only region we have available (more coming soon).

You can now query the credit you have available using:

$ tru workspaces

And the output will be similar to:

credentials.client_id                data_residency balance.amount_available balance.currency created_at
xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx EU             28                       API              2020-08-12T12:46:56+0000

Creating a tru.ID Project

Projects are configuration containers within the tru.ID platform and you'll normally have a one-to-one mapping of a tru.ID project to an application that you are developing (though you may also create a project per environment: dev, staging and prod). A key piece of configuration are the project credentials which contain a client_id and client_secret that you use to authenticate interactions with the tru.ID APIs.

You create projects using the CLI:

$ tru projects:create "My Awesome Project"

And you'll see output such as:

Creating Project "My Awesome Project"
Project configuration saved to "~/my_awesome_project/tru.json".

The tru.json file contains your project configuration including the project credentials. Don't check this into source control!

With a project created you can cd my_awesome_project so the CLI can read the tru.json file from the cwd and you have everything you need to fully utilise the tru.ID CLI.

Trying the tru.ID APIs

CLIs normally focus on platform management functionality, such as creating and managing projects, but we decided to also add commands to let you try out our products from the terminal. Of course, you can also try these out programmatically too.

SIMCheck

SIMCheck is an API that queries when the SIM card associated with a phone number last changed:

$ tru simchecks:create

With the output being similar to the following, which prompts for the phone number to be checked:

? Please enter the phone number you would like to SIMCheck +{phone_number}
Creating SIMCheck for +{phone_number}

    status: COMPLETED
    no_sim_change: true
    last_sim_change_at: 2017-01-26T07:16:57+0000

The no_sim_change value indicates that the SIM card hasn't changed within the last seven (7) days, and last_sim_change_at specifies the last change date (when I changed my mobile phone provider from giffgaff UK to EE UK).

PhoneCheck

PhoneCheck verifies that a phone number is associated with a SIM card within the mobile device. This is achieved via tru.ID's integration with MNOs (Mobile Network Operators) around the world. For a more in-depth look at how this works, check out the PhoneCheck integration guide. Of course, you can also try this out via our CLI:

$ tru phonechecks:create --workflow

The output of this command prompts for a phone number and also displays a QR code to scan on a mobile device. It also provides instructions to disable WiFi on the device, as part of the PhoneCheck workflow is to make a web request over the device's mobile data connection.

? Please enter the phone number you would like to PhoneCheck +{phone_number}
Creating PhoneCheck for +{phone_number}
PhoneCheck ACCEPTED
check_id: 76a36abb-8495-403a-9f71-531c80c6a26b
check_url: https://eu.api.tru.id/phone_check/v0.1/checks/76a36abb-8495-403a-9f71-531c80c6a26b/redirect
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █▄█  ██ ▄███ ▀▄▄ ▄▀█ ██ ▄  ▀██▀█▀▀  █  ▄ ██ ▄▄▄▄▄ █
█ █   █ █ ▄▀▄ █▄█▄█▀█████ ▄█ ██▄▄▄▄█▀▀█▀ █ ▀█▄▀▄ ██ █   █ █
█ █▄▄▄█ █▄ █▀  ▀▀▀   ▀▀  ▀█ ▄▄▄   ▄█▄▄   ▀ ▀▄▄▄▀▄██ █▄▄▄█ █
█▄▄▄▄▄▄▄█▄▀▄█▄█▄█▄█▄▀▄█▄█ ▀ █▄█ █▄█ ▀▄▀ ▀ ▀ ▀▄█ ▀▄█▄▄▄▄▄▄▄█
█    ▀▀▄▀▄▄▀▄▀▀█▄▄ ▀▄▄  ▀ ▄ ▄▄▄  ███ █▀██ ▀▀ ▀▀▄▄  ██ ▄▄▀▄█
███▀▄▀▄▄█▄ ▀   ▀██ ██▄▄▄▀ ▄▄██▀ █▄ ▀ ▀▀▄ ▄ ▀█ ▄  ▄████ █  █
█▀▄█ ▀▀▄█▀ ▄█▄▄ █▄█▄  █▄▄██ █▀▄▄ ▀ ▄▀▄   ▀▄▄▀▀ ▄▄█▄▀▄▀ █▄▄█
█▄██ ▄ ▄▄ ▄▀▀▀▀█ ▄▀██▄▄▀▀ ▄▄▄█ ▄▄ ██▄█ █▀ █ █ ▄█▀▀ ▄▀▀▀ █▀█
█▄▀▀▄██▄█▄▄▄  ▄▄▄ █▀██▄█ ▄ █▄█ ▄▄▄▄ ▀█▀▄▀▀▄▄▄▄▄  ▄ █ █▄██ █
█ ▀ ▄ ▀▄▄▀  █▄▀▀ ▄  ██▀█▀▄▀ ▄█ ▀██▀▄█▀▄ █▀▀█▀█▀  ▀▀▄▀▀▀█▀▀█
███ ▄▀ ▄ ▀  ▀▀ ██ ▄███  ▀ ▄▀▄ █▀██▄▄▀▀███ ▄ ▀▀ ▄▀ █▄█▄▀ █▀█
█▀▄ ▀██▄▀ █ ▀█ ▄▀▄ █ ▄  ▀███▄▄█▄█▄▄▄█▀▄▀█▀▀ ▄█  █▄▀▀█▄██▄ █
█▀▄██ ▄▄ ▄ █ ▀ ▄█▄   ▀█▀█▄ ▀█▀▀█▄▀ █▄▄ ▀███▄▄█ ██▄  ▀█▄█▄▄█
██▄▀  ▄▄▄ ▀▀ ▀█▀▀ ▄▄▄▀█▄█ ▄ ▄▄▄   █▄▀██▄▀▀█▄▄▀▄▄▀ ▄▄▄ ▀▀▀▀█
█ ▀ ▄ █▄█ ▀█▀ ▄▀▀ █▄██▀▀ █▀ █▄█ ▄▄ ▀█▀ ▄▄▀ ██▄▄▀▄ █▄█ ▀▄▀ █
██▀▀█ ▄▄  ██▄▄█▄ ▄█▀ ▀█ ▀█▄  ▄▄  ▄█▄▄ █  ▀▄▀██ ▄▄  ▄ ▄██ ▀█
█ ▄██ ▄▄ ███▀█▄█▄███ ▄    █▄▀█ █ ▀ ▄▀▀▄██▄▄▀█▀██▀█▀▄ █▀▄▄▀█
██▄   ▀▄█▀▄ ▄▀██▀  ▀ █▄▀ ▄▄█ ▀███ █ █  █▀▄█▄▄ █▄█▀█ ▄ ███▄█
█▄██▀ █▄█▄▄█ ▄█▀███ ▀██▀█▄█▄ ▄ ▄ ▀ █▀ █ ██▄▄█▀▀█▀▀▄▄▀█ ▀▀██
█▀▄█▄▄▄▄▄█  █ ██ ▄▀▄  ▄▀▀ ▀ ▄▄ █ ▀█▀ ▀█ █▄▀ ▀▀██▀ █▀▄█ ▀█▄█
█▀▄█ █▄▄▀ █▀▀ █▀  ▀▀██▄▀█▄▀▄▀▀▄██▄▀▀████ ▀ ██▄ ▀▄█▄▀▄ ▀██▄█
██  ▀▀▄▄▀ ▄ ▄██▄▀▀█▄▀ █ ▄▄▄     ▄█ ▄  ▀   █▄ ▄ ▀██ █ ██▄▄▀█
█▀▄▀▄█▀▄ ▀▀ █ ▄▀ █▀▀ ▄ █▄ ▄  █▀█▀▀ ▄████▀▄▀▀ ▀███▄ ▀██▄ ▄ █
█ ▀ ▀▀▄▄▄ ██▀▄▀   ▀█▀█ ▀▀█  ▄ ███▀▀▄▄▀ █▀▄█ ▄ █  █▀ ██▀▄  █
███████▄█▀▀▄ ▀▄█ ██ ▀ ▀██▄▀ ▄▄▄ ▀▀███▄  ▄█▀▄▀███▀ ▄▄▄ ▀▀ ██
█ ▄▄▄▄▄ ██ █ █▄█▀█  ▀ ███ ▄ █▄█ █▀▄▀█▀ ▄▄ ▄ ▄▀▄█▄ █▄█ █▀▄▀█
█ █   █ █▀ █▀▄ █▀█ ▀ ▄ █▀▄▀  ▄▄   ▀▀█▀██▄▀█▄▄▄█   ▄▄ ▄▀▄ ██
█ █▄▄▄█ █ █▄▄▄▀▀  ▄▄▄▀▄ ▀ ▀▀█▀██ ▄  ▀ █ ██▄██▄▀▄▀ █▀███▄█▀█
█▄▄▄▄▄▄▄█▄▄▄▄▄▄▄█▄▄██▄▄▄█████▄▄███▄▄▄██▄▄▄▄▄██▄▄▄██▄█▄▄▄███

Please ensure the mobile phone with the phone number +{phone_number} is disconnected from WiFi and is using your mobile data connection.

Then scan the QR code and navigate to the check_url.

Waiting for a PhoneCheck result... done

PhoneCheck Workflow result:
    status:  COMPLETED
    match:  true ✅

QR codes in the terminal. Pretty cool, huh!

As well as creating resources you can also query existing ones:

$ tru phonechecks:list 76a36abb-8495-403a-9f71-531c80c6a26b
check_id                             created_at               status    match charge_currency charge_amount
76a36abb-8495-403a-9f71-531c80c6a26b 2021-02-23T21:08:56+0000 COMPLETED true  API

You can also try out tru phonechecks:list with flags such as --search to add query conditions the API request, --filter to filter a result from the API, and --output to change the output format e.g. --output json.

SubscriberCheck

The CLI also supports SubscriberCheck, which runs a PhoneCheck but also includes a SIMCheck within the result. We'll leave trying that out to you, but here's the creation command that runs through the QR code workflow:

$ tru subscriberchecks:create --workflow

What Else Can the CLI Do?

Two other commands worth highlighting are oauth2 and coverage.

OAuth2

Our APIs use OAuth2 credentials and access tokens for authentication. But we know that sometimes you just want access to an access token without having to concatenate a project client_id and client_secret, Base 64 encode that value, make a request to the /token endpoint to create an access token, and then eventually getting to use it. So, the oauth2 command makes it a bit easier to create an access token when you're just trying things out.

Note: Running the following command from a directory that contains a tru.json project configuration file will use the credentials for the project. If you run the command without a tru.json in the cwd you'll use the credentials you supplied in the tru setup:credentials command.

$ tru oauth2:token

Then you just need to copy the access token and use it:

access_token
GXuXq1DKa2LdBikD0jC8DenJgJTdgPSONLC0TpYqIzQ.ko9hRxKojOYhSvWkUBsPtHNPSUtB5KMwCqw8_FjUW6c

You can also assign the output to a variable and use it either in a mobile client or to try things out via cURL:

$ TOKEN=$(tru oauth2:token --no-header)
$ curl -s -X GET \
-H "Authorization: Bearer $TOKEN" \
https://eu.api.tru.id/phone_check/v0.1/checks/76a36abb-8495-403a-9f71-531c80c6a26b
{"check_id":"76a36abb-8495-403a-9f71-531c80c6a26b","status":"COMPLETED","match":true,"charge_amount":1.00,"charge_currency":"API","created_at":"2021-02-23T21:08:56+0000","updated_at":"2021-02-23T21:09:26+0000","_links":{"self":{"href":"https://eu.api.tru.id/phone_check/v0.1/checks/76a36abb-8495-403a-9f71-531c80c6a26b"}}}%

Coverage

Coverage provides two endpoints and is thus a "topic" with two commands in the CLI.

coverage:country {country_code} allows you to query if the tru.ID platform has coverage for a given country. You can use either a phone number country code prefix:

$ tru coverage:country +44
product_name     network_id network_name currency amount
Phone Check      23410      O2 UK        API      1
Phone Check      23415      Vodafone UK  API      1
Phone Check      23420      3 UK         API      1
Phone Check      23430      EE UK        API      1
Sim Check        23410      O2 UK        API      1
Sim Check        23415      Vodafone UK  API      1
Sim Check        23420      3 UK         API      1
Sim Check        23430      EE UK        API      1
Subscriber Check 23410      O2 UK        API      1
Subscriber Check 23415      Vodafone UK  API      1
Subscriber Check 23420      3 UK         API      1
Subscriber Check 23430      EE UK        API      1

Or a two-letter alpha country code:

$ tru coverage:country CA
product_name network_id network_name currency amount
Phone Check  302220     Telus        API      1
Phone Check  302610     Bell         API      1
Phone Check  302720     Rogers       API      1

coverage:reach also performs a tru.ID platform coverage query but based on the IP address (IPv4 or IPv6) of the device:

$ tru coverage:reach 213.205.197.123
network_id network_name country_code supported_products
23430      EE UK        GB           Phone Check,Sim Check,Subscriber Check

Try out the CLI and let us know what you think

In this post we've covered a number of the main commands but there's more that the CLI offers. Either install the tru.ID CLI (npm install -g @tru_id/cli) and tru --help to find out more, or take a look at the CLI Reference docs to see what else is possible.

We believe the tru.ID CLI offers a good first developer experience of our platform. But we'd love to know what you think via feedback@tru.id.

If you haven't already, signup for a tru.ID account, follow @_tru_id on Twitter and join our mission to reimagine mobile authentication.