DEV Community: Greg Holmes

Build a Model Context Protocol (MCP) Server for Symfony

Greg Holmes — Thu, 30 Oct 2025 10:43:40 +0000

The Model Context Protocol (MCP) enables AI assistants to interact directly with your applications, but most examples focus on JavaScript/TypeScript. If you're a PHP developer using Symfony, you might be curious how to leverage MCP in your projects. This tutorial shows you exactly how. You'll build a complete MCP server that gives Claude and other AI assistants the ability to query your database, analyse customer data, and interact with your Symfony application through human language.

The outcome of this tutorial will add MCP server capabilities to a Symfony Customer Management application, allowing AI assistants like Claude to:

Search for customers by name, email, city, or county
Get detailed customer information with order history
Analyse order data and customer statistics
Query recent orders and products

Prerequisites

To follow this tutorial you'll need:

PHP 8.1+ installed,
Composer installed,
Git installed locally to clone the repository and checkout to the starter branch.

Get Started

The first step of this tutorial is to clone the Github repository and checkout to the starter branch. I've already built a Symfony application with some demo customer accounts, orders etc. So, first run the following commands to clone the repository and change directory into the application:

git clone git@github.com:GregHolmes/build-a-symfony-mcp-server-tutorial.git

cd build-a-symfony-mcp-server-tutorial

You should by default be checkedout to the starter branch, but if you're not, checkout to the starter branch. The starter branch contains the complete Symfony application without MCP:

git checkout starter

Install the dependencies with the single composer install command:

composer install

Let's make sure the starter branch is working as expected by starting up the server:

php -S localhost:8000 -t public

When you visit http://localhost:8000 you'll see:

100 UK customers with realistic data
Orders with status badges
Products organized by category

Below are two screenshots showing two of the pages you should expect to see when loading the page.

The first image shows the page displaying 100 customer records:

While the second shows a table of 100 order records by customers:

If you're interested in the data you're seeing, it's being fed from the SQLite database at var/data.db.

The Database Structure

Entities

The application has four main entities with relationships. This represents a data model in your application and maps to a database table:

Customer (src/Entity/Customer.php)

Properties: firstName, lastName, email, phone, address, city, state (county), zipCode
Relationships: Each customer can have many Orders.

Order (src/Entity/Order.php)

Properties: orderDate, status, total
Relationships: Each order belongs to a Customer and has many OrderItems.

OrderItem (src/Entity/OrderItem.php)

Properties: quantity, price
Relationships: Each OrderItem belongs to Order and Product

Product (src/Entity/Product.php)

Properties: name, description, price, category

Repositories

This tutorial has four custom query methods are available in repository classes:

CustomerRepository::findBySearchTerm() - Search customers
CustomerRepository::findByState() - Find customers by county
CustomerRepository::findTopSpenders() - Get top spending customers
OrderRepository::findRecentOrders() - Get recent orders

Install the Symfony MCP SDK

The Symfony MCP SDK enables AI assistants like Claude to directly interact with your Symfony application's data and functionality through a standardized protocol, allowing you to build AI-powered interfaces without creating custom APIs.

Important: The Symfony MCP SDK is currently experimental and does not yet have a stable release. The API may change in future versions.

Install the official MCP SDK package in your application with the following command:

composer require mcp/sdk

Note: The MCP SDK requires Symfony 6.4+. The starter branch already has this 7.3, so the SDK will install without issues.

You can check that the package is installed by running composer show:

composer show mcp/sdk

Create MCP Tools

MCP servers expose "tools" that AI assistants can call. We'll create tools using PHP attributes.

MCP services define the tools that AI assistants can call. Each public method marked with the #[McpTool] attribute becomes a callable tool. Our CustomerMcpService will expose five tools for customer search, order analysis, and data queries.

Create src/Service/CustomerMcpService.php:

<?php

namespace App\Service;

use App\Repository\CustomerRepository;
use App\Repository\OrderRepository;
use App\Repository\ProductRepository;
use Mcp\Capability\Attribute\McpTool;

class CustomerMcpService
{
    public function __construct(
        private CustomerRepository $customerRepository,
        private OrderRepository $orderRepository,
        private ProductRepository $productRepository,
    ) {}

    #[McpTool(
        name: 'search_customers',
        description: 'Search for customers by name, email, city, or county'
    )]
    public function searchCustomers(string $searchTerm): array
    {
        $customers = $this->customerRepository->findBySearchTerm($searchTerm);

        return array_map(fn($customer) => [
            'id' => $customer->getId(),
            'name' => $customer->getFullName(),
            'email' => $customer->getEmail(),
            'city' => $customer->getCity(),
            'county' => $customer->getState(),
            'totalOrders' => $customer->getOrders()->count(),
            'totalSpent' => $customer->getTotalSpent(),
        ], $customers);
    }

    #[McpTool(
        name: 'get_customer_details',
        description: 'Get detailed information about a specific customer including order history'
    )]
    public function getCustomerDetails(int $customerId): array
    {
        $customer = $this->customerRepository->find($customerId);

        if (!$customer) {
            return ['error' => 'Customer not found'];
        }

        $orders = [];
        foreach ($customer->getOrders() as $order) {
            $orders[] = [
                'id' => $order->getId(),
                'date' => $order->getOrderDate()->format('Y-m-d'),
                'status' => $order->getStatus(),
                'total' => $order->getTotal(),
                'itemCount' => $order->getOrderItems()->count(),
            ];
        }

        return [
            'id' => $customer->getId(),
            'name' => $customer->getFullName(),
            'email' => $customer->getEmail(),
            'phone' => $customer->getPhone(),
            'address' => $customer->getAddress(),
            'city' => $customer->getCity(),
            'county' => $customer->getState(),
            'postcode' => $customer->getZipCode(),
            'customerSince' => $customer->getCreatedAt()->format('Y-m-d'),
            'totalOrders' => count($orders),
            'totalSpent' => $customer->getTotalSpent(),
            'orders' => $orders,
        ];
    }

    #[McpTool(
        name: 'get_recent_orders',
        description: 'Get a list of recent orders with customer information'
    )]
    public function getRecentOrders(int $limit = 20): array
    {
        $orders = $this->orderRepository->findRecentOrders($limit);

        return array_map(fn($order) => [
            'id' => $order->getId(),
            'date' => $order->getOrderDate()->format('Y-m-d'),
            'customer' => $order->getCustomer()->getFullName(),
            'customerId' => $order->getCustomer()->getId(),
            'status' => $order->getStatus(),
            'total' => $order->getTotal(),
            'itemCount' => $order->getOrderItems()->count(),
        ], $orders);
    }

    #[McpTool(
        name: 'get_customers_by_county',
        description: 'Find all customers in a specific UK county'
    )]
    public function getCustomersByCounty(string $county): array
    {
        $customers = $this->customerRepository->findByState($county);

        return array_map(fn($customer) => [
            'id' => $customer->getId(),
            'name' => $customer->getFullName(),
            'email' => $customer->getEmail(),
            'city' => $customer->getCity(),
            'totalOrders' => $customer->getOrders()->count(),
        ], $customers);
    }

    #[McpTool(
        name: 'get_top_spenders',
        description: 'Get the top spending customers'
    )]
    public function getTopSpenders(int $limit = 10): array
    {
        $customers = $this->customerRepository->findTopSpenders($limit);

        return array_map(fn($customer) => [
            'id' => $customer->getId(),
            'name' => $customer->getFullName(),
            'totalSpent' => $customer->getTotalSpent(),
            'totalOrders' => $customer->getOrders()->count(),
            'city' => $customer->getCity(),
            'county' => $customer->getState(),
        ], $customers);
    }
}

Register the Service

The service needs to be made public so it can be accessed from the MCP server script. Update config/services.yaml and add the public service declaration at the end of the file (after the App\: namespace declaration):

services:
    _defaults:
        autowire: true
        autoconfigure: true

    # makes classes in src/ available to be used as services
    App\:
        resource: '../src/'
        exclude:
            - '../src/DependencyInjection/'
            - '../src/Entity/'
            - '../src/Kernel.php'

    # add more service definitions when explicit configuration is needed
    # please note that last definitions always *replace* previous ones

    # Make CustomerMcpService public so it can be accessed from the MCP server script
    App\Service\CustomerMcpService:
        public: true

Important: The App\Service\CustomerMcpService declaration must come after the App\: namespace declaration. In Symfony's service configuration, the last definition wins, so placing it at the end ensures it overrides the default private visibility.

After updating the configuration, clear the cache:

php bin/console cache:clear

Create the MCP Server

The MCP server is the bridge between AI assistants and your Symfony application. It listens for requests from Claude (or other AI assistants), routes those requests to the appropriate tools in your service class, and returns the results. This server script uses STDIO (standard input/output) to communicate using the MCP protocol and handles all the protocol details so your service methods can focus on business logic.

Create a new file in the bin directory called mcp-server.php:

#!/usr/bin/env php
<?php

use App\Kernel;
use Mcp\Server;
use Mcp\Server\Transport\StdioTransport;
use Symfony\Component\Dotenv\Dotenv;

require_once dirname(__DIR__).'/vendor/autoload.php';

// Load environment variables
(new Dotenv())->bootEnv(dirname(__DIR__).'/.env');

// Boot Symfony kernel to get the service container
$kernel = new Kernel($_SERVER['APP_ENV'] ?? 'dev', (bool) ($_SERVER['APP_DEBUG'] ?? true));
$kernel->boot();
$container = $kernel->getContainer();

// Get the CustomerMcpService from Symfony's container
$customerService = $container->get('App\Service\CustomerMcpService');

// Build the MCP server and register the service methods as tools using closures
$server = Server::builder()
    ->setServerInfo('Symfony Customer Manager', '1.0.0')
    ->addTool(fn(string $searchTerm) => $customerService->searchCustomers($searchTerm), 'search_customers', 'Search for customers by name, email, city, or county')
    ->addTool(fn(int $customerId) => $customerService->getCustomerDetails($customerId), 'get_customer_details', 'Get detailed information about a specific customer including order history')
    ->addTool(fn(int $limit = 20) => $customerService->getRecentOrders($limit), 'get_recent_orders', 'Get a list of recent orders with customer information')
    ->addTool(fn(string $county) => $customerService->getCustomersByCounty($county), 'get_customers_by_county', 'Find all customers in a specific UK county')
    ->addTool(fn(int $limit = 10) => $customerService->getTopSpenders($limit), 'get_top_spenders', 'Get the top spending customers')
    ->build();

// Run the server with STDIO transport
$transport = new StdioTransport();
$server->run($transport);

This approach manually registers each tool method using closures. This ensures that Symfony's dependency injection properly provides the required repository dependencies to the CustomerMcpService.

In order to work, this file needs to be executable, so run the following command to do so:

chmod +x bin/mcp-server.php

Run the following command to test that the server starts:

php bin/mcp-server.php

The server will appear to "hang" with no output - this is correct behavior. MCP servers communicate via stdio (standard input/output) and wait silently for JSON-RPC messages from an MCP client. You can press Ctrl+C to stop the server.

Note: You won't see any prompts or logs when running the server directly. The server only responds to MCP protocol messages sent by clients like Claude Desktop.

Configure Claude Desktop

Locate Claude Desktop Config

The config file location depends on your OS:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

If the file or directory doesn't exist, create it:

# macOS
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
mkdir -p ~/.config/Claude
touch ~/.config/Claude/claude_desktop_config.json

You can open the file in your default editor:

# macOS - use full path to avoid permission issues
open -e "/Users/$(whoami)/Library/Application Support/Claude/claude_desktop_config.json"

# Linux
xdg-open ~/.config/Claude/claude_desktop_config.json

Add Your MCP Server

Edit the config file and add your server:

{
  "mcpServers": {
    "symfony-customers": {
      "command": "php",
      "args": [
        "/absolute/path/to/your/app/bin/mcp-server.php"
      ],
      "cwd": "/absolute/path/to/your/app"
    }
  }
}

Replace /absolute/path/to/your/app with the actual path to your application. For example, if your app is at /Users/yourname/projects/symfony-app, the config would be:

{
  "mcpServers": {
    "symfony-customers": {
      "command": "php",
      "args": [
        "/Users/yourname/projects/symfony-app/bin/mcp-server.php"
      ],
      "cwd": "/Users/yourname/projects/symfony-app"
    }
  }
}

Important Notes:

The cwd (current working directory) is required so Symfony can find its dependencies, configuration, and database
Both paths must be absolute (not relative)
Use the full path to bin/mcp-server.php in the args array

Restart Claude Desktop

Completely quit and restart Claude Desktop for the changes to take effect.

Test with Claude

Once configured, you can ask Claude questions like:

Search for customers:

"Search for customers in London"

Get customer details:

"Show me details for customer ID 5"

Analyse orders:

"What are the recent orders?"

Find top spenders:

"Who are the top 5 spending customers?"

County-based queries:

"Show me all customers in Greater Manchester"

Claude will use the MCP tools you created to query your database and provide answers!

Add More Tools

You can extend the MCP server with additional tools:

Example: Product Search Tool

#[McpTool(
    name: 'search_products',
    description: 'Search for products by name or category'
)]
public function searchProducts(string $query): array
{
    // Your implementation
}

Example: Order Statistics Tool

#[McpTool(
    name: 'get_order_stats',
    description: 'Get statistics about orders (total count, revenue, etc.)'
)]
public function getOrderStats(): array
{
    // Your implementation
}

Next Steps

Here are some further steps I could think of, which I couldn't add to this tutorial but hope would further help your exploration of creating an MCP for your Symfony application:

Add authentication to restrict MCP access
Implement caching for frequently-queried data
Add more sophisticated search capabilities
Create resources in addition to tools
Deploy the MCP server for production use

Resources

Build a Discord bot to expose Raindrop.io instances

Greg Holmes — Tue, 21 Oct 2025 13:10:48 +0000

I'm on quite a few different Discord servers, and one of them has a 3D printing channel with a catalog of STLs. Initially, it was just a bunch of posts in a specific channel that got pinned. The problem? Those pinned posts were constantly outdated and needed manual updates from moderators or whoever originally posted them. Pretty tedious and annoying to keep bugging them.

