Friday, 11 September, 2020 UTC
Summary
As part of Twilio's account security offerings, the Twilio Verify API makes it simple to add user verification and Multiple Factor Authentication (MFA) to any user authentication flow. It supports One Time Passcodes (OTP) sent via voice, SMS, and email. App-based push authentication was also recently added to the Verify service.
Auth0 is a popular Identity Access Management (IAM) platform. If you are an Auth0 customer and want to use Twilio Verify for Multiple Factor Authentication (MFA), please read on.
This blog post will walk you through the steps of how to configure Auth0 to use Twilio Verify for MFA. It will use both Verify SMS channel and Voice channel to deliver OTPs so users can choose to receive the OTP via SMS or Voice.
What will you need? - Twilio Account. Log in or create one for free here.
- Twilio Verify Service. Create a service in the console.
- Auth0 Account.
- A mobile phone to receive SMS and voice OTP.
If you do not have a Twilio account and or an Auth0 account, you can sign up for a free Twilio account and a free Auth0 account.
Setting up a Verify Service Log in to the Twilio Console and then create a new Verify service. If you prefer you can also use Verify REST API to create a new Verify service. Please note down the following details. These will be used in Auth0 MFA configuration.
- Twilio Account SID (ACXXX…. ….)
- Twilio Auth Token (you can locate both Account SID and Auth Token at the home page after you login your Twilio account)
- The newly created Verify service SID (VAXXX… …)
Using Verify SMS OTP and Voice OTP in Auth0 requires the Custom Code feature. Please contact Twilio Sales to have this feature enabled.
Everything in Twilio has now been set up. Now let us head over to Auth0 Console.
Hooking Twilio Verify with Auth0 for MFA Log in to the Auth0 dashboard and click the Hook menu item on the left and click the CREATE A HOOK button to create a new hook, give it a name. In the example below, we name the hook as twilio-verify. Make sure you select Send Phone Message in the Hook drop down.
Now scroll down to the bottom of the page and click the Edit icon next to the newly created Hook (called twilio-verify in our case).
module.exports = function(recipient, text, context, cb) { const accountSid = context.webtask.secrets.TWILIO_ACCOUNT_SID; const authToken = context.webtask.secrets.TWILIO_AUTH_TOKEN; const verifySid = context.webtask.secrets.TWILIO_VERIFY_SID; const client = require('twilio')(accountSid, authToken); const verifyChannel=(context.message_type==="voice")? "call":context.message_type; client.verify.services(verifySid) .verifications .create({ to: recipient, channel:verifyChannel, customCode: context.code }) .then(function() { cb(null, {}); }) .catch(function(err) { cb(err); }); }; Delete everything in the code editor and copy above Javascript code (or download the code from my GitHub repository) and paste it there. Hit Save.
Now create three Hook Secrets (environmental variables). Click the wrench icon in the top left to open the Secrets menu:
- TWILIO_ACCOUNT_SID
- TWILIO_AUTH_TOKEN
- TWILIO_VERIFY_SID
and add the values from the above Setting up a Verify Service section.
The last step is to load the Twilio helper library. Click the wrench icon again and select NPM Modules. Search for Twilio helper library and add the module. At the time of writing this blog post, the latest version is 3.49.1. Auth0's module search should load the latest version, but you can check the latest version on npm.
Now you can test the hook implementation. Click the Run icon, replace recipient with your mobile number and change the code to “12345”, then click the Run button. You should now receive a SMS message with the code “12345”.
Configuring Auth0 MFA Click the Multifactor Auth menu item on the left. Next toggle on Phone Message, scroll down to the bottom, click the Require Multi-factor Auth drop down and select Always and hit Save.
Click Phone Message, the phone message pop-up windows will show. Select Custom in the Choose Delivery Provider, and then select SMS and Voice in Choose Delivery Method. Please note, if you only want to use SMS to deliver OTP, then select SMS in Choose Delivery Method instead. We are not going to use Enrollment Template and Verification Template, so you can leave them as it is. Now click Save to save the configuration.
Please note, don’t Select Twilio in the Choose Delivery Provider as it will use Twilio programmable SMS API rather than Twilio Verify API.
- Twilio Verify is a fully managed, turn-key global service optimised for OTP delivery to meet the high delivery, low latency requirements of OTP use cases.
- Unlike Twilio programmable SMS, Verify manages a dedicated pool of short codes and long codes, thus you do not need to buy and manage a pool of phone numbers.
- It Includes a secondary global network for failover and delivery optimization.
- It supports 38 languages for both SMS and Voice out of box.
You have now enabled Auth0 MFA.
End to End Testing with Auth0 Sample Application You can now test the end to end user experience using Auth0 sample application. In this example, I will use Auth0 JavaScript Single Page Application. Please login Auth0 and follow the instructions to download the application and configure it in Auth0.
In this example, I use both Database and Google connections for user login. I also added a test user account to the database and enrolled the user account including a mobile number to MFA.
Next, Click the Universal Login menu item and make sure you select New experience. You might also want to add your company logo.
Now, everything has been set up. Run the Single Page App and access it at https://127.0.0.0:3000/ You will see the welcome page. Click the Login button, your browser will be directed to Auth0 universal login page like the one below.
Sign in using email and password and click Continue. It will take you to the Verify Identity page where you can input the OTP that you receive on your mobile to complete the authentication.
Alternatively you can click the get a call link under the Continue button you will then receive a phone call and the OTP will be read out to you.
Congratulations! Your users now can login your MFA-enabled application with the OTP sent via Twilio Verify.
What’s Next? Interested to know more about Twilio Verify? Check out Twilio Verify API documentation online. Want to add Push authentication into your own mobile app? check out Verify Push SDK for iOS and Android.
If you have any questions, please leave a comment below or reach me on my GitHub. I can't wait to see what you build.
Dr Mingchao Ma has more than 15 years’ experience in Cybersecurity. In the account security team at Twilio he helps customers build solutions using Twilio Cloud security APIs. He previously worked at Microsoft UK helping financial sector customers adopt Microsoft Cloud security technologies. Before this he was a lead security architect at IBM UK. Mingchao has a PhD in information security, and cybersecurity certifications such as CISSP-ISSAP, CISM, SABSA etc. He is a Microsoft Certified Azure Solutions Architect Expert, Microsoft 365 Certified Enterprise Administrator Expert and Microsoft Certified Azure DevOps Engineer Expert.