Verify Push iOS Client Library Quickstart

Twilio Verify Push Client Library (SDK) helps you verify users by adding a low-friction, secure, cost-effective, push verification or device approval factor into your own mobile application. It works by registering your user's iOS devices as a secure key via public-key cryptography. When your app backend needs to verify that the user is who they say they are, you challenge the user to prove that they still possess their secure key (iOS device). This still works even if the user has disabled push notifications (APNs), as your mobile app can poll for challenges via the SDK.

You can also perform Silent Device Approval authentications from the Client Library, which are invisible to the end-user and don’t require push notifications. See the How to Implement Silent Device Approval section for more information on implementing this strategy.

You can run the Verify Push iOS Client Library in your existing iOS app and verify a user using Verify Push API. This Quickstart will walk you through the entire process step-by-step, starting with setting up your Twilio account all the way through verifying a user using your existing iOS app and backend.

In this Quickstart, you will learn how to:

1. Sign up for Twilio
2. Configure Push Credential and Verify Service
3. Embed the client SDK into your iOS app
4. Setup your app backend
5. Register a user and their device in Verify Push
6. Configure webhooks
7. Verify a user

By the end of this Quickstart, you’ll have a solid foundation for implementing Verify Push or Silent Device Approval within your app and backend to verify users at login, transaction, and other sensitive actions.

Set up APNs for your iOS app (optional)

To configure push notifications, follow these Apple Push Notification service (APNs) setup steps.

Step 1 - Setup an App ID

Log into your Apple development account and click on Identifiers under the Certificates, IDs & Profiles. This will show a list of identifiers, including App IDs.

Option 1- Existing App ID

If your App ID is already on this list, click on it and a list of capabilities will be shown.

1. Check the 'Push Notifications' capability.
2. Don't worry about the Configure button right now, just click the Save button in the upper right.

Option 2- New App ID

If your App ID isn't on this list, click the "+" symbol to add a new App ID.

1. Choose App IDs and click the Continue button in the upper right.
2. Select App as type
3. Give your app a description as you see fit.
4. Give it an Explicit Bundle ID that matches the bundle identifier in Xcode (such as com.twilio.TwilioVerifyDemo).
5. Under Capabilities check Push Notifications
6. Click the Continue button
7. Click the Register button to confirm your new App ID and create it.

Be sure to add Push notifications and Remote notifications capabilities to your Xcode project

Step 2 - Create a Certificate

Now you will need to create a push notification certificate. This will enable your app to receive notifications. You can either make a development certificate or a production certificate. For this guide, we'll make a development certificate.

1. Add a certificate on the Apple Developer Portal
2. Under Services, select 'Apple Push Notification service SSL (Sandbox)'.
3. Click 'Continue'
4. Select the App ID you previously created.
5. Click 'Continue' again
6. It will prompt you to create a Certificate Signing Request, with instructions on how to do it in the 'Learn more' link. Create one.
7. Upload the Certificate Signing Request.
8. Click 'Continue' again
9. Click 'Download' to obtain your certificate.

Congrats! You just created an Apple Development iOS Push Services certificate. Now you can download it and double click on it locally to add it to your Keychain access.

Create a Push Credential

For Verify Push to send push notifications to your iOS app, you will need to create an Apple Push Notification (APN) Push Credential that contains your APN certificate and private key.

Get your certificate and private key

In Keychain Access, go to the 'Certificates' Category in the lefthand sidebar.

1. Right-click your push certificate. It should be labeled "Apple Development iOS Push Services" (or "Apple Push Services").
2. Choose "Export"
3. Save it as cred.p12. (Leave the password blank)

This is your credential file. We're going to extract your certificate key and private key from this file. We need these 2 keys to create a Twilio Credential.

Create a Certificate Key

Run the following command in terminal

openssl pkcs12 -in cred.p12 -nokeys -out cert.pem -nodes

Create a Private Key

Run the following command in terminal

openssl pkcs12 -in cred.p12 -nocerts -out key.pem -nodes

Process the RSA key

Run the following command in terminal

openssl rsa -in key.pem -out key.pem

Then you can use the certificate in the cert.pem file and the private key in the key.pem file to create a push credential

Create the push credential

Follow these steps to do it in the Twilio Console.

• Go to Twilio Console > Account > Keys & Credentials > Credentials > Push Credentials:

• Click the "Create new Credential" button to add a new credential and a form will pop-up:

• Enter a friendly name, such as "Verify Quickstart App Credentials"
• Select APN push credentials as type
• Enter the Certificate from the cert.pem
  • strip anything outside of "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" boundaries.
• Enter the Private key from the key.pem.
  • strip anything outside of "-----BEGIN RSA PRIVATE KEY-----" and "-----END RSA PRIVATE KEY-----" boundaries