One of the community members had a brilliant idea: why not use Raindrop.io? We could make it a collaborative catalog that willing contributors could help maintain. It worked great! The catalog grew into something really useful... but there was one catch. Every time someone wanted to search for an STL file, they had to leave Discord and open Raindrop in their browser.

So I thought, "Why not bring the search functionality directly into Discord?" That way, people can find what they need without ever leaving the conversation. You type a command, get your results privately in the same channel, and you're good to go.

What We're Building

In this tutorial, I'll walk you through building a system that backs up your Raindrop.io contents to a Supabase database and makes them searchable via a Discord bot. This project consists of two main components:

A TypeScript cron job that syncs Raindrop.io collections and bookmarks to Supabase.
A Discord bot that allows you to search your bookmarks by tags using slash commands.

Whether you're managing a 3D printing catalog like me, organizing documentation links, or even if you just want to build a Discord bot, this tutorial will show you exactly how to build it.

Project Overview

The system architecture includes:

Raindrop.io API - Source of bookmark data
Supabase - PostgreSQL database for storing bookmarks
Discord Bot - Interface for searching bookmarks
TypeScript - Type-safe implementation

Prerequisites

Before starting, make sure you have:

Node.js (v20 or higher) installed
A Raindrop.io account and API credentials
A Supabase account, database with:
- Supabase URL,
- Supabase anon key,
- Supabase service role key.
A Discord bot token and application
Basic knowledge of TypeScript and SQL

Step 1: Project Initialization

Create a new project directory and initialize it:

mkdir raindrop-backup-bot
cd raindrop-backup-bot
npm init -y

Step 2: Install Dependencies

Install all required packages. These provide:

@supabase/supabase-js - Official Supabase client for interacting with your PostgreSQL database
axios - HTTP client for making API requests to Raindrop.io
discord.js - Complete toolkit for building Discord bots and handling bot interactions
dotenv - Loads environment variables from .env file for secure credential management

npm install @supabase/supabase-js axios discord.js dotenv

Install development dependencies. These provide:

@types/node - TypeScript type definitions for Node.js built-in modules
typescript - TypeScript compiler for type-safe development
ts-node - Executes TypeScript files directly without pre-compilation

npm install --save-dev @types/node typescript ts-node

Step 3: TypeScript Configuration

Create a tsconfig.json file in your project root:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

This configuration ensures proper TypeScript compilation with ES2020 features and strict type checking.

Step 4: Project Structure

Create the following directories and files:

mkdir -p src supabase/migrations
touch .env

Your project should look like this:

raindrop-backup-bot/
├── src/
├── supabase/
│   └── migrations/
├── .env
├── package.json
└── tsconfig.json

Step 5: Environment Configuration

Create a .env file with all required environment variables:

RAINDROP_REFRESH_TOKEN=
RAINDROP_CLIENT_ID=
RAINDROP_CLIENT_SECRET=

SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

DISCORD_TOKEN=
DISCORD_CHANNEL_ID=
DISCORD_CLIENT_ID=

Getting Raindrop.io Credentials

Go to Raindrop.io App Settings
Create a new app to get your client_id and client_secret
Follow the OAuth flow to get your refresh_token

Getting Supabase Credentials

Create a new project at Supabase
Go to Project Settings > API
Copy your project URL and service role key

Getting Discord Bot Credentials

Go to Discord Developer Portal
Create a new application
Go to Bot section and create a bot
Copy the bot token
Copy the application ID (client ID)

Step 6: Database Schema

Create the database schema file with the command supabase migration new create_tables and populate the contents with the following:

-- Create collections table
CREATE TABLE collections (
    id BIGSERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    description TEXT,
    parent_id BIGINT REFERENCES collections(id) ON DELETE SET NULL,
    count INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    slug TEXT
);

-- Create raindrops table
CREATE TABLE raindrops (
    id BIGSERIAL PRIMARY KEY,
    link TEXT NOT NULL,
    title TEXT NOT NULL,
    type TEXT,
    cover TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    collection_id BIGINT REFERENCES collections(id) ON DELETE CASCADE
);

-- Create tags table
CREATE TABLE tags (
    id BIGSERIAL PRIMARY KEY,
    name TEXT NOT NULL UNIQUE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Create media table
CREATE TABLE media (
    id BIGSERIAL PRIMARY KEY,
    link TEXT NOT NULL,
    type TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    raindrop_id BIGINT REFERENCES raindrops(id) ON DELETE CASCADE
);

-- Create many-to-many relationship between raindrops and tags
CREATE TABLE raindrop_tags (
    raindrop_id BIGINT REFERENCES raindrops(id) ON DELETE CASCADE,
    tag_id BIGINT REFERENCES tags(id) ON DELETE CASCADE,
    PRIMARY KEY (raindrop_id, tag_id)
);

Database Schema Explanation

The schema consists of five tables:

collections: Stores Raindrop.io collections (folders) with hierarchical support via parent_id
raindrops: Stores individual bookmarks with links, titles, and references to collections
tags: Stores unique tags used to categorize bookmarks
media: Stores media items (images, videos) associated with bookmarks
raindrop_tags: Junction table for many-to-many relationship between raindrops and tags

Run this migration in your Supabase SQL editor or using the Supabase CLI with supabase db push.

Step 7: Backup Script - Part 1 (Setup and OAuth)

Create src/backupRaindrop.ts. Start with the imports and setup:

import axios from 'axios';
import { createClient } from '@supabase/supabase-js';
import dotenv from 'dotenv';

dotenv.config();

const clientId = process.env.RAINDROP_CLIENT_ID;
const clientSecret = process.env.RAINDROP_CLIENT_SECRET;
const refreshToken = process.env.RAINDROP_REFRESH_TOKEN;

const supabaseUrl = process.env.SUPABASE_URL!;
const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY!;
const supabase = createClient(supabaseUrl, supabaseKey);

if (!clientId || !clientSecret || !refreshToken) {
  throw new Error('Missing required environment variables');
}

// OAuth token endpoint
const TOKEN_URL = 'https://raindrop.io/oauth/access_token';
const API_BASE = 'https://api.raindrop.io/rest/v1';

OAuth Token Refresh Function

Add the function to refresh your Raindrop.io access token:

export async function refreshAccessToken(): Promise<string> {
  const response = await axios.post(TOKEN_URL, {
    grant_type: 'refresh_token',
    refresh_token: refreshToken,
    client_id: clientId,
    client_secret: clientSecret,
  });

  return response.data.access_token;
}

This function uses the OAuth refresh token flow to get a new access token for API calls.

Step 8: Backup Script - Part 2 (Collections Sync)

Add functions to fetch and sync collections:

// Function to fetch collections from Raindrop.io
async function fetchRaindropCollections() {
  const accessToken = await refreshAccessToken();
  const response = await axios.get(`${API_BASE}/collections/childrens`, {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });

  if (!response.data.result) {
    throw new Error('Failed to fetch collections from Raindrop.io');
  }

  return response.data.items;
}

// Function to separate collections into childCollections and parentCollections
function separateCollections(collections: any[]) {
  const childCollections: any[] = [];
  const parentCollections: any[] = [];

  for (const collection of collections) {
    if (collection.parent?.$id) {
      parentCollections.push(collection);
    } else {
      childCollections.push(collection);
    }
  }

  return { childCollections, parentCollections };
}

// Function to check if a collection exists in Supabase
async function collectionExists(id: number): Promise<boolean> {
  const { data, error } = await supabase
    .from('collections')
    .select('id')
    .eq('id', id)
    .single();

  if (error && error.code !== 'PGRST116') {
    console.error('Error checking collection existence:', error.message);
    throw error;
  }

  return !!data;
}

Insert and Update Collection Functions

These functions handle inserting collections into Supabase and updating their parent-child relationships after all collections are stored.

// Function to insert a collection into Supabase with parent_id set to NULL
async function insertCollectionWithNullParent(collection: any) {
  const { _id, title, description, count, slug } = collection;

  const { error } = await supabase.from('collections').insert({
    id: _id,
    title,
    description,
    parent_id: null,
    count,
    slug,
  });

  if (error) {
    console.error(`Error inserting collection "${title}":`, error.message);
    throw error;
  }

  console.log(`Inserted collection with NULL parent: ${title}`);
}

// Function to update the parent_id for a collection
async function updateCollectionParent(collection: any) {
  const { _id, parent } = collection;

  if (parent?.$id) {
    const { error } = await supabase
      .from('collections')
      .update({ parent_id: parent.$id })
      .eq('id', _id);

    if (error) {
      console.error(`Error updating parent_id for collection "${_id}":`, error.message);
      throw error;
    }

    console.log(`Updated parent_id for collection: ${_id}`);
  }
}

Collections Sync Main Function

This function orchestrates the entire collection sync process by fetching collections from Raindrop.io, separating them by hierarchy, and inserting them with proper relationships.

// Main function to sync collections
async function syncCollections() {
  try {
    const collections = await fetchRaindropCollections();

    // Separate collections into childCollections and parentCollections
    const { childCollections, parentCollections } = separateCollections(collections);

    console.log('Inserting Parent Collections with NULL parent_id...');
    for (const collection of parentCollections) {
      const exists = await collectionExists(collection._id);
      if (!exists) {
        await insertCollectionWithNullParent(collection);
      } else {
        console.log(`Parent collection already exists: ${collection.title}`);
      }
    }

    console.log('Inserting Child Collections with NULL parent_id...');
    for (const collection of childCollections) {
      const exists = await collectionExists(collection._id);
      if (!exists) {
        await insertCollectionWithNullParent(collection);
      } else {
        console.log(`Child collection already exists: ${collection.title}`);
      }
    }

    console.log('Updating Parent IDs for All Collections...');
    for (const collection of [...parentCollections, ...childCollections]) {
      await updateCollectionParent(collection);
    }

    console.log('Collections sync completed.');
  } catch (error) {
    if (error instanceof Error) {
      console.error('Error syncing collections:', error.message);
    } else {
      console.error('Error syncing collections:', error);
    }
  }
}

Step 9: Backup Script - Part 3 (Raindrops Sync)

Add functions to sync individual raindrops (bookmarks):

// Function to fetch raindrops for a specific collection
async function fetchRaindropsByCollection(collectionId: number, accessToken: string) {
  const response = await axios.get(`${API_BASE}/raindrops/${collectionId}`, {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });

  if (!response.data.result) {
    throw new Error(`Failed to fetch raindrops for collection ID: ${collectionId}`);
  }

  return response.data.items;
}

// Function to check if a raindrop exists in Supabase
async function raindropExists(id: number): Promise<boolean> {
  const { data, error } = await supabase
    .from('raindrops')
    .select('id')
    .eq('id', id)
    .single();

  if (error && error.code !== 'PGRST116') {
    console.error('Error checking raindrop existence:', error.message);
    throw error;
  }

  return !!data;
}

// Function to insert a raindrop into Supabase
async function insertRaindrop(raindrop: any, collectionId: number) {
  const { _id, link, title, type, cover, created } = raindrop;

  const { error } = await supabase.from('raindrops').insert({
    id: _id,
    link,
    title,
    type,
    cover,
    created_at: created,
    updated_at: new Date().toISOString(),
    collection_id: collectionId,
  });

  if (error) {
    console.error(`Error inserting raindrop "${title}":`, error.message);
    throw error;
  }

  console.log(`Inserted raindrop: ${title}`);
}

Step 10: Backup Script - Part 4 (Media and Tags)

Add functions to handle media and tags:

// Function to insert media entries for a raindrop
async function insertMediaEntries(media: any[], raindropId: number) {
  for (const entry of media) {
    const { link, type } = entry;

    const { error } = await supabase.from('media').insert({
      link,
      type,
      created_at: new Date().toISOString(),
      updated_at: new Date().toISOString(),
      raindrop_id: raindropId,
    });

    if (error) {
      console.error(`Error inserting media for raindrop ID "${raindropId}":`, error.message);
      throw error;
    }

    console.log(`Inserted media for raindrop ID: ${raindropId}`);
  }
}

// Function to check if a tag exists in Supabase
async function tagExists(name: string): Promise<number | null> {
  const { data, error } = await supabase
    .from('tags')
    .select('id')
    .eq('name', name)
    .single();

  if (error && error.code !== 'PGRST116') {
    console.error(`Error checking tag existence for "${name}":`, error.message);
    throw error;
  }

  return data ? data.id : null;
}

// Function to insert a tag into Supabase
async function insertTag(name: string): Promise<number> {
  const { data, error } = await supabase
    .from('tags')
    .insert({
      name,
      created_at: new Date().toISOString(),
      updated_at: new Date().toISOString(),
    })
    .select('id')
    .single();

  if (error) {
    console.error(`Error inserting tag "${name}":`, error.message);
    throw error;
  }

  console.log(`Inserted tag: ${name}`);
  return data.id;
}

// Function to insert a raindrop-tag relationship
async function insertRaindropTag(raindropId: number, tagId: number) {
  const { error } = await supabase.from('raindrop_tags').insert({
    raindrop_id: raindropId,
    tag_id: tagId,
  });

  if (error) {
    console.error(`Error inserting raindrop-tag relationship for raindrop ID "${raindropId}" and tag ID "${tagId}":`, error.message);
    throw error;
  }

  console.log(`Inserted raindrop-tag relationship: raindrop ID ${raindropId}, tag ID ${tagId}`);
}

// Function to process tags for a raindrop
async function processTags(tags: string[], raindropId: number) {
  for (const tag of tags) {
    let tagId = await tagExists(tag);

    if (!tagId) {
      tagId = await insertTag(tag);
    }

    await insertRaindropTag(raindropId, tagId);
  }
}

Step 11: Backup Script - Part 5 (Raindrops Sync Main Function)

Add the main function to sync all raindrops:

// Main function to sync raindrops
async function syncRaindrops() {
  try {
    const accessToken = await refreshAccessToken();

    // Fetch all collections from Supabase
    const { data: collections, error: collectionsError } = await supabase
      .from('collections')
      .select('id');

    if (collectionsError) {
      console.error('Error fetching collections:', collectionsError.message);
      throw collectionsError;
    }

    if (!collections || collections.length === 0) {
      console.log('No collections found to sync raindrops.');
      return;
    }

    console.log('Syncing raindrops for collections...');
    for (const collection of collections) {
      const collectionId = collection.id;

      console.log(`Fetching raindrops for collection ID: ${collectionId}`);
      const raindrops = await fetchRaindropsByCollection(collectionId, accessToken);

      for (const raindrop of raindrops) {
        const exists = await raindropExists(raindrop._id);
        if (!exists) {
          await insertRaindrop(raindrop, collectionId);

          // Insert media entries for the raindrop
          if (raindrop.media && raindrop.media.length > 0) {
            await insertMediaEntries(raindrop.media, raindrop._id);
          }

          // Process tags for the raindrop
          if (raindrop.tags && raindrop.tags.length > 0) {
            await processTags(raindrop.tags, raindrop._id);
          }
        } else {
          console.log(`Raindrop already exists: ${raindrop.title}`);
        }
      }
    }

    console.log('Raindrops sync completed.');
  } catch (error) {
    if (error instanceof Error) {
      console.error('Error syncing raindrops:', error.message);
    } else {
      console.error('Error syncing raindrops:', error);
    }
  }
}

Step 12: Backup Script - Part 6 (Execute)

Add the execution calls at the end of src/backupRaindrop.ts:

// Run the sync process
syncCollections();

// Run the sync process
syncRaindrops();

This completes the backup script. The script will:

Fetch all collections from Raindrop.io
Insert them into Supabase with proper parent-child relationships
Fetch all raindrops (bookmarks) from each collection
Insert raindrops along with their media and tags

Step 13: Discord Bot - Part 1 (Setup)

Create src/discordBot.ts and start with the imports and setup:

import { Client, GatewayIntentBits, REST, Routes, SlashCommandBuilder } from 'discord.js';
import { createClient } from '@supabase/supabase-js';
import dotenv from 'dotenv';

dotenv.config();

// Discord bot token from environment variables
const DISCORD_TOKEN = process.env.DISCORD_TOKEN;
const CLIENT_ID = process.env.DISCORD_CLIENT_ID;

if (!DISCORD_TOKEN) {
  throw new Error('DISCORD_TOKEN is not defined in environment variables.');
}

// Create a new Discord client
const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent
  ],
});

