Web Client SDK is in Pilot
This Web Client SDK component of Verify Push is currently in the Pilot maturity stage, which means that:
1. We're actively looking for early-adopter customers to try it out and give feedback. That could be you!
2. You'll need to contact sales to request access to the private GitHub repo containing the SDK code.
3. We're actively developing this SDK and it could change/break unexpectedly; please don't use in production. This just applies to this SDK; the rest of Verify Push is stable for production use.
This Twilio Verify Push Web Client Library (SDK) helps you verify users by adding a low-friction, secure, cost-effective, push verification or device approval factor into your own web/desktop app. It works by enrolling your app (e.g. Owlbank.com) running on a browser/device (e.g. Chrome on a Mac) into a secure key for Verify Push. When your app backend needs to verify that the user is who they say they are, you challenge the user via your app to prove that they still possess the secure key stored locally in the browser.
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 Web Client Library in your existing app and verify a user using Verify Push API. This Verify Push 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 app and backend.
In this Quickstart, you will learn how to:
- Sign up for Twilio
- Configure Push Credential and Verify Service
- Embed the client SDK into your app
- Setup your app backend
- Register a user and their device in Verify Push
- Configure webhooks
- 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.
This SDK can run in any app running in an environment with a JS engine that supports all of the following APIs:
- Web Crypto
This includes all web apps running in a Chrome or Edge browser (~73% market share). Electron-based desktop apps can also run the SDK.
Support for web apps running in other modern browsers like Firefox and Safari is expected soon.
Want a technical overview first?Technical Overview
Check out the Verify Push SDK Technical Overview to view its data model, sequence diagrams, and security FAQs.
Want to see an example?Run Sample App
If you don't want to setup Verify Push with your own app or backend immediately, we have built a Sample App embedded with the client Verify Push Web Client SDK and a Sample Backend using Twilio functions that you can run to see Verify Push in action. These samples can also be helpful for troubleshooting. Note that the Sample App is located in a private GitHub repo, so you need to contact sales to request access.
Already have a Twilio account? Go ahead and skip this section.
You can sign up for a free Twilio trial account here.
- When you sign up, you'll be asked to verify your personal phone number. This helps Twilio verify your identity.
- Once you verify your number, you'll be asked to create a project. For the sake of this tutorial, you can click on the "Learn and Explore" template. Give your project a name, or just click "skip remaining steps" to continue with the default.
- Once you get through the project creation flow, you'll arrive at your project dashboard in the Twilio Console. This is where you'll be able to access your Account SID, an authentication token, create a Push Credential, create a Verify Service and more.
For Verify Push to send push notifications to your web app, you will need to create a Firebase project to enable Firebase Cloud Messaging (FCM) in your project. Follow these steps to do it.
- If you haven't yet, sign up for Google's Firebase. We'll be using it as the base for our notification today. To use push notifications for your web apps, create a project on the Firebase Console. You can find more info here
- After you have a Firebase project, add your web app to it. You can find more instructions here.
Environments that don't support Firebase Cloud Messaging
The use of FCM to enable push notifications is supported in Chrome, Edge, and Firefox browsers, but not Safari (see "Cloud Messaging" row in the official documentation). When the SDK itself supports Safari, push notifications to it will be supported via APNs. Electron-based desktop apps also can't use FCM, but we're planning to support push notifications to it via WebSockets.
For Verify Push to send push notifications to your web app, you will need to create a Push Credential that contains your FCM secret. Follow these steps to do it in the Twilio Console.
- Click the
+button to add a new credential and a form will pop-up:
- Enter a friendly name, such as "Verify Quickstart App Credentials"
FCM push credentialsas type
- Enter the
FCM Secret. The value is your web app's
Server key. To find it, visit the Firebase Console, and then look in your app's project settings, under Cloud messaging
- Click the
- Note: Although Verify Push uses Twilio Notify for sending push notifications, you do not need to create your own Notify Service
- Go to Twilio Console > Verify > Services and create a new Service.
- Alternatively, you can select any existing Service. However, we recommend creating a new service for testing so you don't accidentally interfere with a production environment.
- From Twilio Console > Verify > Services, select your Service to access its Settings. Under the Push section, select the Credential SID(s) that you want this Service to use for sending push notifications. One SID can be selected for your Android app (FCM) and one for your iOS app (APN). For web apps, select the FCM credential SID.
You only need to configure and select an FCM credential for sending push notifications to web apps running on Chrome, Edge, and Firefox browsers.
Follow the installation steps in the README file of the Twilio Verify Web Client GitHub repo. Note that this is a private repo, please contact sales to request access. The installation steps will explain how to add the Web Client library to your project and setup your web app to work with Firebase Cloud Messaging (FCM).
After you import the Twilio Verify Web Client 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. Type or paste the sample code.
Your client-side 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 app to request the Access Token
2. Have your app backend request an Access Token from Verify Push API
3. Return the Access Token,
Verify Service SID to the app
Check out our Sample Backend using Twilio functions for an implementation example. In a production web application, you would restrict access token retrieval to the currently authenticated user, using whatever type of authentication your service already uses.
In the sidebar to the right (or below) is sample code for requesting an access token from the Verify Push API in all languages supported by Twilio helper libraries. You will need the Verify
service_sid, as well as the user id (such as a GUID or the user's primary key in your database table) you use as the
identity with this Verify service.
Do not use Personally Identifiable Information for
identity. Use an immutable user identifier like a UUID, GUID, or SID.
Verify Push uses
identity as a unique identifier of a user. You should not use directly identifying information (aka personally identifiable information or PII) like a person's name, home address, email or phone number, etc., as
identity because the systems that will process this attribute assume it is not directly identifying information.
Do not store your
Verify Service SID in your app. Get it from your backend, as well as the
identity. You can find an example in the Sample Backend using Twilio functions
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.
You don’t need to make a separate Create Entity call, because the Create Factor call will create an Entity and a Factor at the same time.
As getting the device registration token for push could happen in a different moment before creating the factor, please validate that your app has a registration token before using it as a
pushToken in the create factor method.
Configure a webhook callback for your app backend to be notified of events such as when a
Factor has been verified or when a
Challenge has been approved, so that it knows to advance the user to the next step in your flow. This is more real-time and efficient than constantly polling the Verify Push API for the
status of a
Follow the steps in this Verify Webhooks page.
Congratulations! Verify Push consists of two user sequences, and you've just completed the first one: user and device registration. The second sequence is to challenge and verify (authenticate) a user with their registered device. Read on for the step-by-step instructions.
Your web application backend needs to call the Verify Push API to create a
Challenge using the
Factor that you've just created. When the challenge is created, Verify Push sends a push notification to the registered device using the configured Push Credential.
The code in the sidebar to the right/bottom demonstrates how to create those challenges using the Twilio helper libraries.
You may choose to put Personally Identifiable Information (PII) or other sensitive information in
hidden_details. The data in each param will be stored per its retention policy listed in the Challenge resource.
- If you are sending push notifications, use the Notifications resource to resend a push notification if the first one fails for some reason. This is better than creating another duplicate Challenge.
Your app needs to read the contents of the push notification payload to obtain the
The following code snippet is run when there is an incoming FCM push notification, and if the type is
verify_push_challenge, read the parameters out of the notification. The push notification can be received when your app is in background or foreground.
Once your app receives the push notification containing the
challengeSid, it needs to retrieve the
challenge details that correspond to that sid. Type/paste the sample code below.
In an actual implementation, your 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 browser/device as the registered browser/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
denied. Type/paste the sample code below into your app.
By optionally implementing Silent Device Approval within the Verify Push Client Library, you can silently approve challenges without push notifications when your app already knows that the user is trying to complete an action (actively logging in, making a transaction, etc.) on the same device as the registered device that is being challenged. This results in an authentication that is completely invisible to the user. While implementation details will vary, here are some suggested steps:
- In order to be confident about the user's intent, the challenge approval should be done when the app is in foreground during the flow of the action that is being approved (e.g. immediately after the user taps "login").
- Identify the device starting the action and create a challenge for the factor linked to that device (a factor only represents one device).
- If you want to send challenges for multiple devices (factors) or if you want to be sure that you're approving the correct challenge, there are two options:
- Include the associated challenge sid for the action in the response to the device and validate that it's the expected challenge sid before approving it.
- Assign a transaction id to the started action and include it in the response to the device, and add the transaction id to the challenge's hidden details, so before approving the challenge you can get the challenge's hidden details to validate it is the expected challenge
- To receive the challenge on the client-side, you can:
- Implement a strategy to listen for incoming push notifications when the app is in foreground and after some seconds, poll for pending challenges just in case the push notification did not arrive.
- Poll for the latest pending challenge for an immediate approval, if your backend implementation can guarantee that the challenge was already created.
Once Verify Push API receives a Challenge update from your app, it will forward the update by sending a webhook callback (
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
This completes the second user sequence of Verify Push: Challenge and verify a user.
Now that you've verified your first user, check out the following resources to continue your Verify Push journey with Twilio:
- 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!