For new development, we encourage you to use the Verify API instead of the Authy API. The Verify API is an evolution of the Authy API with continued support for SMS, voice, and email one-time passcodes, an improved developer experience and new features including:
- Access via the Twilio CLI
- Improved Visibility and Insights
- Push authentication SDK embeddable in your own application
You are currently viewing the Authy API. The Authy API will continue to be maintained, but any new features and development will be on the Verify API. Check out the FAQ for more information and Verify API Reference to get started.
This Sinatra sample application is an example of typical login flow. To run this sample app yourself, download the code and follow the instructions on GitHub.
Adding two-factor authentication (2FA) to your web application increases the security of your user's data. Multi-factor authentication determines the identity of a user by validating first by logging into the app, and second by validating their mobile device.
For the second factor, we will validate that the user has their mobile phone by either:
- Sending them a OneTouch push notification to their mobile Authy app or
- Sending them a token through their mobile Authy app or
- Sending them a one-time token via text message sent with Authy via Twilio.
If you haven't configured Authy already now is the time to sign up for Authy. Create your first application naming it as you wish. After you create your application, your "production" API key will be visible on your dashboard.
Once we have an Authy API key we register it as an environment variable.
Let's take a look at how we register a user with Authy.
When a new user signs up for our website, we will call this route. This will store our new user into the database and will register the user with Authy.
All Authy needs to get a user set up for your application is the email, phone number and country code. In order to do a two-factor authentication, we need to make sure we ask for this information at sign up.
Once we register the user with Authy we get an
authy_id back. This is very important since it's how we will verify the identity of our user with Authy.
Having registered our user with Authy, we then can use Authy's OneTouch feature to log them in.
When a User attempts to log in to our website, we will ask them for a second form of authentication. Let's take a look at OneTouch verification first.
OneTouch works like this:
- We attempt to send a OneTouch Approval Request to the user.
- If the user has OneTouch enabled, we will get a
- The user hits Approve in their Authy app.
- Authy makes a POST request to our app with an
- We log the user in.
In the next steps we'll look at how we handle cases where the user does not have OneTouch, or denies the login request.
When our user logs in we immediately attempt to verify their identity with OneTouch. We will fallback gracefully if they don't have a OneTouch device, but we don't know until we try.
Authy allows us to input details with our OneTouch request, including a message, a logo and so on. We could easily send any amount of details by appending
details['some_detail']. You could imagine a scenario where we send a OneTouch request to approve a money transfer.
"message" => "Request to Send Money to Jarod's vault", "details['Request From']" => "Jarod", "details['Amount Request']" => "1,000,000", "details['Currency']" => "Galleons",
Once we send the request we need to update our user's
authy_status based on the response.
Once we send the request we need to update our user's
AuthyStatus based on the response. But first we have to register a OneTouch callback endpoint.
In order for our app to know what the user did after we sent the OneTouch request, we need to register a callback endpoint with Authy.
Note: In order to verify that the request is coming from Authy, we've written the helper method
authenticate_request! that will halt the request if it appears it isn't coming from Authy.
Here in our callback, we look up the user using the Authy ID sent with the Authy POST request. Ideally at this point we would probably use a websocket to let our client know that we received a response from Authy. However for this version we're going to keep it simple and just update the
authy_status on the user.
Our application is now capable of using Authy for two-factor authentication. However, we are still missing an important part: the client-side code that will handle it.
When we expect a OneTouch response, we will begin by polling
/authy/status until we see an Authy status is not empty. Let's take a look at this controller and see what is happening.
Finally, we can confirm the login.
authy_status is approved the user will be redirected to the protected content, otherwise we'll show the login form with a message that indicates the request was denied.
That's it! We've just implemented two-factor auth using three different methods and the latest Authy technology.
If you're a Ruby developer working with Twilio, you might enjoy these other tutorials:
Faster than e-mail and less likely to get blocked, text messages are great for timely alerts and notifications. Learn how to send out SMS (and MMS) notifications to a list of server administrators.
Click-to-call enables your company to convert web traffic into phone calls with the click of a button
Thanks for checking out this tutorial! If you have any feedback to share with us, we'd love to hear it. Connect with us on Twitter and let us know what you build!