const supabaseUrl = process.env.SUPABASE_URL!;
const supabaseKey = process.env.SUPABASE_SERVICE_ROLE_KEY!;
const supabase = createClient(supabaseUrl, supabaseKey);

// Event: Bot is ready
client.once('ready', () => {
  console.log(`Logged in as ${client.user?.tag}!`);
});

Step 14: Discord Bot - Part 2 (Slash Command Registration)

// Register the /find command
const commands = [
  new SlashCommandBuilder()
    .setName('find')
    .setDescription('Search for raindrops by tag')
    .addStringOption((option) =>
      option.setName('tag').setDescription('The tag to search for').setRequired(true)
    ),
];

const rest = new REST({ version: '10' }).setToken(DISCORD_TOKEN);

(async () => {
  try {
    console.log('Started refreshing application (/) commands.');

    if (!CLIENT_ID) {
      throw new Error('CLIENT_ID is not defined in environment variables.');
    }
    await rest.put(Routes.applicationCommands(CLIENT_ID), { body: commands });

    console.log('Successfully reloaded application (/) commands.');
  } catch (error) {
    console.error(error);
  }
})();

Step 15: Discord Bot - Part 3 (Command Handler)

Create an event listener that responds when users execute the /find command. This handler validates the tag input, queries Supabase for matching bookmarks, and sends the results back as Discord embeds:

// Event: Slash command interaction
client.on('interactionCreate', async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  if (interaction.commandName === 'find') {
    let tag = interaction.options.getString('tag');
    if (!tag) {
      await interaction.reply({
        content: 'Please provide a valid tag.',
        ephemeral: true,
      });
      return;
    }

    // Convert the tag to lowercase for case-insensitive matching
    tag = tag.toLowerCase();

    try {
      // Query Supabase for the tag (case-insensitive)
      const { data: tagData, error: tagError } = await supabase
        .from('tags')
        .select('id')
        .ilike('name', tag)
        .single();

      if (tagError || !tagData) {
        await interaction.reply({
          content: `No raindrops found for the tag "${tag}".`,
          ephemeral: true,
        });
        return;
      }

      const tagId = tagData.id;

      // Query Supabase for raindrops associated with the tag
      const { data: raindrops, error: raindropsError } = await supabase
        .from('raindrop_tags')
        .select('raindrop_id')
        .eq('tag_id', tagId);

      if (raindropsError || !raindrops || raindrops.length === 0) {
        await interaction.reply({
          content: `No raindrops found for the tag "${tag}".`,
          ephemeral: true,
        });
        return;
      }

      // Fetch raindrop details
      const raindropIds = raindrops.map((r) => r.raindrop_id);
      const { data: raindropDetails, error: raindropDetailsError } = await supabase
        .from('raindrops')
        .select('id, title, link')
        .in('id', raindropIds);

      if (raindropDetailsError || !raindropDetails || raindropDetails.length === 0) {
        await interaction.reply({
          content: `No raindrop details found for the tag "${tag}".`,
          ephemeral: true,
        });
        return;
      }

      // Create embeds for each raindrop
      const embeds = await Promise.all(
        raindropDetails.map(async (raindrop) => {
          const embed: { title: string; url: string; description: string; image?: { url: string } } = {
            title: raindrop.title,
            url: raindrop.link,
            description: `Link: [Click here](${raindrop.link})`,
          };

          // Query the media table for an image associated with the raindrop
          const { data: media, error: mediaError } = await supabase
            .from('media')
            .select('link, type')
            .eq('raindrop_id', raindrop.id)
            .eq('type', 'image')
            .limit(1)
            .single();

          if (mediaError) {
            console.error(`Error fetching media for raindrop ID "${raindrop.id}":`, mediaError.message);
          }

          // Optionally add image to embed (currently commented out)
          // if (media && media.link) {
          //   embed.image = { url: media.link };
          // }

          return embed;
        })
      );

      await interaction.reply({
        content: `Raindrops for the tag "${tag}":`,
        embeds: embeds,
        ephemeral: true,
      });
    } catch (error) {
      console.error('Error processing /find command:', error);
      await interaction.reply({
        content: 'An error occurred while processing your request.',
        ephemeral: true,
      });
    }
  }
});

Step 16: Discord Bot - Part 4 (Login)

Add the login call at the end of src/discordBot.ts:

// Log in to Discord
client.login(DISCORD_TOKEN);

Step 17: Package.json Scripts

Update your package.json with convenient scripts:

{
  "name": "raindrop-backup-bot",
  "version": "1.0.0",
  "description": "Backup Raindrop.io bookmarks to Supabase and search via Discord",
  "main": "index.js",
  "scripts": {
    "backup": "npx tsc && node dist/backupRaindrop.js",
    "bot": "npx tsc && node dist/discordBot.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@supabase/supabase-js": "^2.50.0",
    "axios": "^1.10.0",
    "discord.js": "^14.21.0",
    "dotenv": "^16.6.1"
  },
  "devDependencies": {
    "@types/node": "^24.0.3",
    "ts-node": "^10.9.2",
    "typescript": "^5.8.3"
  }
}

Step 18: Running the Project

First Time Setup

Run the database migration in Supabase (copy the SQL from Step 6 into the SQL editor)
Fill in your .env file with all credentials
Install dependencies:

npm install

Running the Backup Job

To sync your Raindrop.io bookmarks to Supabase:

npm run backup

This will:

Fetch all your collections from Raindrop.io
Insert them into Supabase with proper relationships
Fetch all bookmarks (raindrops) from each collection
Store all associated tags and media

You can run this command manually or set it up as a cron job to run regularly.

Running the Discord Bot

To start the Discord bot:

npm run bot

The bot will:

Connect to Discord
Register the /find slash command
Listen for interactions
Query Supabase when users search for tags

Step 19: Using the Discord Bot

Once your bot is running and invited to your Discord server:

Type /find in any channel
Enter a tag name (e.g., "typescript", "tutorials", etc.)
The bot will search your Supabase database and return matching bookmarks as embeds

Example usage:

/find tag:javascript

The bot will return all bookmarks tagged with "javascript" showing:

Title
Link (clickable)
Associated media (if enabled)

Step 20: Setting Up a Cron Job (Optional)

To automatically sync your bookmarks daily, you can set up a cron job:

On Linux/Mac

Edit your crontab:

crontab -e

Add this line to run the backup daily at 2 AM:

0 2 * * * cd /path/to/raindrop-backup-bot && npm run backup >> /var/log/raindrop-backup.log 2>&1

Using PM2 (Recommended)

Install PM2 globally:

npm install -g pm2

Create a PM2 ecosystem file ecosystem.config.js:

module.exports = {
  apps: [
    {
      name: 'discord-bot',
      script: 'dist/discordBot.js',
      cron_restart: '0 2 * * *',
      autorestart: true,
    },
    {
      name: 'raindrop-backup',
      script: 'dist/backupRaindrop.js',
      cron_restart: '0 2 * * *',
      autorestart: false,
    }
  ]
};

Start your services:

npm run backup  # Initial sync
pm2 start ecosystem.config.js
pm2 save
pm2 startup

Conclusion

You now have a fully functional system that:

Backs up your Raindrop.io bookmarks to a PostgreSQL database
Preserves all metadata including collections, tags, and media
Provides a searchable interface via Discord bot
Can be automated to run on a schedule

This architecture is extensible and can be adapted for other bookmark services or enhanced with additional features. The separation between data sync and retrieval makes it easy to add new interfaces (web, mobile, Slack, etc.) without modifying the core backup logic.

The complete source code for this project is available, and you can customize it to fit your specific needs. Happy bookmarking!

Resources

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.

Build a Birthday Congratulations Time Capsule with Go

Greg Holmes — Thu, 10 Jun 2021 11:59:01 +0000

Intro

With the pandemic, we've at times been forced into virtual interactions with our family and friends. But even with a pandemic going on, our lives have continued. People are still getting married; birthdays still come around once a year for everyone.

So when my birthday came around, it also reminded me of something my grandmother used to do every year. She'd call me first thing in the morning and sing happy birthday down the phone to me.

This memory triggered an idea in my head to create a birthday time capsule where all of your friends and family call a number. When they call, they can leave their well-wishes as a voice recording. Then, you would receive a call and hear all of the well-wishing recordings at a predetermined date and time.

Prerequisites

To complete this tutorial you will need:

Go
Ngrok
An active phone number

Vonage API Account

To complete this tutorial, you will need a Vonage API account. If you don’t have one already, you can sign up today and start building with free credit. Once you have an account, you can find your API Key and API Secret at the top of the Vonage API Dashboard.

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Create Ngrok Tunnel

When making or receiving voice calls, Vonage will send an HTTP request to your preconfigured webhook URLs. Your application should be accessible to the internet to receive it, so we recommend using Ngrok.

Launch ngrok with the following command:

ngrok http 8080 # Creates an http tunnel to the Internet from your computer on port 8080

Make sure to copy your ngrok HTTPS URL, as you'll need this later when configuring the project.

Create Vonage Application with Webhooks

This project will rely on listening to the inbound webhook requests made by the Vonage APIs, so we'll need to create a new application. Go ahead and create a new application with the following input:

Name - this can be anything you wish; it's a name only you will see
Capabilities
- Voice
- Under Answer URL add: <your ngrok url>/webhooks/answer
- Under Event URL add: <your ngrok url>/webhooks/event
- RTC (In-app voice & messaging)
- Under Event URL add: <your ngrok url>/webhooks/event
Click "Generate public & private key" and move the private.key file into your project directory.
Click "Save changes"

Your application is now ready to send you any predefined webhooks!

Note If you're using ngrok without an account, <your ngrok url> will be different every time you run ngrok. Remember to update your webhook URLs every time you run the command. Alternatively, sign up for a free account to make the URL persist.

Collect Voice Recordings

The first half of this project is to receive the voice recordings from the well-wishers.

Install Required Packages

We will need several third-party Go libraries to successfully run this project. These include the following:

joho/godotenv - to securely store our Vonage credentials
vonage/vonage-go-sdk - to make our API requests at Vonage
gorm and sqlite to store the voice message file names and whether they've been played into an SQLite database

To install these third-party libraries, run the following four commands:

go get github.com/joho/godotenv
go get github.com/vonage/vonage-go-sdk
go get gorm.io/gorm
go get gorm.io/driver/sqlite

To make use of joho/gotdotenv package, and start storing your credentials in a file, create your .env file in your project directory and add the following variables:

VONAGE_APPLICATION_ID=
VONAGE_PRIVATE_KEY_PATH=private.key
VONAGE_NUMBER=
TO_NUMBER=
PERSON_NAME=
NGROK_URL=

Be sure to populate these variables with the correct values you've gathered in previous steps. Below is a list of how to gain all of the required values:

VONAGE_APPLICATION_ID - Your application ID is the ID given when you created an application in Vonage's dashboard
VONAGE_PRIVATE_KEY - The location of the private.key file relevant to the project directory
VONAGE_NUMBER - Your Vonage number is the virtual phone number you purchased in the Vonage Dashboard
TO_NUMBER - The number that will be receiving the call with all the voice recordings at your predetermined date and time
PERSON_NAME - The name of the person who will be receiving these well wishes
NGROK_URL - The ngrok URL you received and stored in a previous step

Structs are typed collections of fields that we'll use to group data from webhook requests throughout this tutorial. Create a new file called structs.go and add the following:

package main

type Dtmf struct {
    Digits    string
    Timed_out bool
}

type EventResponse struct {
    Conversation_id string
    Type            string
    Body            EventBodyResponse
}

type EventBodyResponse struct {
    Channel EventBodyChannelResponse
}

type EventBodyChannelResponse struct {
    Id   string
    Type string
}

type Recording struct {
    Start_time        string
    Recording_url     string
    Size              int
    Recording_uuid    string
    End_time          string
    Conversation_uuid string
    Timestamp         string
}

