Passport + Twilio: Two-factor authentication for Customer Identity Management

Security

12 February 2018 8 min read

By: Daniel DeGroff

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.

Multi-factor Authentication

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!

Tools Needed

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.

<br>
class Login extends Component {<br>
  render() {<br>
    return (<br>
      <div className="login" ><br>
        <form id="login"><br>
          <label><input id="loginId" name="loginId" type="text"/></label><br>
          <label><input id="password" name="password" type="password"/></label><br>
          <input type="submit" value="Login"/><br>
        </form><br>
       </div><br>
    );<br>
  }<br>
}<br>
export default Login;<br>

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. See documentation. Here’s the AJAX code that makes the login API call to Passport:

<br>
const xhr = new XMLHttpRequest();<br>
xhr.onreadystatechange = (function() {<br>
  if (xhr.readyState === XMLHttpRequest.DONE) {<br>
    if (xhr.status === 200) {<br>
      // Handle successful login<br>
    } else if (xhr.status === 242) {<br>
      // Handle 2FA Challenge<br>
    } else if (xhr.status === 400) {<br>
      // Input validation, missing required values<br>
    } else if (xhr.status === 404) {<br>
      // Invalid loginId or password<br>
    } else {<br>
      // Login failed for other reasons<br>
    }<br>
  }<br>
});<p></p>
<p>const request = {<br>
  loginId: 'cosmo@playtronics.com',<br>
  password: 'too many secrets',<br>
  applicationId: '486e7225-b59a-4eff-802d-fc9452d85226'<br>
};</p>
<p>xhr.open('POST', 'http://localhost:9011/api/login', true);<br>
xhr.setRequestHeader("Content-type", "application/json");<br>
xhr.send(JSON.stringify(request));<br>
</p>

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:

<br>
class TwoFactor extends Component {<br>
  render() {<br>
    return (<br>
      <div className="login" ><br>
        <form id="two-factor"><br>
          <label><input id="code" name="code" type="text"/></label><br>
          <input type="submit" value="Complete Login"/><br>
        </form><br>
      </div><br>
    );<br>
  }<br>
}<br>
export default TwoFactor;<br>

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. See documentation.

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.

<br>
const xhr = new XMLHttpRequest();<br>
xhr.onreadystatechange = (function() {<br>
  if (xhr.readyState === XMLHttpRequest.DONE) {<br>
    if (xhr.status === 200) {<br>
      // Handle successful login<br>
    } else if (xhr.status === 400) {<br>
      // Input validation, missing required values<br>
    } else if (xhr.status === 404) {<br>
      // Invalid or expired twoFactorId, return to login<br>
    } else if (xhr.status === 421) {<br>
      // Invalid two-factor code, try again<br>
    } else {<br>
      // Login failed for other reasons<br>
    }<br>
  }<br>
});<p></p>
<p>const request = {<br>
  code: '522909',<br>
  twoFactorId: 'YkQY5Gsyo4RlfmDciBGRmvfj3RmatUqrbjoIZ19fmw4',<br>
  applicationId: '486e7225-b59a-4eff-802d-fc9452d85226'<br>
};</p>
<p>xhr.open('POST', 'http://localhost:9011/api/two-factor/login', true);<br>
xhr.setRequestHeader("Content-type", "application/json");<br>
xhr.send(JSON.stringify(request));<br>
</p>

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. For full integrated examples review the example source code provided in the linked Github project.

If you’d like to learn more about Passport, visit our inversoft.com/passport and review our documentation. We would love to hear if there are any other Passport integrations you’d like to see in the future. Please let us know in the comment section below, on email or Twitter @inversoft.