Add Nexmo Verify 2FA to any iOS or Android app on Appdome

Nexmo Verify is a service that lets you add multi-factor authentication to your application by verifying a PIN code sent to your device via an SMS message or voice call.

This Knowledge Base article provides step-by-step instructions for using Appdome to add Nexmo Verify to any Android and iOS mobile app.

About Appdome for Nexmo Verify

Nexmo Verify is a full-service two-factor authentication (2FA) solution from Nexmo/Vonage that enables businesses to validate the identity of users by sending them a randomly generated, single-use PIN code to their mobile device. Appdome and Nexmo have partnered to offer Nexmo customers an instant, no-code implementation of the Nexmo Verify service into any mobile app as part of Nexmo’s Accelerate offering. Using Appdome’s simple ‘click to integrate’ user interface, the Appdome platform enables anyone (developers or non-developers) to easily add Nexmo Verify 2FA to any iOS or Android app – instantly, without source code or development.

Using Appdome, there are no development or coding prerequisites. For example, there is no Appdome SDK, libraries, or plug-ins to implement. Users merely upload mobile apps, select the Nexmo Verify Identity Service and click “Build My App.” The Appdome technology adds Nexmo Verify MFA and more to the app automatically, with no manual development work at all.

Integrating Nexmo Verify Service using Appdome

Using Appdome’s no-code mobile solutions platform, there are 2 options to integrate the Nexmo Verify service into any mobile app:

1. Standard – MFA on Login

Using the “MFA on Login” method. With this method, the Nexmo Verify API is automatically triggered after the mobile user successfully authenticates to the app via their first factor (eg. username/password).  The Nexmo Verify service sends a one-time pin code to the mobile phone number on record. The user must then enter the pin code into the mobile app when prompted by the app.

2. Custom MFA

Using this method, developers can leverage the app’s own unique event structure to trigger the Nexmo Verify API. When an application is built with Custom MFA, the verification code will be promoted based on the user configuration from the mobile app.  When the application attempts to access a protected resource or if Appdome detects a successful Built app login with the configured Phone Number Tag, the verification code will be sent to the configured phone number.  This verification code will be sent via SMS or a voice call.

Additionally, with DEV-Events™ you can use Appdome to handle in-app events and complete Nexmo Verify authentication internally. For more information on how to use DEV-Events read this KB: Integrating your application with Appdome DEV-Events™ and Nexmo Verify 2FA service.

Prerequisites for Adding Nexmo Verify to Your  Mobile App

As a preliminary step to adding Nexmo Verify 2FA service to your mobile app using Appdome, Nexmo and Appdome customers are encouraged to verify their backend servers are configured correctly to work with the Nexmo Verify MFA service. To make it easy to tell if your servers are configured correctly, Appdome has created a simple Nexmo Environment app. For more information, please refer to the following KB article: Nexmo Environment App.

In order to use Appdome’s no code implementation of Nexmo Verify, you will need:

• Appdome account
• Mobile App (.ipa for iOS, or .apk or .aab for Android)
• Signing Credentials (e.g., signing certificates and provisioning profile)
• An account for the Nexmo Verify service, and the API Key and API Secret which you get from the Nexmo dashboard:

Nexmo Verify Request Workflow

Appdome allows you to automatically configure the Nexmo Verify request workflow which will provide the best chance of reaching your end-users.

Once triggered the Nexmo Verify API will begin the sequence of actions to reach the user with a PIN code. The sequence, a combination of SMS and TTS (Text-To-Speech) calls will stop only after successful verification. If the verification is unsuccessful, the sequence will continue and remain active until either the PIN has expired or three incorrect codes have been sent.

There are five available workflows:

• Workflow 1 (Default Workflow) : SMS -> TTS -> TTS
• Workflow 2 : SMS ->SMS -> TTS
• Workflow 3: TTS -> TTS
• Workflow 4 : SMS ->SMS
• Workflow 5 : SMS -> TTS

For more information on the time setting, please review  Nexmo Verify Workflows and Events.

How to Add Nexmo Verify MFA to Your mobile app

Please follow these steps to add a mobile app to your Appdome account.
If you don’t have an Appdome account, click here to create an account.

Using Appdome to Build Your Mobile App with Nexmo Verify

To Build an app with Nexmo Verify’s MFA, please follow the steps below:

Click the Build Tab. Note: a blue underline will appear showing the step is active. Select the Identity category

1. Click on the toggle to enable Identity Services, Select Nexmo Verify from the drop-down menu
2. Enter the API Key you got from Nexmo Dashboard
3. Enter the API Secret you got from Nexmo Dashboard

Option 1: Build your app with MFA on Login (Standard):

1. Click on the toggle to enable MFA on Login
   • By default, MFA on Login detects a phone number sent using a custom header named “X-PhoneNumber“
