Onboarding Authy Users

Onboarding Authy Users

Twilio customers have several options for using devices to authenticate users. Here’s how to onboard your users with our best known solution, Authy two-factor authentication (2FA).

User Enrollment

When users enable Authy 2FA, your app will need to register them. This is done via a REST API call in which Authy returns a unique AuthyID based on a country code and phone number. Stored alongside the user data model in your database, all future 2FA requests will use this AuthyID to initiate a second factor for authentication.

1. User enables 2FA by providing phone number, country code and email address
2. Your application backend calls Authy API with your Authy API key
3. Authy returns unique AuthyID
4. Store this value in your database with the user account information.

To confirm a successful registration, require users to authenticate with a second factor. Here’s one way:

1. Request an SMS or Voice 2FA to be sent to the device associated with the user’s AuthyID
2. Authy user receives a Time-based One Time Password (TOTP) via SMS or Voice
3. User verifies the requested TOTP
4. Verify the SMS with the user’s AuthyID
5. If successful, store the AuthyID in the database and begin enforcing 2FA

If the TOTP is not delivered, users can request it be resent. Alternatively, you can encourage the user to download and enable Authy before continuing. Then send them a OneTouch approval request to confirm before enabling 2FA.

Why an AuthyID?

In order to disassociate the user’s phone number from the Authy service and allow you to maintain a single identifier for that user, a unique AuthyID is created during registration.

If the user changes their phone number or loses their phone, Authy’s registered mobile app, Phone Change and Account Recovery processes will transition the user with the AuthyID. You, as a service provider, never need to handle support calls pertaining to phone changes related to your user’s second factor.

Opt-In vs Opt-Out and Mandatory User Enrollment

The easiest way for users to enroll with Authy is to ask the user to opt-in by navigating to their profile and enabling 2FA. After users register, save an AuthyID, and respond to the initial 2FA notification, they will prove they’re in possession of their phone.

In the case of ‘mandatory’ user enrollments (e.g. new students at a University), all users are batch enrolled.  Afterwards, users are prompted to use 2FA at their initial login. You can then provide a number of ‘grace logins’ prompting the user to login with 2FA before their account is locked out.

If you want to provide users with the ability to opt-out of using a second factor, you can do so during these initial grace logins. However, you may want to provide messaging which discourages users from disabling their second factor.

Application Options

When providing opt-in Authy protection to users, you may want to toggle authentication methods by disabling — or forcing — SMS or phone calls, depending upon your security requirements. Additionally, if you batch enroll pre-existing users, you can choose to disable the links to install Authy’s iOS or Android apps typically sent to new registrations.

Defining the User Experience

As a provider, you can design your user’s Authy experience with any combination of the following authentication approaches:

Authy SoftToken

Allows for a unique TOTP code to be generated on the Authy app when a user’s phone is not connected to a cell or data network (e.g. when on a plane).

Authy OneCode

Provides SMS or voice-call delivery of a TOTP code. Has broadest global reach, but the National Institute of Standards and Technology (NIST) has voiced significant concerns about relying solely on SMS-based authentication.

Authy OneTouch

Push notification triggered solution provides a streamlined user experience with advanced 2FA protection. Available in the Authy app and with the Authy OneTouch Mobile SDK, OneTouch lets you customize the delivery payload and approval time frame, and it supports HMAC signing for non-repudiation of approvals.

Client-side Implementation

In our demo sites, we provide all three options in a single modal after authentication. The website immediately opens up a modal window (below, left) and sends a OneTouch notification to the registered Authy user. If the Authy app is installed, users receive a notice and can approve or deny access (below, right).

Our implementation example encourages users to use the most secure option first (OneTouch) and then, after some seconds, allow fallback to authenticate with OneCode or SoftToken.

While our demos offer all authentication methods, you may decide to offer a subset of options. Remember, you always have full control to design an interface that suits your use case.

Try Authy Yourself

Twilio customers report that our turnkey 2FA solution is easy to implement and requires a minimum of engineering time. Explore our guides, APIs, SDKs, and tutorials in the programming language of your choice — or try for Authy for yourself.  Sign up for an Authy API key at twilio.com/console and download our Authy API Samples. Or clone and run our full-stack JavaScript implementation.