type Response struct {
    Speech            []string
    Dtmf              Dtmf
    From              string
    To                string
    Uuid              string
    Conversation_uuid string
    Timestamp         string
}

Now we've created some of the boring bits to get started, let's create the project's main file, main.go, in your project directory and add the following code to it:

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "log"
    "net/http"
    "os"

    "github.com/joho/godotenv"
    "github.com/vonage/vonage-go-sdk/jwt"
)

func main() {
    err := godotenv.Load()

    if err != nil {
        log.Fatal("Error loading .env file")
    }

  connectDb()

    http.ListenAndServe(":8080", nil)
}

The code in the example above is the initial structure for the project. It currently loads the .env file into the project and creates a web server listening on port 8080.

Creating the Database Model

To save the file name of the audio files and whether they were played or not, we'll need to create a database. Let's create the model BirthdayEntry and a function connectDb() to handle connecting to our database. Create a new file called models.go and add the following code:

package main

import (
    "gorm.io/driver/sqlite"
    "gorm.io/gorm"
)

var db *gorm.DB
var err error

type BirthdayEntry struct {
    gorm.Model
    FileName string
    Played   bool
}

func connectDb() {
    db, err = gorm.Open(sqlite.Open("voiceRecordings.db"), &gorm.Config{})

    if err != nil {
        panic("failed to connect database")
    }

    db.AutoMigrate(&BirthdayEntry{})
}

Handling the Answering of a Call

There will be multiple steps to the recording process of a voice message. The first one will answer the initial call and instruct the Vonage APIs on what to do next. So, create a new file in your project directory called recording.go and add the following:

package main

import (
    "encoding/json"
    "errors"
    "io"
    "io/ioutil"
    "log"
    "net/http"
    "net/url"
    "os"
    "strconv"
    "time"

  "github.com/vonage/vonage-go-sdk"
    "github.com/vonage/vonage-go-sdk/ncco"
    "github.com/vonage/vonage-go-sdk/jwt"
)

func answer(w http.ResponseWriter, req *http.Request) {
    MyNcco := ncco.Ncco{}
    talk := ncco.TalkAction{Text: "Thank you for calling the birthday congratulations hotline for " + os.Getenv("PERSON_NAME") + ".. If you would like to leave a message, please press 1. Otherwise end the call. Thank you"}
    MyNcco.AddAction(talk)

    inputAction := ncco.InputAction{EventUrl: []string{"https://" + req.Host + "/webhooks/record"}, Dtmf: &ncco.DtmfInput{MaxDigits: 1}}
    MyNcco.AddAction(inputAction)

    data, _ := json.Marshal(MyNcco)

    w.Header().Set("Content-Type", "application/json")
    w.Write(data)
}

The above functionality will create a new Call Control Object (NCCO) with two actions to be carried out. The first action will be to "Talk", converting predefined text into voice, and the second one will be to handle user's input via Dual Tone Multi-Frequency (DTMF), with another predefined webhook URL.

These actions are then converted into a JSON object and returned in the request.

This function is currently unused, so let's change that!
Back in main.go within the main() function, add the following line of code, which tells the webserver to listen for the URL webhooks/answer, and when triggered, call the answer() function:

// First Step - Answer phone call
http.HandleFunc("/webhooks/answer", answer)

Recording the Call

When in a voice call, the RecordAction in the NCCO is triggered and starts recording anything your microphone will pick up. When you trigger the RecordAction, you need to define the webhook URL to provide you with the details of the recorded file upon completion of the call.

To trigger a recording, you'll first need to register two new routes in your webserver. In your main.go file below your call to the answer function, add the following two lines:

// Second Step - Take Voice Recording
http.HandleFunc("/webhooks/record", recordUsersMessage)
// Third Step - Receive Voice Recording confirmation + Download the file
http.HandleFunc("/webhooks/recording-file", getFileRecording)

In your recording.go file, one of the functions you defined in the step above is the recordUsersMessage() function, triggered when the user inputs their DTMF response into the call (Pressing 1, for example). This function will create a new NCCO, which will first convert some text to speech, thanking them, then requesting they leave a message after the tone.

The second action is a RecordAction, which tells the API to record whatever is said after the tone. Add this new function to your file:

func recordUsersMessage(w http.ResponseWriter, req *http.Request) {
    data, _ := ioutil.ReadAll(req.Body)
    var response Response
    json.Unmarshal(data, &response)

    MyNcco := ncco.Ncco{}
    talk := ncco.TalkAction{Text: "Thank you. Please leave a message after the tone."}
    MyNcco.AddAction(talk)

    recordAction := ncco.RecordAction{EventUrl: []string{"https://" + req.Host + "/webhooks/recording-file"}, Format: "mp3", BeepStart: true, EndOnSilence: 10}
    MyNcco.AddAction(recordAction)

    responseData, _ := json.Marshal(MyNcco)

    w.Header().Set("Content-Type", "application/json")
    w.Write(responseData)
}

Saving the Audio File

Once a voice recording is completed, a call to the /webhooks/recording-file path is triggered with JSON, similar to the example below:

{
  "start_time": "2020-01-01T12:00:00Z",
  "recording_url": "https://api.nexmo.com/v1/files/aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "size": 12345,
  "recording_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "end_time": "2020-01-01T12:01:00Z",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

In this JSON example, we can see the recording_url, which is vital for our tutorial to work. This recording URL is protected; you need to generate a JSON Web Token (JWT) and provide it with the GET request when pulling that recording file.

The first step is to create a new row in the database for this file, create the file name (Unix timestamp) and call the downloadFile() function. Then, in your recordings.go file, add the following function:

func getFileRecording(w http.ResponseWriter, req *http.Request) {
    data, _ := ioutil.ReadAll(req.Body)
    var recording Recording
    json.Unmarshal(data, &recording)

    responseData, _ := json.Marshal(data)

    fileName := strconv.FormatInt(time.Now().UTC().UnixNano(), 10) + ".mp3"
    err := downloadFile(recording.Recording_url, fileName)

    if err != nil {
        log.Fatal(err)
    }

    birthdayEntry := BirthdayEntry{FileName: fileName, Played: false}

    _ = db.Create(&birthdayEntry)

    w.Header().Set("Content-Type", "application/json")
    w.Write(responseData)
}

Downloading the File

You may have noticed that we don't yet have the downloadFile() function called in the example above. Our next step is to add this as well as another function to generate our JWT. The JWT needs passing as a header in the request.

Add the following to your recordings.go file. This action will download the audio file from Vonage servers and save it as a file in the recordings directory with the predetermined file name.

func downloadFile(audioUrl string, fileName string) error {
    //Get the response bytes from the url
    reqUrl, _ := url.Parse(audioUrl)
    token := generateJWT()
    request := &http.Request{
        Method: "GET",
        URL:    reqUrl,
        Header: map[string][]string{
            "Authorization": {"Bearer " + token},
        },
    }

    response, err := http.DefaultClient.Do(request)

    if err != nil {
        log.Fatal("Error:", err)
    }

    defer response.Body.Close()

    if response.StatusCode != 200 {
        return errors.New("received non 200 response code")
    }

    file, err := os.Create("./recordings/" + fileName)

    if err != nil {
        return err
    }

    defer file.Close()

    _, err = io.Copy(file, response.Body)

    if err != nil {
        return err
    }

    return nil
}

We still haven't generated our JWT token! So, using Vonage's Go SDK, add the following function to recordings.go. This function uses your VONAGE_APPLICATION_ID and your VONAGE_PRIVATE_KEY_PATH environment variables to generate a new JWT.

func generateJWT() string {
    applicationId := os.Getenv("VONAGE_APPLICATION_ID")
    privateKey, _ := ioutil.ReadFile(os.Getenv("VONAGE_PRIVATE_KEY_PATH"))
    g := jwt.NewGenerator(applicationId, privateKey)

    token, _ := g.GenerateToken()

    return token
}

That's it for the part of the system that collects the voice calls; before we move on to the second half of the tutorial, we're going to want to test this half from start to finish.

First, make sure your project is running. In your Terminal, inside your project directory, run the command:

go run .

You should still have ngrok running, so go ahead and call your Vonage virtual number using your phone.

The first response is the following voice message: "Thank you for calling the birthday congratulations hotline for .. If you would like to leave a message, please press 1. Otherwise end the call. Thank you".

If you press one on your keypad, you'll then hear: "Thank you. Please leave a message after the tone.". Now record yourself saying a few words and hang up.

A few seconds after completion of the phone call, check your recordings directory. You'll see a new file created.

It's time to build the part of the system for the birthday person!

Calling the Birthday Person

Create a Cronjob and Congratulate

This project needs a method to run one of the functions at a specific date and time.

The cron job is a time scheduler in Unix operating systems. This project will use a cron library for Go to define a particular date and time on running a specific function.

In your Terminal, run the command below to install this cron library:

go get github.com/robfig/cron

Inside your the main() function within your main.go we're going to call a function yet to be created, runCongratulateCron(), so add this below the part where you call connectDb():

runCongratulateCron()

To keep the functionality separate from the first part of the tutorial, we will add the necessary functionality for this part in a separate file. Create a new file called congratulate.go and add the following code:

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "os"

  "github.com/robfig/cron"
    "github.com/vonage/vonage-go-sdk"
    "github.com/vonage/vonage-go-sdk/ncco"
)

func runCongratulateCron() {
    c := cron.New()
    // This would be triggered at midnight on 1st Jan
    c.AddFunc("0 0 0 1 1 *", func() {
        congratulate()
    })
    c.Start()
}

func congratulate(w http.ResponseWriter, req *http.Request) {
    privateKey, _ := ioutil.ReadFile(os.Getenv("VONAGE_PRIVATE_KEY_PATH"))
    auth, _ := vonage.CreateAuthFromAppPrivateKey(os.Getenv("VONAGE_APPLICATION_ID"), privateKey)
    client := vonage.NewVoiceClient(auth)

    from := vonage.CallFrom{Type: "phone", Number: os.Getenv("VONAGE_NUMBER")}
    to := vonage.CallTo{Type: "phone", Number: os.Getenv("TO_NUMBER")}

    MyNcco := ncco.Ncco{}

    talkAction := ncco.TalkAction{Text: "Happy Birthday! I have collected a number of recordings from your friends and family wishing you a happy birthday. If you would like to listen to this, please press 1."}
    MyNcco.AddAction(talkAction)

    inputAction := ncco.InputAction{EventUrl: []string{"https://" + os.Getenv("NGROK_URL") + "/webhooks/play-audio"}, Dtmf: &ncco.DtmfInput{MaxDigits: 1}}
    MyNcco.AddAction(inputAction)

    conversationAction := ncco.ConversationAction{Name: os.Getenv("TO_NUMBER"), StartOnEnter: "false"}
    MyNcco.AddAction(conversationAction)

    client.CreateCall(vonage.CreateCallOpts{From: from, To: to, Ncco: MyNcco})
}

The above code has two functions.

First, the runCongratulateCron() function defines a new cronjob and adds the specified time for the birthday person to receive their phone call. If you're unsure how to set up the times with a cronjob, please check the Crontab Guru to build your custom time set.

The second function gets called from the first one, and this makes the outbound Text-To-Speech voice call to the birthday person, then asks them for an InputAction ("Press 1 to continue").
To keep the call active for the receiver, a ConversationAction is needed. We'll learn how to play the audio into the call in the next step, but this needs to be done in an active conversation.

Play Audio Into a Call

Now that we have a call, we need to add the code to play the audio files into the voice call. To do this, you'll need to grab the UUID and pass it into a request calling the PlayAudioStream function, alongside the URL of the file you wish to play first.

Note you cannot queue the audio files. If you loop through playing each audio file into the call, it will interrupt each audio file with the latest one. To avoid this, we need to play the file and then wait for an event to come in on completion. We then find the next unplayed one in the database and play that one on completion of the previous audio file.

So, in congratulate.go add the following code:

func congratulatePlayAudio(w http.ResponseWriter, req *http.Request) {
    data, _ := ioutil.ReadAll(req.Body)
    var response Response
    json.Unmarshal(data, &response)

    playAudio(response.Uuid, req.Host)
}

func playAudio(uuid string, host string) {
    var birthdayEntry BirthdayEntry

    privateKey, _ := ioutil.ReadFile(os.Getenv("VONAGE_PRIVATE_KEY_PATH"))
    auth, _ := vonage.CreateAuthFromAppPrivateKey(os.Getenv("VONAGE_APPLICATION_ID"), privateKey)
    client := vonage.NewVoiceClient(auth)

    if err := db.First(&birthdayEntry, "played = ?", false).Error; err != nil {
        client.PlayTts(uuid, "This is the end of your birthday wishes, you may now hang up.", vonage.PlayTtsOpts{})

        return
    }

    fmt.Println("https://" + host + "/" + birthdayEntry.FileName)

    result, _, _ := client.PlayAudioStream(uuid,
        "https://"+host+"/"+birthdayEntry.FileName,
        vonage.PlayAudioOpts{},
    )

    birthdayEntry.Played = true
    db.Save(&birthdayEntry)

    fmt.Println("Update message: " + result.Message)
}

In main.go find the line http.HandleFunc("/webhooks/recording-file", getFileRecording) and add the following:

http.HandleFunc("/congratulate", congratulate)
http.HandleFunc("/webhooks/play-audio", congratulatePlayAudio)

Trigger Request to Play Next Audio File

As previously discussed, we need to play the next audio file into the call upon completing the previous one. Using the previously defined webhook URL under: RTC (In-app voice & messaging) in the dashboard, we'll listen for a specific event that contains a particular key in the request. By listening to the event.type part of the request, we'll be able to check if the value is: audio:play:done, and then call the function playAudio to find the following unplayed audio file.

Inside congratulate.go add this new event function:

func event(w http.ResponseWriter, req *http.Request) {
    var event EventResponse

    err := json.NewDecoder(req.Body).Decode(&event)

    if err != nil {
        return
    }

    if event.Type == "audio:play:done" {
        playAudio(event.Body.Channel.Id, req.Host)
    }
}