2. Select the Verify Workflow
3. Dynamic UI™ automatically enables Appdome to create the necessary UI dialogs to perform the verification process using Nexmo Verify

Login Detection Flow (MFA on Login)

The following diagram illustrates the Nexmo Verify Login detection flow for apps that have been integrated using Appdome:

1. The application performs the standard login sequence with its backend servers.
2. When the login sequence is successful, the server will/must return the user’s phone number in the payload to the mobile.
3. At this point, Appdome  identifies the successful login (according to the chosen ‘MFA on Login’ configuration method)
   • The app will not be allowed to communicate with its backend until the full 2FA auth sequence has been completed successfully.
   • Appdome sends the Nexmo verification request with all the preconfigured parameters
   • Appdome prompts the user using DynamicUI to enter the PIN code. This occurs via Appdome’s “DynamicUI feature” which adds the Nexmo UI screens automatically and adapts the Nexmo UI o take on the same ‘look and feel as the original app.
4. Nexmo’s APIs receive Appdome’s Verify the request and send a PIN code to the phone number (that was returned by the server backend and identified by Appdome) using the configured Nexmo workflow (defined on the Appdome platform). The PIN may be sent via SMS or TTS depending on the configured workflow.
5. The user receives the PIN code via SMS and enters it into the app after receiving a push notification asking for the code (sent by Appdome DynamicUI).
6. Appdome checks the verification code after the user enters it.
7. If the PIN code is valid, Appdome releases the network traffic and the application can continue with its normal flow (ie: the app is allowed to communicate with the backend and the user proceeds to use the app as expected).

Understanding the color-coding:

• Actions performed by the app are in green (these are all actions that were originally coded into the app)
• Actions performed by Appdome are in blue
• Actions performed by Nexmo are in orange

Option 2: Build Your App with Custom MFA:

1. Click on the toggle to enable Custom MFA
2. Enable Appdome in-app DEV-Events and complete Nexmo Verify authentication internally – for more information visit Integrating your application with Appdome DEV-Events™ and Nexmo Verify 2FA service.
3. Enable Authenticate on Resource and add the protected servers which will trigger the authentication process. (optional)
4. Enable Customize Login Detect and choose the method by which to detect the login and extract the phone number (optional):
   • Detect by Header: Enter the HTTP header name whose value is the user’s phone number.
   • Detect by JSON Body: Enter the JSON key whose value is the user’s phone number. This key will be searched for inside HTTP response payloads.
   • Detect by OAuth2 Access Token: allows detection of OAuth2 access tokens inside HTTP response payloads and querying the backend for the user’s phone number
     • Phone Number Query URL will hold the URL that will be queried for the user’s phone number
     • Phone Number JSON Tag will hold the JSON key whose value is the user’s phone number. This key will be searched for inside the query response payload.
   • None: Appdome will no perform login detect.
5. Select the Verify Workflow
6. Select “Custom API Key Change Notification” to customize the pop-up notification when the user entered the wrong Nexmo credentials.
7. (optional) Click on the toggle to enable DEV-Events on your app
8. Select the Nexmo Verify verification Pincode Length
9. Brand ID (optional): enter a string up to 18 characters which will be included in the verification SMS or voice call. If it is left blank, Appdome Nexmo implementation will use your application name, and the SMS show ” code: 1234. Valid for 5 minutes”.
10. Sender ID (optional): Enter the application’s brand identifier to appear as the SMS sending the contact.
11. API URL (optional): If you are using an alternative Nexmo server, enter here. Otherwise, leave blank. By default, Appdome’s Nexmo Verify implementation will use “https://api.nexmo.com“
12. Dynamic UI™ automatically enables Appdome to create the necessary UI dialogs to perform the verification process using Nexmo Verify

Click the Build My App button to complete Appdome’s Nexmo integration into the app.

The technology behind Build My App has two major elements – (1) a microservice architecture filled with 1000s of code sets needed for mobile integrations, and (2) an adaptive code generation engine that can recognize the development environment, frameworks and methods in each app and match the app to the relevant code-sets needed to add Nexmo Verify MFA to the mobile app in seconds.

Congratulations! Now you have a mobile app fully integrated with Nexmo Verify MFA.

What’s next? 

After you have added Nexmo Verify to any Mobile App on Appdome, there are a few additional steps needed to complete your mobile integration project.

Add Context™ to the Appdome-Built App

Appdome is a full-featured mobile integration platform. Within Context™, Appdome users can brand the app, including adding a favicon to denote the new service added to the app.
For more information on the range of options available in Context™, please read this knowledge base article.

Sign the Nexmo Verify enabled Appdome-Built App (Required)

In order to deploy an Appdome Built app, it must be signed. Signing iOS apps and Signing Android apps is easy using Appdome. Alternatively, you can use Private Signing, download your unsigned app and sign locally using your own signing methods.

Kai Kenan