Two-factor Authentication Developer Best Practices

Twilio's expertise in Two-factor Authentication implementations has shown us pitfalls to avoid and common patterns that are best to follow when building 2FA into your application. This page contains our answers to common questions and distilled expertise and best practices for your Two-factor Authentication implementation.

Many of our best practices are already embedded in our Two-factor Authentication Quickstarts. We suggest running through a quickstart before starting your own implementation.

Customize Your Two-factor Authentication Implementation

First before you start implementing the API in your application, you will create an Authy application in the Twilio Console. Here you have an opportunity to customize to the look, feel, and user experience of your authentication setup.

Custom Logo, Image, and Colors

By default, your application's requests will use the default logo and image set up in the Twilio Console. To change it, click on the 'Images & Colors' link on the left sidebar. Upload both a large image (seen while the push notification is active) and a smaller icon. The maximum image size is 128 Kb.

Below the images on that page, you can change the color of the fonts, headers, and background. Additionally, you can customize the timer color. Any customizations you make will be reflected instantly on the phone preview on the right side of the page.

You can also set a custom logo per request through the API. See the ApprovalRequests API page for details.

Two-factor Authentication Messages

By default, the Authy API automatically uses the Application Name from the Account Security Console in user messages. Whatever you set in the Console as the 'Application Name' will be reflected in 2FA messages, and the rest of the text will be automatically localized and translated for your users.

Two-factor requests have several message variants to prevent carrier spam flags, they typically look like the following. But some words and the order might change:

Your <Application Name> verification code is: 1234

Custom Messages

If the default message variants are insufficient, the Authy API supports custom two-factor messages with an account flag. Please contact Sales with your business requirements to enable custom messages. Note that we require any custom message to be significantly different from the ones we use to ensure we continue to avoid carrier filtering/blocking. Our sales team can help you with that decision.

Note: You will need to provide any localization and translation necessary on your own if you enable custom messaging. 

Your <Application Name> Service Number is 1234!

 

Secure Your Twilio Two-factor Authentication App

Now that you've got the application setup in the Console, it's time to look at how to implement the API into your own application logic. 

Register a New User

For high levels of security, we suggest following this workflow when onboarding a new user. Each step assumes the previous step was passed:

  1. Use Phone Verification (Account Verification) to determine if the user has the device they claim currently in possession.
  2. Register the user for continuous Two-factor Authentication usage.
  3. Require Twilio Two-factor Authentications to protect any combination of log-ins, high-risk operations, and high-value transactions.

Please talk to our sales team for more details and to work through your custom requirements.

Verify a Push Authentication Validation Request Comes from Twilio

Twilio offers HMAC signature verification to check a Push Authentication Webhook request comes from Twilio and is not spoofed. As Push Authentications will authenticate with Twilio directly, we'll respond with a Webhook to your exposed endpoint with the results of the verification. While testing without verification is acceptable, you'll need to add code to validate requests in production. (Our account security helper libraries can help ease this step).

All requests from Twilio will include a X-Authy-Signature HTTP Header, which is hashed using HMAC-SHA256 with your Application API Key from the Console.

We've written up the steps to validating incoming Twilio Push Authentication Verifications in detail here.

Token Generation Algorithm

Our token generation code implements RFC 6238's One-Time Password Algorithm.

Understand the Two-factor Authentication Delivery Channels

We've put extended details on the four Authy API authentication Channels on this overview page, but it's important to understand high level pros and cons of the four channels we offer.

Should I Use The SMS (or voice) Channel?

SMS is a lower security channel than soft tokens or push authentications, but in many cases you should still leave it available as an authentication option. SMS support is built into all mobile phones; even without a separate application tokens delivered by SMS will make it to your users. If the choice is between password-only authentication or password plus SMS, SMS is a clear winner. Twilio also offers additional security on top of common SMS authentication implementations - for example, we limit delivery to certain endpoints (such as online SMS portals) to prevent some attack vectors.

Similar arguments apply for the voice channel. In some regions of the world, voice traffic is prioritized. By opening the voice channel (perhaps as an application preference if not by default), you improve the reliability of token delivery in some geographies.

Which 2FA Channels Are The Most Secure?

Push authentications are the most secure channel, and it is very convenient for your users as well. Instead of having to open a mobile application and navigate to your website's token, Push authentications present an "Approve"/"Deny" dialog within easy reach. Additionally, a "Deny" on a push authentication is a signal you can use in your application's business logic, perhaps to apply greater scrutiny to the current user action.

Although not as secure as push authentications, soft tokens (TOTP/Time-based One Time Passcodes generated in-app or SDK) are still a strong choice. Soft tokens won't offer the "Deny" signal of push authentications and will present other attack surfaces such as spearphishing, but tokens are a much more secure choice than SMS or voice channels.

How Should I Limit my Two-factor Channels?

Twilio's Authy API is forward compatible, so adding support for the SMS channel means you can use voice and soft tokens automatically. Push authentications require just a few additional lines of code to implement polling or webhook support.

You can force specific channels through the API or the Account Security Console, but you can also segment your users into specific channels. For example, you might want to allow users to opt-in to voice or SMS channels, or require some high-volume users to use soft tokens or push authentications.

As always, feel free to talk through your specific requirements with us.

Know the Rate Limits and Timing Constraints

There are a number of rate limits, tolerances, and timeout periods you should be aware of when building your application. As rate limits often interact with security requirements, note that these numbers are subject to change.

Time Synchronization, Validity Window, and Time Drift

Soft tokens are valid plus or minus 3 minutes from the nominal time on the server. Generally speaking, the client and server are synchronized if the client is connected to the internet, but in extreme cases tokens may be valid for up to 6 minutes. To work around issues of time synchronization and drift, if your users have the Authy App it will opportunistically synchronize clocks with our servers when an internet connection is available. SMS and voice channels are synchronized, so requests are valid for exactly three minutes.

Passcodes will continue to work even when a phone is offline or in airplane mode, as long as the total time differential is less than three minutes when codes are submitted. We are unable to extend the validity window for your application beyond +/- 3 minutes, or 6 total minutes (3 for SMS/Voice).

Our time drift implementation is based on RFC 6238, which builds on RFC 4226. For a further discussion of time synchronization and drift, see those RFCs.

One Time Password (OTP) Length

By default, Two-factor Authentication apps will use 7 digit passcodes. You can change them to be from 6 to 8 digits in the 'Settings' link of the Authy Console.

TOTP Length

 

Latency

While we don't guarantee a two-way latency, the majority of our requests will complete in under 500 milliseconds. This will vary depending on your method of connectivity, network congestion, and geographic distance among other reasons.

 

Build Your Custom Mobile Authentication App

For the quickest path to two-factor integration, you can pair our Authy API with the Authy Desktop or Mobile apps. We suggest starting with Authy App before moving forward on plans to build your own solution; starting with Authy will eliminate some debugging steps and large variables in the early stages of your app.

You can take a staged approach to building an app, starting with Authy, then supporting the Authy App and your own applications simultaneously before moving to a single client solution. Here are the quick links for more information on the SDK:

 

Still Have Questions on Best Practices?  We're Here to Help.

Still curious about an aspect of Two-factor Authentication that is confusing or whether a pattern is worth implementing? Contact Twilio Sales and we'll help you pick features and implementations that will work best for your application.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.