Then, in main.go, under the line http.HandleFunc("/webhooks/play-audio", congratulatePlayAudio) add:

    http.HandleFunc("/webhooks/event", event)

That's it! We've now created our birthday celebrations time capsule with Go! Below we'll run through the step-by-step process to test the functionality.

Test It!

Now that we've built this project, let's outline the process from start to finish:

Well-wishers call your virtual Vonage number
Your app answers the call with a Text-To-Speech message: "Thank you for calling the birthday congratulations hotline for .. If you would like to leave a message, please press 1. Otherwise, end the call. Thank you"
The app waits for you to input a number in your keypad.
The next webhook receives a request, sends a Text-To-Speech message: "Thank you. Please leave a message after the tone."
A beep happens, and the call is now recording anything picked up from your microphone.
You end the call when you're finished.

However, many well-wishers can repeat steps 1-6 there are.

At the specified time (Defined in the runCongratulateCron() function), the function congratulate() is called.
The application to the birthday person makes an outbound call.
On answering the call, the receiver is presented with "Happy Birthday! I have collected several recordings from your friends and family wishing you a happy birthday. If you would like to listen to this, please press 1."
The call is now waiting for the receiver to press a number on their keypad.
The application will then retrieve the first unplayed audio file from the database and stream it into the voice call.
On completion of the audio file stream, an event is sent back to the application. When this event is received, the application finds the next unplayed audio file and streams it through the call.
When there are no unplayed audio files, the call is ended.

You've now integrated a birthday celebrations time capsule with Go, using Vonage's Voice API. The example provided is just one of many ways to use the Voice API.

If this tutorial has piqued your interest in our Voice API, but Go isn't the language of your choice, other tutorials in various languages or services can be found here on the Vonage blog, such as:

If you have any questions, advice, or ideas you'd like to share with the community, please feel free to jump on our Community Slack workspace, or contact me on Twitter. I'd love to hear back from anyone that has implemented this tutorial and how your project works.

Random Facts Voice Call With PHP, Uselessfacts and AWS Lambda

Greg Holmes — Tue, 13 Apr 2021 12:47:48 +0000

Have you wanted to run a service without needing to create and maintain a server? Whether this to be a function triggered at set intervals or a specific action triggers this function?

In this tutorial, we will create a PHP application and host it on AWS Lambda, listening for a specific webhook URL to be triggered when someone calls a specific phone number. The application will then confirm the caller's number and convert a random fact from text to speech for the caller to hear. The random facts get retrieved from an API called Random Useless Facts.

Prerequisites

An AWS Account
Serverless installed locally
PHP installed locally
Composer installed locally

Vonage API Account

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Getting Started

Install the Dependencies

First, you'll need to create a directory for your project, then, in your Terminal, navigate to this directory and run the following command to initialise your Composer project:

composer init

Once you've finished with that step, run the command below to install the required third-party libraries. These libraries are:

the Slim PHP Framework,
Slim's PSR-7 which contains Response and Request interfaces we'll need,
GuzzleHttp to make API requests in retrieving random facts,
Bref to bring support for PHP on AWS Lambda,
Vonage's PHP client to correctly handle incoming webhook requests for a voice call.

composer require slim/slim:"4.*" slim/psr7 guzzlehttp/guzzle:"^7.0" bref/bref vonage/client

Now that you've installed the third-party libraries, it's time to make use of one of these. In your Terminal, run the following command to initialise a Bref project, be sure to accept all the defaults provided:

vendor/bin/bref init

This will create two new files:

index.php will contain the code for the application
serverless.yml will contain the configuration requirements for deploying the application to AWS

Write the Code

In your code editor, open the newly created index.php file. Remove the contents of this file as we're going to be rewriting everything.

The first thing to add to the file is the imports for the classes used from the third-party libraries we installed in the previous step. Copy the following into your index.php file:

<?php

use GuzzleHttp\Client;
use Laminas\Diactoros\Response\JsonResponse;
use Psr\Http\Message\ResponseInterface as Response;
use Psr\Http\Message\ServerRequestInterface as Request;
use Slim\Factory\AppFactory;
use Vonage\Voice\NCCO\Action\Talk;
use Vonage\Voice\NCCO\NCCO;
use Vonage\Voice\Webhook\Answer;
use Vonage\Voice\Webhook\Factory;

require __DIR__ . '/vendor/autoload.php';

We need to create the Slim application in our index.php file and an empty GET endpoint with the URI being /webhooks/answer. To do this, add the following to the file:

$app = AppFactory::create();

$app->get('/webhooks/answer', function (Request $request, Response $response, array $args) {

});

$app->run();

The /webhooks/answer endpoint will be configured in your Vonage dashboard later as a way for your virtual phone number to get instructions on what to do when a call is made.

