Passport + Twilio: Two-factor authentication for Customer Identity Management
IBM is building the next generation cloud platform that provides necessary tools and services to application developers. IBM Cloud platform, built on open technology, gives developers the power they need to build without the traditional ‘do it yourself’ approach to feature development. When you build applications on IBM Cloud, you can leverage the ecosystem of tools they provide to add additional features to your application outside of your expertise.
Passport is a powerful customer identity and access management (CIAM) platform that is used by companies to reduce development costs and time-to-market. A key feature of Passport is multi-factor authentication, sometimes referred to as MFA.
A specific type of multi-factor authentication is two-factor authentication which utilizes two components to verify a user’s identity. The two components being something you know, such as your login credentials and something you possess. This particular type of multi-factor authentication will be the topic for the remainder of the article.
Traditionally, two-factor authentication requires an extra application or device that would generate a 6-digit code. For example, a user might have an application on their smartphone or an RSA code generator on a key fob. The generated code is then used to verify a user’s identity after they supply their username and password.
While this system works, it is often cumbersome for users to install and configure this application on their mobile phone. A simpler alternative is to utilize a push service to send a text message to the user’s mobile phone containing the code.
When we decided to add push notifications for two-factor authentication, it became clear that the transport for sending users a push notification with a security code does not line up with our core competency. Twilio has planted themselves firmly as a leader in messaging services, which made them an ideal choice to fill this gap for Inversoft.
Both Passport and Twilio are listed in the IBM Cloud Catalog and work together seamlessly to send push notifications containing two-factor codes to enable secure user authentication.
In this example, Passport and Twilio are used to develop a simple application with push notifications to deliver the two-factor verification codes. If you’re already a Passport customer, enabling the Twilio integration can be done with a few clicks. Let’s get started!
Create a simple login page that takes a username and password. In this case, the email is used as the username. I’m using React for this example. Below is the React component that supplies the login page and the corresponding rendered output.
The form above will be submitted by the user and the React component will make an AJAX request to Passport to authenticate the user. This request is made using the Login API. Here’s the AJAX code that makes the login API call to Passport:
The Login API will return a variety of HTTP status codes depending on the situation. For this example, the user has enabled two-factor authentication, and therefore Passport will respond with an HTTP status code of 242 that indicates the user’s credentials were valid. However, a two-factor code will be required to complete login.
Passport + Twilio
To enable the Twilio integration in Passport, navigate to Integrations by clicking on Settings and then Integrations and click on the Twilio icon. See the example below.
To configure Twilio in Passport you’ll need:
API URL (the URL to connect to the Twilio Service).
Account SID (Twilio account SID found on your Twilio dashboard)
Auth Token (Twilio authorization token found on your Twilio dashboard)
The phone number assigned to your Twilio account or the messaging service Id if you’re using the Copilot service
Once you have entered the required values, enter your mobile phone number in the Test configuration section to validate your configuration before saving your configuration. You should receive a message on your mobile phone that says You’ve successfully configured the Twilio integration for Passport. See the example below.
For this example, I created a user in Passport with my cell phone number and two-factor authentication enabled to test this portion of my code. This ensures that I receive a push message from Passport sent via Twilio when I login. This must be done through an API or a custom registration form. I used the User API to create my user.
Below is an example screenshot of the two factor code on my phone. The trial message will not be present on your production Twilio account.
To complete the process, create a form in the React app that will accept the code that was pushed to the user’s mobile phone and send it to Passport.
Here’s the React component to accept the two-factor code:
The form above will be submitted by the user and the React component will make an AJAX request to Passport to complete login by calling the Two Factor Login API.
This API returns a HTTP status code of 200 if the request was successful and the response also includes the User object and a JWT. If the code is incorrect, the HTTP status code will be 421.
Here is the AJAX code to make the API call to Passport. Notice it is nearly identical to the Login API except it takes a code and twoFactorId instead of loginId and password.
That’s it, you’re done! With just a few clicks and minimal code, two-factor authentication is successfully enabled using Twilio.
The code examples in this article are simplified to make them easier to understand. These examples can be found in a working example application on Github.