As of November 2022, Twilio no longer provides support for Authy SMS/Voice-only customers. Customers who were also using Authy TOTP or Push prior to March 1, 2023 are still supported. The Authy API is now closed to new customers and will be fully deprecated in the future.
For new development, we encourage you to use the Verify v2 API.
Existing customers will not be impacted at this time until Authy API has reached End of Life. For more information about migration, see Migrating from Authy to Verify for SMS.
This Ruby on Rails sample application is an example of a 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 users' data. Multi-factor authentication validates the identity of a user with a two-stage process: first, that they can log into the app, and second that they their mobile device in their possession. This second phase is performed by:
See how VMware uses Authy 2FA to secure their enterprise mobility management solution.
If you haven't already signed up for Authy, now is the time to to do so. Create your first application, naming it whatever you wish. After you create your application, your "production" API key will be visible on your dashboard.
Once you have an Authy API key, register it as a environment variable.
config/initializers/authy.rb
_10require 'yaml'_10Authy.api_key = Rails.application.secrets.authy_key_10Authy.api_uri = 'https://api.authy.com/'
Let's take a look at how you register a user with Authy.
When a new user signs up for our website, we will call this route. This will save our new user to the database and will register the user with Authy.
In order to set up your application, Authy only needs the user's 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 the user with Authy.
app/controllers/users_controller.rb
_31class UsersController < ApplicationController_31 def new_31 @user = User.new_31 end_31_31 def create_31 @user = User.new(user_params)_31 if @user.save_31 session[:user_id] = @user.id_31_31 authy = Authy::API.register_user(_31 email: @user.email,_31 cellphone: @user.phone_number,_31 country_code: @user.country_code_31 )_31 @user.update(authy_id: authy.id)_31_31 redirect_to account_path_31 else_31 render :new_31 end_31 end_31_31 private_31_31 def user_params_31 params.require(:user).permit(_31 :email, :password, :name, :country_code, :phone_number_31 )_31 end_31end
Having registered our user with Authy, we 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 identification. Let's take a look at OneTouch verification first. OneTouch works like this:
POST
request to our app with an
approved
status.
When our user logs in, we immediately attempt to verify their identity with OneTouch. We will fall back gracefully if they don't have a OneTouch device.
Authy allows us to include extra information with our OneTouch request, including a message, a logo, and so on. Add extra information with details['some_detail']. Imagine a scenario where you send a OneTouch request to approve a money transfer. You'd set up details like:
_10"message" => "Request to Send Money to Jarod's vault",_10"details['Request From']" => "Jarod",_10"details['Amount Request']" => "1,000,000",_10"details['Currency']" => "Galleons",
app/controllers/sessions_controller.rb
_35class SessionsController < ApplicationController_35 def new_35 @user = User.new_35 end_35_35 def create_35 @user = User.find_by(email: params[:email])_35 if @user && @user.authenticate(params[:password])_35 session[:pre_2fa_auth_user_id] = @user.id_35_35 # Try to verify with OneTouch_35 one_touch = Authy::OneTouch.send_approval_request(_35 id: @user.authy_id,_35 message: "Request to Login to Twilio demo app",_35 details: {_35 'Email Address' => @user.email,_35 }_35 )_35 status = one_touch['success'] ? :onetouch : :sms_35 @user.update(authy_status: status)_35_35 # Respond to the ajax call that requested this with the approval request body_35 render json: { success: one_touch['success'] }_35 else_35 @user ||= User.new(email: params[:email])_35 render :new_35 end_35 end_35_35 def destroy_35 session[:user_id] = nil_35 flash[:notice] = "You have been logged out"_35 redirect_to root_path_35 end_35end
Once we send the request we need to update our user's authy_status 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.
In order to verify that a request is coming from Authy, we've written the helper method authenticate_request! that will halt the request if it appears the request 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 use a websocket to let our client know that we received a response from Authy. However, we're going to keep it simple and just update the authy_status on the User.
app/controllers/authy_controller.rb
_76require 'openssl'_76require 'base64'_76_76class AuthyController < ApplicationController_76 # Before we allow the incoming request to callback, verify_76 # that it is an Authy request_76 before_action :authenticate_authy_request, :only => [_76 :callback_76 ]_76_76 protect_from_forgery except: [:callback, :send_token]_76_76 # The webhook setup for our Authy application this is where_76 # the response from a OneTouch request will come_76 def callback_76 authy_id = params[:authy_id]_76 if authy_id != 1234_76 begin_76 @user = User.find_by! authy_id: authy_id_76 @user.update(authy_status: params[:status])_76 rescue => e_76 puts e.message_76 end_76 end_76 render plain: 'ok'_76 end_76_76 def one_touch_status_76 @user = User.find(session[:pre_2fa_auth_user_id])_76 session[:user_id] = @user.approved? ? @user.id : nil_76 render plain: @user.authy_status_76 end_76_76 def send_token_76 @user = User.find(session[:pre_2fa_auth_user_id])_76 Authy::API.request_sms(id: @user.authy_id)_76 render plain: 'sending token'_76 end_76_76 def verify_76 @user = User.find(session[:pre_2fa_auth_user_id])_76 token = Authy::API.verify(id: @user.authy_id, token: params[:token])_76 if token.ok?_76 session[:user_id] = @user.id_76 session[:pre_2fa_auth_user_id] = nil_76 redirect_to account_path_76 else_76 flash.now[:danger] = "Incorrect code, please try again"_76 redirect_to new_session_path_76 end_76 end_76_76 # Authenticate that all requests to our public-facing callback is_76 # coming from Authy. Adapted from the example at_76 # https://docs.authy.com/new_doc/authy_onetouch_api#authenticating-callbacks-from-authy-onetouch_76 private_76 def authenticate_authy_request_76 url = request.url_76 raw_params = JSON.parse(request.raw_post)_76 nonce = request.headers["X-Authy-Signature-Nonce"]_76 sorted_params = (Hash[raw_params.sort]).to_query_76_76 # data format of Authy digest_76 data = nonce + "|" + request.method + "|" + url + "|" + sorted_params_76_76 digest = OpenSSL::HMAC.digest('sha256', Authy.api_key, data)_76 digest_in_base64 = Base64.encode64(digest)_76_76 theirs = (request.headers['X-Authy-Signature']).strip_76 mine = digest_in_base64.strip_76_76 unless theirs == mine_76 render plain: 'invalid request signature'_76 end_76 end_76end
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.
Scenario: The OneTouch callback URL provided by you is no longer active.
Action: We will disable the OneTouch callback after three consecutive HTTP error responses. We will also:
How to enable OneTouch callback? You need to update the OneTouch callback endpoint, which will allow the OneTouch callback.
Visit the Twilio Console: Console > Authy > Applications > {ApplicationName} > Push Authentication > Webhooks > Endpoint/URL to update the Endpoint/URL with a valid OneTouch callback URL.
We've already seen what's happening on the server side, so let's step in front of the cameras and see how our JavaScript is interacting with those server endpoints.
When we expect a OneTouch response, we 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.
app/assets/javascripts/sessions.js
_43$(document).ready(function() {_43_43 var showTokenForm = function() {_43 $('.auth-ot').fadeOut(function() {_43 $('.auth-token').fadeIn('slow');_43 });_43 };_43_43 var triggerSMSToken = function() {_43 $.get('/authy/send_token');_43 };_43_43 var checkForOneTouch = function() {_43 $.get('/authy/status', function(data) {_43 if (data === 'approved') {_43 window.location.href = '/account';_43 } else if (data === 'denied') {_43 showTokenForm();_43 triggerSMSToken();_43 } else {_43 setTimeout(checkForOneTouch, 2000);_43 }_43 });_43 };_43_43 var attemptOneTouchVerification = function(form) {_43 $.post('/sessions', form, function(data) {_43 $('#authy-modal').modal({backdrop:'static'},'show');_43 if (data.success) {_43 $('.auth-ot').fadeIn();_43 checkForOneTouch();_43 } else {_43 $('.auth-token').fadeIn();_43 }_43 });_43 };_43_43 $('#login-form').submit(function(e) {_43 e.preventDefault();_43 var formData = $(e.currentTarget).serialize();_43 attemptOneTouchVerification(formData);_43 });_43});
Let's take a closer look at how we check the login status on the server.
If the value of 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.
app/controllers/authy_controller.rb
_76require 'openssl'_76require 'base64'_76_76class AuthyController < ApplicationController_76 # Before we allow the incoming request to callback, verify_76 # that it is an Authy request_76 before_action :authenticate_authy_request, :only => [_76 :callback_76 ]_76_76 protect_from_forgery except: [:callback, :send_token]_76_76 # The webhook setup for our Authy application this is where_76 # the response from a OneTouch request will come_76 def callback_76 authy_id = params[:authy_id]_76 if authy_id != 1234_76 begin_76 @user = User.find_by! authy_id: authy_id_76 @user.update(authy_status: params[:status])_76 rescue => e_76 puts e.message_76 end_76 end_76 render plain: 'ok'_76 end_76_76 def one_touch_status_76 @user = User.find(session[:pre_2fa_auth_user_id])_76 session[:user_id] = @user.approved? ? @user.id : nil_76 render plain: @user.authy_status_76 end_76_76 def send_token_76 @user = User.find(session[:pre_2fa_auth_user_id])_76 Authy::API.request_sms(id: @user.authy_id)_76 render plain: 'sending token'_76 end_76_76 def verify_76 @user = User.find(session[:pre_2fa_auth_user_id])_76 token = Authy::API.verify(id: @user.authy_id, token: params[:token])_76 if token.ok?_76 session[:user_id] = @user.id_76 session[:pre_2fa_auth_user_id] = nil_76 redirect_to account_path_76 else_76 flash.now[:danger] = "Incorrect code, please try again"_76 redirect_to new_session_path_76 end_76 end_76_76 # Authenticate that all requests to our public-facing callback is_76 # coming from Authy. Adapted from the example at_76 # https://docs.authy.com/new_doc/authy_onetouch_api#authenticating-callbacks-from-authy-onetouch_76 private_76 def authenticate_authy_request_76 url = request.url_76 raw_params = JSON.parse(request.raw_post)_76 nonce = request.headers["X-Authy-Signature-Nonce"]_76 sorted_params = (Hash[raw_params.sort]).to_query_76_76 # data format of Authy digest_76 data = nonce + "|" + request.method + "|" + url + "|" + sorted_params_76_76 digest = OpenSSL::HMAC.digest('sha256', Authy.api_key, data)_76 digest_in_base64 = Base64.encode64(digest)_76_76 theirs = (request.headers['X-Authy-Signature']).strip_76 mine = digest_in_base64.strip_76_76 unless theirs == mine_76 render plain: 'invalid request signature'_76 end_76 end_76end
That's it! You've just implemented two-factor authentication using three different methods and the latest in Authy technology.
If you're a Ruby developer working with Twilio, you might enjoy these other tutorials:
Protect your users' privacy by anonymously connecting them with Twilio Voice and SMS. Learn how to create disposable phone numbers on-demand, so that two users can communicate without exchanging personal information.
Use Twilio to track the effectiveness of your marketing campaigns.
Thanks for checking out this tutorial. If you have any feedback for us, we'd love to hear it. Connect with us on Twitter and let us know what you build!