Next, we need to create the functionality that will allow us to receive the data transmitted to the webhook, parse the from phone number, make a GET request to the random fact generator, create and return a call control object (NCCO) to the caller. The code below carries out all of this functionality described, so add this into your $app->get('/webhooks/answer' function:

// Convert the contents of the `$request` sent in the `GET` request into a Voice Webhook Object.
/** @var Answer $call */
$call = Factory::createFromRequest($request);
// Take the `from` phone number and add spaces so it can be read properly in the voice call
$fromSplitIntoCharacters = implode(" ", str_split($call->getFrom()));

// Create a new GuzzleHttp client ready to make a `GET` request
$client = new Client();
// Make a `GET` request for a random useless fact in English
$response = $client->get('https://uselessfacts.jsph.pl/random.json?language=en');
// Convert the response JSON into a PHP Array
$responseArray = json_decode($response->getBody(), true);

// Initialise the Call Control Object ready to take actions to return back to the caller
$ncco = new NCCO();
$ncco
    // Create the first Talk Action thanking the caller and reading out their number back to them
    ->addAction(
        new Talk('Thank you for calling from ' . $fromSplitIntoCharacters)
    )
    // Create the second Talk Action reading the caller their random fact.
    ->addAction(
        new Talk('Your fact is: ' . $responseArray['text'])
    );

// Returns a Json Response of the NCCO containing the two Talk Actions.
return new JsonResponse($ncco);

Deploy the Code

To deploy the code to AWS Lambda, in your Terminal, run the following command:

serverless deploy

When the deployment is successful, you'll see an output similar to the example shown in the image below. The output may be slightly different depending on the values in your serverless.yml file, though. Make sure to keep note of the URL found in the endpoints: section.

Create an Application

We now need an application in with Vonage in order to enable our virtual phone number to know which endpoint it needs to request when a call is made. Create an application in your Dashboard under "Your Applications" and give your new application a name.

Add Voice capabilities to the application and configure the URLs using the Lambda URL you copied earlier in the previous step. For the Answer URL, use [paste lambda url]/webhooks/answer and for the Event URL [paste lambda url]/webhooks/event.

Now, click the Link button next to your recently purchased Vonage virtual number to link your new application to the phone number.

You've purchased a Vonage virtual number, created a Vonage Application, and written the code to handle the voice webhook events. It's time to test your project in action!

Test It

To test your project once you've deployed it to AWS Lambda call your virtual number and hear the voice reading back your phone number followed by a random fact.

What Now?

You've now successfully created and deployed a PHP application to AWS Lambda which listens to a webhook waiting for your virtual number to receive a phone call.

Here are some links to other tutorials we've using serverless functions:

As always, if you have any questions, advice or ideas you’d like to share with the community, then please feel free to jump on our Community Slack workspace, or you can contact me directly on Twitter. I'd love to hear how you've gotten on with this tutorial and how your project works.

Open Source Video Conferencing

Greg Holmes — Wed, 24 Mar 2021 12:21:39 +0000

What is Vonage Video (Formerly OpenTok / TokBox)?

Vonage Video (Formerly TokBox / OpenTok) is an API that allows businesses to build a custom video experience within any mobile, web, or desktop application.

This API supports all video use-cases, such as 1:1 video consultations, group video chat, or large scale broadcasts to thousands of people. You're able to record any session with control over how to compose and securely deliver these files to your chosen method of storage. Analytics allow you to see project-by-project summaries in the dashboards or see session-specific analytics through the Advanced Insights API. The Video API enables you to build on our standard always-on encryption and GDPR-compliance capabilities to offer an extensive range of advanced security, firewall-control, regional isolation and compliance certificate options. There are many more features and services provided within the Vonage Video service. For more information on these, please head over to the landing page.

What is WebRTC?

Web Real-Time Communication (WebRTC) is a free and open-source project that provides web browsers and mobile applications to have real-time communication with APIs. WebRTC allows audio and video communication to function within your web browser by allowing communication to happen directly between peer-to-peer, which removes the requirement to install plugins or download any native applications.

What is Vonage Open Source Conferencing and Recording?

Vonage Open Source Conferencing and Recording is your private web-based video conferencing solution. It is based on the Vonage Video API Platform (formerly OpenTok API) and uses the Vonage Video SDKs and APIs. You can deploy the app on your servers to get your video conferencing app running on WebRTC.

If you wish to test this service out without hosting your own servers, you're welcome to head over to our Demo webpage. This demo page is hosted by a default version of the Open Source Conferencing and Recording package, which can be found on our Github Repository.

How Can I Host My Own Video Conferencing Software?

Prerequisites

Installation

To run this server, you'll need to clone the repository and install all required third-party libraries. In your terminal, run the three commands below:

git clone git@github.com:opentok/opentok-rtc.git
cd opentok-rtc
npm install # Installs required packages

Minimum Configuration

Once you've installed all of the required dependencies, some configuration is required. The very least you'll need to do is define your API key and secret, which you can obtain from the Vonage Video Dashboard.

To start, you'll need to create a config.json file, and the command below will copy a precompiled config.json file with all empty values for you. So run the command:

cp config/example.json config/config.json

Open this file, and the first few lines will be what you see in the example below:

{
   "showTos": false,
   "meetingsRatePerMinute": 30,
   "OpenTok":{
      "apiKey": "<key>",
      "apiSecret": "<secret>",
      "publisherResolution": "640x480"
   },
   ...
}

Be sure to replace <key> and <secret> with your Video API key and the corresponding API secret that you retrieved from the Vonage Video Dashboard.

If you do not wish to keep the credentials within your config.json file, you can use environment variables instead. You can set the environment variables using the commands below, again making sure to replace <key> and <secret> with your values:

export TB_API_KEY=<key>
export TB_API_KEY=<secret>

Running the Server

Before you run the RTC server, you'll need to make sure Redis is running, so in your terminal, enter the following command:

redis-server

The base command to run the server on localhost with all of the default settings, including the default port (8123), is the following command:

node start

However, there are some other flags you can add to your commands for a more customised setup. You can see a few of these examples below:

node server -p 8080 # To run the server on a different port to the default
node server -d # To run the server as a daemon in the background

If you wish to use SSL, the server expects the SSL Certificate to be named serverCert.pem and the SSL private key file named serverKey.pem. You can find a pre-generated self-signed SSL certificate pair in the sampleCerts directory.

The flag -S tells the server it needs to enable the launch of a secure server while the flag -C <dir> along with the directory name tells the server where to find the certificates. To run the server using these certificates, you would enter the following:

node server -S -C sampleCerts

For detailed information on available options, run node server -h.

Additional Configuration Options

There are many other options available for configuration to suit your needs. These options can be set either in your config.json file or as an environment variable. The keys for these options are specified first for each choice in the examples below:

appName (config.json) / APP_NAME (environment variable) -- The name of the application displayed in various places throughout the lifecycle of the video call. The default value is "Vonage Video Conferencing".
introText (config.json) / INTRO_TEXT (environment variable) -- The text displayed under the application name in the first page which displays the precall widget. The default value is 'Welcome to Video Conferencing'.
showTos (config.json) / SHOW_TOS (environment variable) -- Whether the app will display the terms of service dialog box and require the user to agree to the terms before joining a room. The default value is false.
meetingsRatePerMinute (config.json) / MEETINGS_RATE_PER_MINUTE (environment variable) -- Determines the maximum amount of new meetings that can be created in a minute. Users will be allowed to join a meeting that already exists. Otherwise a message will appear telling them that the service is not available at the moment. If the value is set to any negative number, rate limiting will be turned off and all meetings will be allowed. If this value is set to 0, all new meetings will be rejected. The default value is -1.
minMeetingNameLength (config.json) / MIN_MEETING_NAME_LENGTH (environment variable) -- The minimum length of meeting names created. The default value, 0, indicates that there is no minimum length. (You can set this in the config file using the minMeetingNameLength setting.) The default value is 0.
maxUsersPerRoom (config.json) / MAX_USERS_PER_ROOM (environment variable) -- The maximum number of users allowed in a room at the same time. Set this to 0, the default, to allow any number of users. The default value is 0.
enableRoomLocking (config.json) / ENABLE_ROOM_LOCKING (environment variable) -- Whether or not to include the Lock Meeting command to users in the options menu. This command allows users to prevent new participants from joining a meeting. The default value is true.
autoGenerateRoomName (config.json) / AUTO_GENERATE_ROOM_NAME (environment variable) -- Whether or not to auto-generate the room name on behalf of the user. If this setting is turned on, we will use haikunator to generate room names for new rooms. If turned off, users will be prompted to enter a room/meeting name when they visit the landing page and won't be allowed to move forward until they do so. The default value is true.
enableEmoji (config.json) / ENABLE_EMOJI (environment variable) -- Whether or not to enable emoji support in the text chat widget.

Customising the UI

For information on how to customise the Vonage Open Source Conferencing and Recording UI, see CUSTOMIZING-UI.

How Is My Service Running?

There is a health status check endpoint at /server/health. You can load this URL to check whether the app can connect to all required external services. On success, this health check endpoint sends a response with the HTTP status code set to 200 and the JSON similar to the following:

{
  "name": "opentok-rtc",
  "version": "4.1.1",
  "gitHash": "312903cd043d5267bc11639718c47a9b313c1663",
  "opentok": true,
  "googleAuth": true,
  "status": "pass"
}

An example of a failing health check will be similar to the following:

{
  "name": "opentok-rtc",
  "version": "4.1.1",
  "git_hash": "312903cd043d5267bc11639718c47a9b313c1663",
  "opentok": false,
  "error": "OpenTok API server timeout exceeded.",
  "status": "fail"
}

Build an On-Call Application With React Native and Symfony

Greg Holmes — Tue, 02 Mar 2021 15:19:51 +0000

Are you a developer? Have you ever been on call and had to install one of those pesky apps that notify you whenever something is a bit off? The threshold for errors has exceeded, or the server is taking too long to give responses, for example? If so, have you ever thought, "I'd like to build myself one of those services?" Well, with this tutorial, you're about to start the basics of building one of these applications and using Vonage to perform the communications.

This tutorial will help you build the beginning of an API in PHP using Symfony and the mobile application using React Native.

The complete code for this tutorial can be found at our: Community Repository. Be sure to checkout to the end-tutorial branch.

Prerequisites

To complete this tutorial you will need the following:

Vonage API Account

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs.

Clone the Repository

git clone https://github.com/nexmo-community/on-call-application-api
cd on-call-application-api

Building The API

Generate JWT Keypair

This project will be using a mobile app built in React Native.

You'll need to authenticate the user between the mobile application and the API. This project uses JWT to handle authentication, so certificates need to be generated to make the JWT tokens.

In the root of your project, run the following three commands:

mkdir -p API/var/jwt # Creates a directory to store your private and public key files.
openssl genpkey -out API/var/jwt/private.pem -aes256 -algorithm rsa -pkeyopt rsa_keygen_bits:4096 # Generates your private key file
openssl pkey -in API/var/jwt/private.pem -out API/var/jwt/public.pem -pubout # Generates the public key file

Exposing Your Application to the Internet

Making a phone call with Vonage requires a virtual phone number. You'll also want to set up a webhook to log the events that happen whenever a phone call is made, answered, rejected, or ended.

For this tutorial, ngrok is the service of choice to expose the application to the Internet. Install ngrok, and run the following command in a new Terminal window:

ngrok http 8080 # Creates an http tunnel to the Internet from your computer on port 8080

Make sure to copy your ngrok HTTPS URL, as you'll need this later when configuring the project.

Environment Variables

Inside the Docker directory is a file called .env.dist; copy or rename this file to .env.

The first fields to update are your database credentials. The example below shows the credentials I've used for this tutorial, but please use more secure ones.

DATABASE_URL=mysql://db_user:db_password@mysql:3306/on_call?serverVersion=8.0

MYSQL_DATABASE=on_call
MYSQL_USER=db_user
MYSQL_PASSWORD=db_password
MYSQL_ROOT_PASSWORD=root_password

Update the values for both VONAGE_API_KEY= and VONAGE_API_SECRET=, which you can find inside the Vonage Developer Dashboard.

Then, in the dashboard, navigate to "Your Applications". Create a new application, making sure to download the private.key file to the project's root directory, and ensuring your application has voice capabilities.

You need to set the Event webhook URL when using the Voice API. Set this to the ngrok HTTPS URL you copied in the last section.

Update the following two:

VONAGE_APPLICATION_PRIVATE_KEY_PATH=/var/www/API/private.key
VONAGE_APPLICATION_ID=<Vonage Application ID>

Next, link your previously purchased Vonage virtual number to your application. Then in your code, update the following inside your .env file inside Docker:

VONAGE_BRAND=OnCallAlerts
VONAGE_NUMBER=<Your Vonage Virtual Number>

JWT_PASSPHRASE=<Your JWT Passphrase>

Finally, find ON_CALL_NUMBER= in the same file, and add your phone number to this value. It will need to be a real number and able to receive SMS messages and voice calls.

Start Docker

Run the following five commands—the comments to the right of each describe what they do:

cd Docker
docker-compose up -d # To start all Docker containers for this project
docker-compose exec php bash # To create a tunnel into your PHP container
composer install # Installing all third-party libraries used in this project
php bin/console doctrine:migrations:migrate # Creates the user table already defined in `/API/migrations`

Time to Build the API!

Make Database Entities

There are three new database tables for this project. Alerts, OnCall, and a table to link Alerts and Users together, UserAlerts.

To start, run the command below and follow the instructions for input below:

php bin/console make:entity

For each field, please add the following:

Class name: Alert
Property name: title (String, 255, Not null)
Property name: description (String, 255, Not null)
Property name: status (String, 255, Not null)

When the command is complete, open the new file: src/Entity/Alert.php

There are three other classes used within this new Entity file. Add these imports at the top of the file:

use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\Common\Collections\Collection;
use Gedmo\Timestampable\Traits\TimestampableEntity;

One of these new classes is the TimestampableEntity, which adds created_at and updated_at fields to the database. Add use TimestampableEntity; at the top of the class, as shown below:

class Alert
{
    use TimestampableEntity;

We need to add some default values within the class, so create a new construct and default the values as shown below:

    public function __construct()
    {
        $this->status = 'raised';
        $this->createdAt = new \DateTime();
        $this->updatedAt = new \DateTime();
    }

While we're in this class, add the two functions below.

The getUserAssigned() function determines which user is the current user responsible for the alert. The second function, toArray(), converts the values of the class into an array, ready for the API responses.

    public function getUserAssigned(): ?User
    {
        if ($this->getUserAlerts()->isEmpty()) {
            return null;
        }

        return $this
            ->getUserAlerts()
            ->first()
            ->getUser();
    }

    public function toArray()
    {
        return [
            'id' => $this->getId(),
            'title' => $this->getTitle(),
            'description' => $this->getDescription(),
            'status' => $this->getStatus(),
            'dateRaised' => $this->getCreatedAt()->format('Y-m-d H:i:s'),
            'assigned' => $this->getUserAssigned()->getName(),
            'incidentId' => $this->getId()
        ];
    }

To make the OnCall entity, which we're using to store which person is on call each week, run the command below and follow the instructions for input as listed:

php bin/console make:entity

For each field, please add the following:

Class name: OnCall
Property name: user (relation, User, ManyToOne, Not null, Add Property to User Yes)
Property name: startDate (datetime, Not null)
Property name: endDate (datetime, Not null)

When the command is complete, open the new file: src/Entity/OnCall.php

There is one other class used within this new Entity file. Add this import at the top of the file:

use Gedmo\Timestampable\Traits\TimestampableEntity;

One of these new classes is the TimestampableEntity, which adds created_at and updated_at fields to the database, add use TimestampableEntity; at the top of the class as shown below:

class OnCall
{
    use TimestampableEntity;

We need to add some default values within the class, so create a new construct and default the values as shown below:

    public function __construct()
    {
        $this->createdAt = new \DateTime();
        $this->updatedAt = new \DateTime();
    }

To link your User and Alert entities together, you need to create a new Entity called UserAlert. Follow the instructions below:

php bin/console make:entity

Class name: UserAlert
Property name: user (relation, User, ManyToOne, Not null, Add Property to User Yes)
Property name: alert (relation, Alert, ManyToOne, Not null, Add Property to Alert yes)
Property name: smsSentAt (datetime, null)
Property name: voiceSentAt (datetime, null)

When the command is complete, open the new file: src/Entity/UserAlert.php

There is one other class used within this new Entity file. Add this import at the top of the file:

use Gedmo\Timestampable\Traits\TimestampableEntity;

One of these new classes is the TimestampableEntity, which adds created_at and updated_at fields to the database, add use TimestampableEntity; at the top of the class as shown below:

class UserAlert
{
    use TimestampableEntity;

We need to add some default values within the class, so create a new construct and default the values as shown below:

    public function __construct()
    {
        $this->createdAt = new \DateTime();
        $this->updatedAt = new \DateTime();
    }

Run the Migrations!

It's now time to make and run the migrations, creating new tables and columns in your database to reflect these newly created entities.

In your Terminal run:

php bin/console make:migration
php bin/console doctrine:migrations:migrate # If you wish to see what is being migrated, check the `API/migrations/` files for the SQL query

Make DataFixtures

We need to make some predefined fixtures for the OnCall database table to determine who is on call at a certain time. To do so, run the following command and follow the instructions listed:

php bin/console make:fixture

Entering the name OnCallFixtures will create a file inside API/src/DataFixtures called OnCallFixtures.php. Replace the contents of this file with the following:

<?php

namespace App\DataFixtures;

use App\Entity\OnCall;
use Carbon\CarbonImmutable;
use Doctrine\Bundle\FixturesBundle\Fixture;
use Doctrine\Common\DataFixtures\DependentFixtureInterface;
use Doctrine\Persistence\ObjectManager;

class OnCallFixtures extends Fixture implements DependentFixtureInterface
{
    public function load(ObjectManager $manager)
    {
        $currentWeek = CarbonImmutable::now();

        $onCall = new OnCall();
        $onCall
            ->setUser($this->getReference('user_1'))
            ->setStartDate($currentWeek->startOfWeek())
            ->setEndDate($currentWeek->endOfWeek());

        $manager->persist($onCall);

        $manager->flush();
    }

    public function getDependencies(): array
    {
        return [
            UserFixtures::class,
        ];
    }
}

Let's run your fixtures so that we have a user and an on-call record! In your terminal run:

php bin/console doctrine:fixtures:load

Make Form

When handling an API request for raising an alert, we need to validate the input to ensure it's what we expect. With Symfony, the easiest way to do this is by using a Form. With a Form, we can define what values we expect and any constraints on these values. Start by running the command below:

php bin/console make:form

Follow the instructions, as shown in the image:

Now, open the newly created AlertType.php file found within src/Form/ and replace the contents of the file with:

<?php

namespace App\Form;

use App\Entity\Alert;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Validator\Constraints\NotBlank;
use Symfony\Component\Validator\Constraints\Length;

class AlertType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('title', TextType::class, [
                'required' => true,
                'constraints' => [
                    new Length(['min' => 5]),
                    new NotBlank()
                ]
            ])
            ->add('description', TextType::class, [
                'required' => true,
                'constraints' => [
                    new Length(['min' => 5]),
                    new NotBlank()
                ]
            ])
        ;
    }

    public function configureOptions(OptionsResolver $resolver)
    {
        $resolver->setDefaults([
            'data_class' => Alert::class,
            'csrf_protection' => false,
        ]);
    }
}

The new code you've added to the AlertType class adds further constraints and requirements on the two fields in this form, title and description, to ensure they have a minimum length and are not blank.

Build a Vonage Util

A Utility class is needed to handle Vonage API requests when sending SMS messages and making voice calls.

In API/src, create a new directory called Util, along with a new file within this new directory called VonageUtil.php

You've already stored your Vonage credentials in the .env file earlier in this tutorial, and you'll be making use of these in this new PHP class.

In the new file add the following code:

<?php

namespace App\Util;

use Vonage\Client;
use Vonage\SMS\Message\SMS;
use Vonage\Voice\Endpoint\Phone;
use Vonage\Voice\NCCO\NCCO;
use Vonage\Voice\NCCO\Action\Talk;
use Vonage\Voice\OutboundCall;

class VonageUtil
{
    /**
     * @var Client
     */
    protected $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }
}

Right now, this code initialises a new PHP Class and creates a new client for Vonage API, using the Vonage Symfony wrapper for the PHP SDK.

Next, within this class, you're going to want to add two new functions, which will handle making the request to the API to send an SMS or make a voice call. Add the following two:

    public function sendSms(string $to, string $from, string $text): bool
    {
        $response = $this->client->sms()->send(
            new SMS($to, $from, $text)
        );

        $message = $response->current();

        if ($message->getStatus() == 0) {
            return true;
        }

        return false;
    }

    public function makePhoneCall(string $to, string $from, string $text)
    {
        $outboundCall = new OutboundCall(
            new Phone($to),
            new Phone($from)
        );

        $ncco = new NCCO();
        $ncco->addAction(new Talk($text));
        $outboundCall->setNCCO($ncco);

        $this->client->voice()->createOutboundCall($outboundCall);
    }

Build the Webhook Controller

Before making the controller, we're going to need a Repository function to pull specific data from the database. Open the OnCallRepository.php found within src/Repository. Inside the class below the __construct() function, add the new function findCurrentOnCall which will find the current user on call.

    public function findCurrentOnCall(\Carbon\Carbon $date)
    {
        return $this->createQueryBuilder('o')
            ->andWhere('o.startDate <= :date')
            ->andWhere('o.endDate >= :date')
            ->setParameter('date', $date->format('Y-m-d H:i:s'))
            ->getQuery()
            ->getOneOrNullResult();
    }

We've created the functionality to pull the data. Next, let's create a controller to handle any requests and pull the data.

First, in your Terminal, run the following:

php bin/console make:controller

When asked for the name of your controller, input WebhookController.

Open the newly created file: API/src/Controller/WebhookController.php.

We will be using all of the following classes, so let's make sure we include them from the beginning. At the top of the file, just below namespace App\Controller; add the following:

use App\Entity\Alert;
use App\Entity\OnCall;
use App\Entity\UserAlert;
use App\Form\AlertType;
use App\Util\VonageUtil;
use Carbon\Carbon;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\EventDispatcher\EventDispatcher;
use Symfony\Component\Form\Form;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;

Your class needs a construct for Symfony to inject the EntityManager and the VonageUtil classes. At the top of your class, add:

    /** @var VonageUtil */
    protected $vonageUtil;

    /** @var EntityManagerInterface */
    private $entityManager;

    public function __construct(
        VonageUtil $vonageUtil,
        EntityManagerInterface $entityManager
    ) {
        $this->vonageUtil = $vonageUtil;
        $this->entityManager = $entityManager;
    }

Now replace the index() function with the code below to create new alerts. This new function handles the POST request body, creates this data as a new Alert, and passes that alert into the Form to validate the values. If all is as expected, it will then create a new UserAlert, with the person currently on call as the person receiving the alert.

    /**
     * @Route("/webhooks/raise_alert", name="raise_alert", methods={"POST"})
     */
    public function index(Request $request): JsonResponse
    {
        $data = json_decode($request->getContent(), true);

        // Create an alert.
        $alert = (new Alert())
            ->setStatus('raised');

        $form = $this->createForm(AlertType::class, $alert);
        $form->submit($data);

        if ($form->isSubmitted() && $form->isValid()) {
            $entityManager = $this->getDoctrine()->getManager();
            $entityManager->persist($alert);
            $entityManager->flush();

            // Get the on call user
            $onCall = $this->entityManager
                ->getRepository(OnCall::class)
                ->findCurrentOnCall(Carbon::now());

            if (!$onCall) {
                return new JsonResponse(['message' => 'No Alerts found.'], 400);
            }

            // Create a UserAlert
            $userAlert = (new UserAlert())
                ->setUser($onCall->getUser())
                ->setAlert($alert);
            $entityManager->persist($userAlert);

            // Notify the on call user
            $this->vonageUtil->sendSms(
                $onCall->getUser()->getPhoneNumber(),
                getenv('VONAGE_BRAND'),
                'A new alert has been raised, please log into the mobile app to investigate.'
            );

            // Save this update to the user alert
            $userAlert->setSmsSentAt(Carbon::now());

            $entityManager->flush();

            return new JsonResponse([], 201);
        }

        return new JsonResponse($this->getErrorMessages($form), 400);
    }

You may have noticed that the function $this->getErrorMessages() is called at the bottom, but your class doesn't have it yet. You'll need to add this function next. It will retrieve all the form errors found when the endpoint is triggered, but some data is missing. Below your index() method, add the following:

    private function getErrorMessages(Form $form): array
    {
        $errors = [];

        foreach ($form->getErrors() as $key => $error) {
            if ($form->isRoot()) {
                $errors['#'][] = $error->getMessage();
            } else {
                $errors[] = $error->getMessage();
            }
        }

        foreach ($form->all() as $child) {
            if (!$child->isValid()) {
                $errors[$child->getName()] = $this->getErrorMessages($child);
            }
        }

        return $errors;
    }

We're at a point where we can test this now!

Test the Authentication

There are two endpoints at this part of the tutorial that we can test with our API, so with Docker still running in the background, make a POST request to http://localhost:8080/api/login_check with the JSON body of:

{
    "username": "dev+1@company.com",
    "password": "test_pass"
}

The response will be a JSON object with a key token, and the value is a JWT token.

The image below shows an example of doing this with Postman:

Test Raising an Alert

You don't need to be authenticated in this example to raise an alert, so no need to use the JWT from the previous example.

To raise an alert, update the URL field: http://localhost:8080/webhooks/raise_alert, keep the method as a POST request, and the JSON body of:

{
    "title": "ERRORRRRRR ASAP FIX NOW ITS BORKED",
    "description": "THE PAGE AINT LOADING TOP PRIORITY FIX ASAP."
}

The response will be an empty array and the HTTP status code of 201 (created). You can see an example of this request in Postman in the image below:

How to Handle an Alert

Symfony's Workflow component allows you to define a life cycle your object can go through with its statuses. Each step your object can go through is called a place, with the transitions defining the action the object needs to take to get from one place to another.

Workflows will allow you to define which places your alert can be in to get from being raised to the last step, which is either cancelled or completed.

Open the workflow.yaml file found within config/packages/ and replace the contents with the example below:

framework:
    workflows:
        alerts:
            type: 'state_machine'
            supports:
                - App\Entity\Alert
            marking_store:
                type: 'method'
                property: 'status'
            initial_marking: new
            places:
                - new
                - raised
                - accepted
                - cancelled
                - completed
            transitions:
                raise:
                    from: [new]
                    to: raised
                accept:
                    from: [raised]
                    to: accepted
                cancel:
                    from: [raised, accepted]
                    to: cancelled
                complete:
                    from: [accepted]
                    to: completed

A controller is now needed to handle all of the API requests regarding Alerts. So, run the command below to start making our new AlertsApiController:

php bin/console make:controller

When it asks for a Controller name, submit AlertsApiController. This command will create a new AlertsApiController.php file within src/Controllers. So open this new file.

We will be using all of the following classes, so let's make sure we include them from the beginning. At the top of the file, just below namespace App\Controller; add the following:

use App\Entity\Alert;
use Doctrine\ORM\EntityManagerInterface;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Workflow\Registry;

Add your class based routing as shown in the example below, so that any routes within this class are prefixed with /api/alerts/:

/** 
 * @Route("/api/alerts")
 */
class AlertsApiController extends AbstractController
{

This controller will use the $workflowRegistry and $entityManager in several places of this class, so to avoid rewriting code in several places, we'll place these inside the construct. Add the following code to the top of your class:

    /** Registry */
    private $workflowRegistry;

    /** EntityManagerInterface */
    private $entityManager;

    public function __construct(Registry $workflowRegistry, EntityManagerInterface $entityManager)
    {
        $this->workflowRegistry = $workflowRegistry;
        $this->entityManager = $entityManager;
    }

When the controller was created, a function named index() was automatically added. We're not going to need it for this project, so delete that function.

Now we'll create our listAction() which will retrieve all alerts from the database and return them as a JSON response. Add the listAction() to your controller as shown below:

    /**
     * @Route("", methods={"GET"})
     */
    public function listAction(): JsonResponse
    {
        $data = $this->entityManager
            ->getRepository(Alert::class)
            ->findAll();

        $alerts = [];

        foreach ($data as $alert) {
            $alerts[] = $alert->toArray();
        }

        return new JsonResponse(
            $alerts, 
            JsonResponse::HTTP_OK
        );
    }

Next, we'll create readAction() to retrieve one alert by ID from the database and return it as a JSON response. Add readAction() to your controller as shown below:

    /**
     * @Route("/{id}", methods={"GET"})
     */
    public function readAction(int $id): JsonResponse
    {
        $alert = $this->entityManager
            ->getRepository(Alert::class)
            ->findOneById($id);

        if (!$alert) {
            return new JsonResponse(
                null,
                JsonResponse::HTTP_NOT_FOUND
            );
        }

        return new JsonResponse(
            $alert->toArray(), 
            JsonResponse::HTTP_OK
        );
    }

We'll create our acceptAction(), which will find an alert by ID from the database; if one is found, it will try to transition the status of this alert from pending to accepted. The response will be an empty JSON response with the HTTP status code of 200.

Add the acceptAction() to your controller as shown below:

    /**
     * @Route("/{id}/accept", methods={"POST"})
     */
    public function acceptAction(int $id): JsonResponse
    {
        $alert = $this->entityManager
            ->getRepository(Alert::class)
            ->findOneById($id);

        if (!$alert) {
            return new JsonResponse(null, JsonResponse::HTTP_NOT_FOUND);
        }

        $workflow = $this->workflowRegistry->get($alert);

        try {
            $workflow->apply($alert, 'accept');

            $this->entityManager->flush();
        } catch (LogicException $exception) {
            return new JsonResponse(['message' => $exception->getMessage()], 400);
        }

        return new JsonResponse([], 200);
    }

Next, we'll create our completeAction(), which will find an alert by ID from the database; if one is found, it will try to transition the status of this alert from accepted to completed. The response will be an empty JSON response with the HTTP status code of 200.

Add the completeAction() to your controller as shown below:

    /**
     * @Route("/{id}/complete", methods={"POST"})
     */
    public function completeAction(int $id): JsonResponse
    {
        $alert = $this->entityManager
            ->getRepository(Alert::class)
            ->findOneById($id);

        if (!$alert) {
            return new JsonResponse(null, JsonResponse::HTTP_NOT_FOUND);
        }

        $workflow = $this->workflowRegistry->get($alert);

        try {
            $workflow->apply($alert, 'complete');

            $this->entityManager->flush();
        } catch (LogicException $exception) {
            return new JsonResponse(['message' => $exception->getMessage()], 400);
        }

        return new JsonResponse([], 200);
    }

Finally, we'll create our cancelAction(), which will find an alert by ID from the database; if one is found, it will try to transition the status of this alert from accepted or pending to cancelled. The response will be an empty JSON response with the HTTP status code of 200.

Add the cancelAction() to your controller as shown below:

    /**
     * @Route("/{id}/cancel", methods={"POST"})
     */
    public function cancelAction(int $id): JsonResponse
    {
        $alert = $this->entityManager
            ->getRepository(Alert::class)
            ->findOneById($id);

        if (!$alert) {
            return new JsonResponse(null, JsonResponse::HTTP_NOT_FOUND);
        }

        $workflow = $this->workflowRegistry->get($alert);

        try {
            $workflow->apply($alert, 'cancel');

            $this->entityManager->flush();
        } catch (LogicException $exception) {
            return new JsonResponse(['message' => $exception->getMessage()], 400);
        }

        return new JsonResponse([], 200);
    }

To summarise, we've added a configuration to our project that controls our alert's flow through its lifecycle. We've then created an API controller that will allow us to retrieve a list of our alerts, retrieve a specific alert, accept, decline, cancel or complete the alerts depending on their status.

Create the Escalation Command

What if the SMS hasn't been received? Or is it ignored?! Well, worry not! The next step is to implement a Symfony Command that will run as a time-based job scheduler (Cron job) and escalate all alerts older than 10 minutes.

Before creating this command, we'll need to add a repository method to retrieve alerts requiring escalation. Open your UserAlertRepository.php file within API/src/Repository/.

At the top of this file, add some more third party libraries for importing:

use App\Entity\Alert;
use App\Entity\UserAlert;
use Carbon\Carbon;

Next, add the repository method to retrieve all alerts that have had an SMS sent over 10 minutes ago but are still in the status of raised:

    public function findRaisedUserAlerts()
    {
        $queryBuilder = $this->createQueryBuilder('ua');
        $lastAlertSent = (Carbon::now())
            ->sub('10 minutes');

        return $queryBuilder
            ->join(Alert::class, 'a', Join::WITH, $queryBuilder->expr()->andX(
                $queryBuilder->expr()->eq('a', 'ua.alert'),
                $queryBuilder->expr()->eq('a.status', ':alertStatus')
            ))
            ->where($queryBuilder->expr()->isNull('ua.voiceSentAt'))
            ->andWhere($queryBuilder->expr()->lte('ua.smsSentAt', ':smsSentAt'))
            ->setParameter('alertStatus', 'raised')
            ->setParameter('smsSentAt', $lastAlertSent->format('Y-m-d H:i:s'))
            ->getQuery()
            ->getResult();
    }

This new Symfony Command will escalate all retrieved alerts. To create it, run the following command in your Terminal:

php bin/console make:command

When asked for the command name, enter app:escalate-alert, which creates a new file called EscalateAlertCommand.php within API/src/Command. Open this new file.

We will be using all of the following classes, so let's make sure we include them from the beginning. At the top of the file, just below namespace App\Command; add the following:

use App\Entity\UserAlert;
use App\Util\VonageUtil;
use Carbon\Carbon;
use Doctrine\ORM\EntityManagerInterface;

The class needs two objects injecting into it, the VonageUtil and EntityManagerInterface. With Symfony, the easiest way to do this is via the constructor. At the top of your class, add the following functionality:

    /** @var VonageUtil */
    protected $vonageUtil;

    /** @var EntityManagerInterface */
    private $entityManager;

    public function __construct(
        VonageUtil $vonageUtil,
        EntityManagerInterface $entityManager
    ) {
        $this->vonageUtil = $vonageUtil;
        $this->entityManager = $entityManager;

        parent::__construct();
    }

Now it's time to write the functionality for this command. It will retrieve all Alerts with an SMS sent over 10 minutes ago, but still with raised status. If there are any of these, it will retrieve the user assigned to the alert and send them a Text-To-Speech voice call notification. Replace current functionality within protected function execute() with:

        $io = new SymfonyStyle($input, $output);

        $userAlertRepository = $this->entityManager->getRepository(UserAlert::class);
        $userAlerts = $userAlertRepository->findRaiseduserAlerts();

        if (!$userAlerts) {
            $io->warning('There are no alerts needing to be raised.');
        }

        /** @var UserAlert $userAlert */
        foreach ($userAlerts as $userAlert) {
            $this->vonageUtil->makePhoneCall(
                $userAlert->getUser()->getPhoneNumber(),
                getenv('VONAGE_NUMBER'),
                'A new alert has been raised, please log into the mobile app to investigate.'
            );

            $userAlert->setVoiceSentAt(Carbon::now());
            $this->entityManager->flush();
        }

        return Command::SUCCESS;

Test the API

Your user needs authenticating to test these new endpoints.

First, make sure you get your JWT token by sending a POST request to http://localhost:8080/api/login_check with your fixtured users credentials.

Once you've copied your JWT, update the type to be a GET request and the URL to be http://localhost:8080/api/alerts. You need to provide a header with the key Authorisation and the value as Bearer <JWT> replacing <JWT> with your token.

The list Alerts endpoint returns a JSON array, which you can see in the Postman example below:

Let's keep that alert in its current state and use it later when testing the mobile application.

You've built an API; it's now time to create the mobile application.

Build the Mobile App

Update config.json where the value of the APIURL is the ngrok URL you saved previously.

Open a new Terminal window and run the following commands:

cd MobileApp
npm install
expo start

After a little while, a web browser opens. On the left-hand side, there are multiple options to run the application through, whether on your mobile device, iOS simulator or Android simulator. Choose the option that suits you, and when the application boots up, the Login Screen will be the first screen you see.

The fixtured user's credentials in the database are:

username: dev+1@company.com
password: test_pass

As shown in the image below:

A successful log in won't currently do anything! We need to implement more screens first, but to double-check your login was correct, check your Terminal where you ran expo start. You should see the line: You Successfully logged in!.

Alerts API

Showing a List of Alerts

Inside the API directory, create a new file called alerts.js.

Add the example below, which imports the client.js file to use the functionality from getClient().

This new function called getAlerts() makes a request to the API on the endpoint /api/alerts. We can add the other API calls, accept, complete, and cancel alerts while we're here.

import { getClient } from "./client.js";

export function getAlerts() {
  return getClient()
    .then(function(client) {
      return client.get("/api/alerts");
    });
};

export function acceptAlert(alertId) {
  return getClient()
    .then(function(client) {
      return client.post(`/api/alerts/${alertId}/accept`);
    });
};

export function cancelAlert(alertId) {
  return getClient()
    .then(function(client) {
      return client.post(`/api/alerts/${alertId}/cancel`);
    });
};

export function completeAlert(alertId) {
  return getClient()
    .then(function(client) {
      return client.post(`/api/alerts/${alertId}/complete`);
    })
};

Now that we have the functionality to get the alerts, build the AlertsScreen component. Create a new file inside components/ called AlertsScreen.js.

import React, { Component } from 'react'
import { FlatList, Text, View, StyleSheet, StatusBar } from 'react-native'
import { TouchableOpacity } from 'react-native-gesture-handler';
import { getAlerts } from '../api/alerts.js'

class AlertsScreen extends Component {

}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    marginTop: StatusBar.currentHeight || 0,
  },
  header: {
    backgroundColor: '#03A5C9',
    padding: 10,
    borderTopLeftRadius: 20,
    borderTopRightRadius: 20,
  },
  body: {
    padding: 10,
    borderBottomLeftRadius: 20,
    borderBottomRightRadius: 20,
  },
  item: {
    marginVertical: 8,
    marginHorizontal: 16,
    paddingBottom: 10,
    borderWidth: 1,
    borderRadius: 20
  },
  title: {
    fontSize: 24,
  },
  incidentId: {
    textAlign: 'right'
  }
});