• Check the Sandbox option
  • Your app should be signed with a development certificate to use sandbox
• Click the Create button
• Note: Although Verify Push uses Twilio Notify for sending push notifications, you do not need to create your own Notify Service

Embed the SDK into your iOS app

Follow the installation steps in the README file of the Twilio Verify iOS repo. The installation steps will explain how to add the iOS library to your project and setup your iOS app to work with Apple Push Notification service (APNs).

After you import the Twilio Verify iOS library, you can start to integrate your existing app with Verify Push.

To get started, you will need to create an instance of the TwilioVerify class, using its Builder. Do this by typing or pasting in the code sample.

Full source

Obtain a Verify Push API access token for your iOS app

Your iOS app needs to obtain an Access Token (technically an Enrollment JWE, similar to a JSON Web Token (JWT)) to make direct requests to the Verify Push API in the future. This Access Token request needs to be brokered by your app backend. To do this, you need to:

1. Expose an API endpoint in your app backend for your iOS app to request the Access Token

2. Have your app backend request an Access Token from Verify Push API

3. Return the Access Token, identity and Verify Service SID to the iOS app

Register a user and their device

Register a user and their device in Verify Push by creating and verifying a Factor. Type or paste the code samples for both of these steps.

Create a factor

Full source

Verify a factor

Full source

Poll for the Challenge

Read Push Notification (optional)

Your iOS app needs to read the contents of the push notification payload to obtain the challengeSid, factorSid, and message parameters.

Typically, you would do this either directly in the AppDelegate class, or you would create a new class that handled incoming push notifications that you reference in your AppDelegate class.

The following code sample runs when there is an incoming push notification, and if the type is verify_push_challenge, reads the parameters out of the notification.

Testing push notifications on simulators

You can test push notifications on simulators. The Xcode command-line tools allow you to send push notifications from the terminal, this command allows you to send a push notification to the iOS simulator:

xcrun simctl push --help
Send a simulated push notification
Usage: simctl push <device> [<bundle identifier>] (<json file> | -)

	bundle identifier
	     The bundle identifier of the target application
	     If the payload file contains a 'Simulator Target Bundle' top-level key this parameter may be omitted.
	     If both are provided this argument will override the value from the payload.
	json file
	     Path to a JSON payload or '-' to read from stdin. The payload must:
	       - Contain an object at the top level.
	       - Contain an 'aps' key with valid Apple Push Notification values.
	       - Be 4096 bytes or less.

Only application remote push notifications are supported. VoIP, Complication, File Provider, and other types are not supported.

The command requires the arguments:

• <device>: set this to booted to use the open simulator. You can also use a device identifier which you could get with the xcrun simctl list devices | grep Booted command.
• <bundle identifier>: bundle identifier of the app you are testing.
• <json file>: a JSON file containing the push notification details.

The JSON content for getting a challenge push notification is:

{
    "aps": {
        "alert": "<Challenge message>",
        "category": "verify_push_challenge"
    },
    "message": "<Challenge message>",
    "challenge_sid": "<challenge_sid>",
    "factor_sid": "<factor_sid>",
    "type": "verify_push_challenge"
}

• <Challenge message>: The message for the challenge
• <factor_sid>: A valid factor Sid, created in the device
• <challenge_sid>: A valid challenge Sid, created for the factor

Running this command for the sample app will be:

xcrun simctl push booted com.twilio.TwilioVerifyDemo payload.json

You can see an example here

Full source

Update the Challenge to verify the user

In an actual implementation, your iOS app should either display the Challenge details to the user and request confirmation that the Challenge is expected, or silently approve the Challenge, because your app already knows that the user is trying to login on the same device as the registered device that is being challenged.

In either case, the next step is for your app to call the Verify Push API directly and update the Challenge status as approved or denied. Type or paste the sample code into your iOS app.

Full source

For additional suggestions, see:

• Getting challenge's hidden details
• Full source for listening to incoming push notifications when the app is in foreground
• Poll for the challenge

Receive Challenge status

Once Verify Push API receives a Challenge update from your iOS app, it will forward the update by sending a webhook callback (challenge.approved or challenge.denied) to your app backend, so that it knows to take your user to the next step in your flow. If you don't have a webhook configured, you can poll the Verify Push API for the status of the Challenge.

This completes the second user sequence of Verify Push: Challenge and verify a user.

Congratulations!

Where to next?

Now that you've verified your first user, check out the following resources to continue your Verify Push journey with Twilio:

• Add Verify Push to your Android app by following the Android SDK Quickstart
• Prepare to go-live by reviewing Verify Push Best Practices for Production use
• Explore adding Verify's other verification channels beyond Push

We can't wait to see what you build!