Write to firstname.lastname@example.org.
iOS Mobile App Verification Sample App
The iOS mobile app verification sample app demonstrates how to integrate a user verification process into an existing native iOS application. It allows mobile iOS applications to verify an end user’s device and phone number without embedding the authentication credentials in the application where they can be easily hacked and taken. The service securely sends an SMS to the end user’s device and verifies the number.
The iOS sample app is discussed in the following sections:
- How it Works
- Sample App Walkthrough
- Implementing App Verification in Your Own App
- Error Handling
How it Works
At a high level, you send an SMS with a unique URL containing a URI scheme and hostname which are handled using deep links connected to the app’s view controller. The URL contains a security code which is extracted and sent for verification when the end user clicks it. If this method will not work, the sample app displays a way to allow for manual security code entry as well.
- The end user’s device requests a JWT token to be used for authentication with your server.
- Your server returns a JWT token to the device.
- The end user’s device sends a registration request using the device’s phone number and JWT token to initiate verification.
- Your server sends a request to TeleSign that an SMS message containing a verification link be sent to the end user. A response is sent back to your server containing a reference ID for the transaction.
- TeleSign sends an SMS to the end user’s device.
- The end user clicks the link provided in the SMS.
- An SMS containing the verification code provided in the link is sent to your server.
- You check the code against what you received in the response from your initial request for an SMS message. If confirmed, you verify the end user and save the registration token for future use. Otherwise, you deny verification.
To see the sample app, you need the following:
- TeleSign customer ID and API key
- Swift 4.1 or higher
- iOS 11
To configure the application for review, do the following:
- Download or clone the repo from github - https://github.com/telesign/ios_app_verify
- In the Networking folder, open the SessionManager.swift file.
- Replace the customerId string with the one provided by TeleSign.
- Set the build scheme to Production.
- Build and run the project.
Sample App Walkthrough
This section quickly walks you through the sample app.
- Open the sample app.
Implementing App Verification in Your Own App
This section goes over resources and tips for setting up your own app properly.
There are two points in the app where authentication is required. You need to authenticate your end user’s app with your servers in order to kick off a request for an SMS, and you need to authenticate between your server and TeleSign in order to successfully send the SMS.
Authenticate Your Application with Your Server
There are a variety of ways you can securely authenticate your application with your server. The sample app uses a JWT service. You can use anything you would like to do this. If you want to do your own JWT service, TeleSign provides resources for a sample JWT server you can try out through the application. You cannot use this service in a production environment. You must build your own JWT service. Available TeleSign resources for working with JWT include:
Authenticate Your Server with TeleSign
To send a successful request for an SMS, you must correctly authenticate with TeleSign, and correctly integrate the TeleSign SMS API. Authentication methods available for TeleSign APIs (used when your server is contacting a TeleSign server) include:
Set Up the SMS API
To set up the SMS API, check out the following information for implementation:
Phone Number Formatting and the Country Code Picker
You should collect the phone number from your end user in a way that forces the correct formatting for the phone number. Make sure you implement with these best practices:
- Request the phone number in your app in a way that does not allow the end user to include special characters or spaces.
- Collect the country code and the rest of the phone number separately.
TeleSign provides you with a country code picker, displayed in the sample app. You can review the code for the country code picker in the following areas:
- AppVerifyDemo > View Controllers > CountryCodeViewController.swift
- Country Code Resources folder
- If you want to view code for the Country Code Picker online, you can review the CountryCodeViewController.swift to see how it is set up.
Verifying with Deep Links
To verify end users, you must set up your app to use deep links. For mobile apps, deep linking is a way to uniquely identify specific pages or locations in your app. This sample app uses deep links to send your end user a verification code. When the request for an SMS is kicked off, the SMS that goes to the end user’s device contains a deep link with the verification code. A response to the request for the SMS goes to your server containing the code that was sent in the link to the end user’s device. When the end user clicks the link, the app parses the code from the deep link and sends the code to your server. You then check the code against what’s on your server and if they match, you can verify the end user.
To do this using deep links, you need a unique URL for your app. The easiest way to construct unique URLs that will not overlap with other apps, is to base your link off of your apps bundle ID.
In the AppVerifyDemo folder, click on Info.plist. It will open in the window to the right.
Click Information Property List and go to the URL types section. Open the array to reveal the URL identifier.
Add your apps Bundle Identifier string to the URL identifier value.
Add a URL Schemes array beneath the URL Identifier and expand the array.
Add your intended URL prefix string (usually added to the Item 0 Key).
Open the DeepLinkManager.swift file within the Deep Linking folder.
Make sure the
appVerifyHoststring matches the value you added to your URL schemes.
You can also take a look at the following areas of the app for implementation details:
- Deep Linking folder
- AppDelegate.swift (very bottom of the file)
The sample app passes errors from the SMS request process between your server and TeleSign directly back to the app. Additionally, some error handling is added to deal with problems that can occur from trying to authenticate with a JWT token. Depending on what way you want to authenticate your end user to your servers, your error handling will vary.
You can review how error handling is dealt with in the Helper Classes folder in the TSError.swift file.