export default AlertsScreen;

We now have an empty AlertsScreen class and some styling. Lets add to this class to show something:

  state = {
    alerts: []
  }

  renderItem = ({ item }) => (
    <View style={styles.item}>
      <TouchableOpacity onPress={() => this.onPress(item)}>
        <View style={styles.header}>
          <Text style={styles.title}>
            {item.title}
          </Text>
        </View>
        <View style={styles.body}>
          <Text>
            {item.dateRaised}
          </Text>
          <Text>
            {item.assigned !== '' ? item.assigned : 'Unassigned'}
          </Text>
          <Text style={styles.incidentId}>
            #{item.incidentId}
          </Text>
        </View>
      </TouchableOpacity>
    </View>
  );

  render() {
    return (
      <View>
        <FlatList
          data={this.state.alerts}
          renderItem={this.renderItem}
          keyExtractor={item => item.id}
        />
      </View>
    );
  }

Ok, this is showing us our page. But it isn't retrieving any information and doesn't tell us what to do next!

Above your renderItem() method, add the following:

  componentDidMount() {
    getAlerts()
      .then(response => {
        return response.data.map(alert => ({
          id: `${alert.id}`,
          title: `${alert.title}`,
          description: `${alert.description}`,
          dateRaised: `${alert.dateRaised}`,
          assigned: `${alert.assigned}`,
          incidentId: `${alert.incidentId}`,
          status: `${alert.status}`
        }))
      })
      .then(alerts => {
        this.setState({ alerts: alerts });
      })
      .catch((err) => console.log(err));
  }

  onPress = (item) => {
    return this.props.navigation.navigate('Alert', {
      alert: item,
    })
  }

Showing a Specific Alert

Create a new file in components called AlertScreen.js, which shows the specific alert by ID.

import React, { Component } from 'react'
import { Text, View, ScrollView, StyleSheet, StatusBar, TouchableOpacity } from 'react-native'
import { acceptAlert, cancelAlert, completeAlert } from '../api/alerts.js'

class AlertScreen extends Component {
  state = {
    alert: {}
  }

  const = this.state.alert = this.props.route.params.alert;

  onPressComplete = () => {
    completeAlert(this.state.alert.id)
      .then(() => {
        this.setState({ alert: { ...this.state.alert, status: 'completed'} });
      })
      .catch((err) => console.log(err));
  }

  onPressCancel = () => {
    cancelAlert(this.state.alert.id)
      .then(() => {
        this.setState({ alert: { ...this.state.alert, status: 'cancelled'} });
      })
      .catch((err) => console.log(err));
  }

  onPressAccept = () => {
    acceptAlert(this.state.alert.id)
      .then(() => {
        this.setState({ alert: { ...this.state.alert, status: 'accepted'} });
      })
      .catch((err) => console.log(err));
  }

  render() {
    let buttons;

    if (this.state.alert.status === 'raised') {
      buttons = <View style={styles.buttonContainer}>
          <View style={styles.buttonView}>
            <TouchableOpacity
              style={styles.button}
              onPress={() => this.onPressAccept()}
              underlayColor='#fff'>
              <Text style={styles.actionText}>Accept</Text>
            </TouchableOpacity>
          </View>
          <View style={styles.buttonView}>
            <TouchableOpacity
              style={styles.button}
              onPress={() => this.onPressCancel()}
              underlayColor='#fff'>
              <Text style={styles.actionText}>Cancel</Text>
            </TouchableOpacity>
          </View>
        </View>
    } else if (this.state.alert.status === 'accepted') {
      buttons = <View style={styles.buttonContainer}>
          <View style={styles.buttonView}>
            <TouchableOpacity
              style={styles.button}
              onPress={() => this.onPressComplete()}
              underlayColor='#fff'>
              <Text style={styles.actionText}>Complete</Text>
            </TouchableOpacity>
          </View>
          <View style={styles.buttonView}>
            <TouchableOpacity
              style={styles.button}
              onPress={() => this.onPressCancel()}
              underlayColor='#fff'>
              <Text style={styles.actionText}>Cancel</Text>
            </TouchableOpacity>
          </View>
        </View>
    }

    return (
      <View style={styles.item}>
        <View style={styles.header}>
          <Text style={styles.title}>
            {this.state.alert.title}
          </Text>
        </View>
        <View style={styles.body}>
          <Text>
            Date Raised: {this.state.alert.raisedDate}
          </Text>
          <Text>
            Assignee: {this.state.alert.assigned !== '' ? this.state.alert.assigned : 'Unassigned'}
          </Text>
          <Text style={styles.incidentId}>
            Incident ID: #{this.state.alert.incidentId}
          </Text>
          <Text style={styles.status}>
            Status: {this.state.alert.status}
          </Text>
        </View>
        {buttons}
        <View style={styles.scrollView}>
          <ScrollView>
            <Text style={styles.text}>
              {this.state.alert.description}
            </Text>
          </ScrollView>
        </View>
      </View>
    );
  }
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    marginTop: StatusBar.currentHeight || 0,
  },
  header: {
    backgroundColor: '#03A5C9',
    padding: 10,
  },
  body: {
    padding: 10,
  },
  item: {
    paddingBottom: 10,
  },
  title: {
    fontSize: 24,
  },
  buttonContainer: {
    flex: 1,
    flexDirection: "row",
    alignItems: 'center',
    justifyContent: 'center',
    paddingBottom: 30
  },
  buttonView: {
    flex: 1,
    height: 10
  },
  button: {
    marginRight: 40,
    marginLeft: 40,
    marginTop: 10,
    paddingTop: 10,
    paddingBottom: 10,
    backgroundColor: '#1E6738',
    borderRadius: 10,
    borderWidth: 1,
    borderColor: '#fff'
  },
  actionText: {
      color: '#fff',
      textAlign: 'center',
      paddingLeft: 10,
      paddingRight: 10
  },
  text: {
    fontSize: 20,
  },
});

export default AlertScreen;

Your application currently has no instruction on how to show these two new screens you've created. In navigation/MainStackNavigator.js below import Login, add the following two lines:

import Alert from '../components/AlertScreen';
import Alerts from '../components/AlertsScreen';

Then below the Login Stack.Screen, add two new Screens:

        <Stack.Screen 
          name='Alerts' 
          component={Alerts} 
          options={{ title: 'Alerts Screen' }}
        />
        <Stack.Screen
          name='Alert'
          component={Alert}
          options={({route, navigation}) => (
            {headerTitle: 'Alert Screen', 
            route: {route}, 
            navigation: {navigation}}
          )}
        />

Back in your LoginScreen.js file, find the line showing: console.log('You Successfully logged in!'); and add the snippet below to redirect the user on a successful login.

  return this.props.navigation.navigate('Alerts');

Testing

To test this app in your Terminal, make sure you've navigated to the MobileApp directory, and run the following command:

expo start

After a little while, a web browser should open. On the left-hand side, there are multiple options to run the application through, whether it's on your mobile device, iOS simulator or Android simulator. Choose the option that suits you. When the application starts, the first screen you see is the Login screen.

The fixtured user's credentials in the database are:

username: dev+1@company.com
password: test_pass

On successful login, the next screen you see is the Alerts screen. However, this will be empty right now because, in the database, there aren't any alerts.

Now, retry logging into your mobile application. You'll see the new alert, and you'll also be able to click on this alert to be taken to a screen that shows more information.

You can also transition this alert, whether it is to be accepted or cancelled.

Conclusion

In this tutorial, we've learned how to build an API using a PHP framework called Symfony. We've also built a mobile application using React Native. Vonage's APIs allowed us to send notifications via SMS and Text-To-Speech voice calls. By applying all of these together, we've built ourselves a functional on-call application for developers or system administrators to be alerted when anything goes wrong. Having a webhook allows us to integrate our on-call system with multiple services to cover as many as possible.

Below are a few other tutorials we've written implementing the Vonage Voice API into projects:

As always, if you have any questions, advice or ideas you’d like to share with the community, then please feel free to jump on our Community Slack workspace. I'd love to hear how you've gotten on with this tutorial and how your project works.

Handle an Incoming Call With Go

Greg Holmes — Thu, 03 Dec 2020 13:59:38 +0000

In this tutorial, we're going to learn how to handle incoming phone calls using a JSON array of actions called Call Control Objects (NCCOs). This tutorial uses Go and the Voice API.

We'll write a server that will respond to the webhook endpoints Vonage sends when a call comes in, or an event is triggered. We'll then create a Vonage application that has voice capabilities, to route incoming voice calls to their destination.

You can find the code shown in this tutorial on the Go code snippets repository.

Prerequisites

A phone number
A Vonage Account
Go installed locally

Vonage API Account

This tutorial also uses a virtual phone number. To purchase one, go to Numbers > Buy Numbers and search for one that meets your needs. If you’ve just signed up, the initial cost of a number will be easily covered by your available credit.

Write the Code

When Vonage receives a voice call to your virtual number, it checks whether you have configured a webhook to route the voice call. This configuration is specific to your application, which you created and configured previously. You also configured an event webhook, which outputs any events in your Terminal such as whether the call was "ringing" or "answered".

Let's write the code that will handle any requests to these two webhooks. Create a file called receive-an-inbound-call.go and copy the following into this file:

package main

import (
    "encoding/json"
    "fmt"
    "net/http"

    "github.com/vonage/vonage-go-sdk/ncco"
)

func answer(w http.ResponseWriter, req *http.Request) {

    paramKeys, _ := req.URL.Query()["from"]

    MyNcco := ncco.Ncco{}

    talk := ncco.TalkAction{Text: "Thank you for calling " + string(paramKeys[0])}
    MyNcco.AddAction(talk)

    data, _ := json.Marshal(MyNcco)

    w.Header().Set("Content-Type", "application/json")
    w.Write(data)
}

func event(w http.ResponseWriter, req *http.Request) {

    paramKeys, _ := req.URL.Query()["status"]

    fmt.Println("Event status: " + paramKeys[0])
}

func main() {

    http.HandleFunc("/webhooks/answer", answer)
    http.HandleFunc("/webhooks/event", event)

    http.ListenAndServe(":8080", nil)
}

The code above contains three functions. The first function is "answer", which retrieves the number the call is coming from, creates a Talk Ncco Action with the string "Thank you for calling" along with the phone number of the caller. It'll then return this Ncco action as the response.

The second function is a handler for any event updates. For this tutorial, whenever the event webhook is triggers, the code will output the status of the event in your Terminal.

The third function is the "main" function, which creates a /webhooks/answer, and a /webhooks/event webhook URLs to run the relevant function for the request. The last part this code does is makes the code into a web server by listening on port 8080.

To test your application, run the command below:

go run receive-an-inbound-call.go

Now in your browser go to "http://localhost:8080/webhooks/answer". You will be greeted with your JSON array which is your NCCO as shown below:

[{"action":"talk","text":"Thank you for calling 447000000","bargeIn":false,"loop":1}]

The NCCO shown in the example above contains four fields to the array, which are described more in depth below:

"action":"talk" determines the type of action this NCCO is. It instructs Vonage that it's a talking action
"text":"Thank you for calling 447000000" instructs Vonage of the text body to talk in the voice call
"bargeIn":false instructs Vonage that the user cannot interrupt the talking until it has finished
"loop":1 instructs Vonage to only speak the text once

Expose the Project To the Internet

When the call comes in, Vonage will send an HTTP request to the webhook URL that is configured for the number, so this application should be accessible to the internet and so we are recommending Ngrok.

Launch Ngrok with the following command:

ngrok http 8080

Copy the https URL that ngrok uses, you will need this later. It will be similar to the example below:

https://abc1234.ngrok.io -> http://localhost:8080

Note This URL will be different every time you run the command if you're using the free plan. So you will have to update your application in the Dashboard each time you run the command.

Configure the Settings

Create an application in your Dashboard under "Your Applications". Give your new application a name and then select "Generate public and private key", this downloads the private.key file for you which you should then move the file to be alongside the code you are about to create.

Add Voice capabilities to the application and configure the URLs using the Ngrok URL you copied earlier. For the Answer URL, use [paste ngrok url]/webhooks/answer and for the Event URL [paste ngrok url]/webhooks/event.

You've purchased a Vonage virtual number, created a Vonage Application, and written the code to handle the webhook events. It's time to test your project!

Time to Test

We have configured our Vonage application and phone number to know how to handle inbound voice calls. We have also written a webhook inside receive-an-inbound-call.go to handle any inbound call requests. Now it's time to test this application. When you run the command below, it will start a web server with this webhook listening for the request. So run the command below to start testing our new application:

go run receive-an-inbound-call.go

When you call your virtual number, you will hear the words quoted back to you "Thank you for calling" followed by your phone number.

You've now created a Vonage application, rented a virtual phone number, and written some code to handle webhook calls to this new number. When you call the number, your code now adds a Text-To-Speech message to the call for you to hear.