Gate Users Until They Verify Their Phone Number

Overview

As of version 1.59.0, FusionAuth can be configured to gate users’ accounts until their phone numbers have been verified. While users can successfully start the login process, they will be blocked from completing it until they have verified possession of the phone number they registered with.

To enable phone verification gating, do the following:

Configure a messenger
Configure the tenant with your messenger
Configure the tenant to enable phone gating
Optionally customize the verification message template
Enable self-service registration
Configure your application with a redirect URL

Let’s step through each of these, but first, there are some required prerequisites.

Prerequisites

This feature is only available in paid plans. Please visit our pricing page to learn more.

This tutorial assumes you are running FusionAuth version 1.59.0 or greater. If you aren’t, head on over to the installation guide or the upgrade guide to update to a version with support for this feature.

This tutorial also assumes you have a paid plan and valid license. If you need to buy a plan, please visit the pricing page. If you need to activate your instance, please visit the Reactor page.

Although you do not have to use Twilio to send messages, this tutorial assumes you will use Twilio as your SMS messenger. If you want to use a different messenger, you can do so by creating a generic messenger instead of a Twilio messenger.

Gating vs Verification

Phone Verification is not a premium feature, however gating is. Gating stops the user from receiving a JWT or essentially completing the authentication workflow. FusionAuth is enforcing a “gate” around a user until they verify their phone number.

FusionAuth ships with phone verification flows. These verification flows update the verified and verifiedReason attributes on a user identity. You have the option to gate the user (or prevent them from “continuing” auth) based on these attributes when writing your application and integration code.

With paid FusionAuth plans, you can elect to have FusionAuth “gate” your users based on these verification attributes. Gating in this sense, would prevent the user from authenticating further or obtaining a JWT and would be enforced by the FusionAuth User Interface.

Configure the Messenger

Log in to the FusionAuth administrative user interface. You could do all of this configuration with the API or kickstart, but for this tutorial you’ll use the UI.

Navigate to Settings -> Messengers and then click Add Twilio messenger and enter your Twilio account information.

Configure the Tenant with the Messenger

Navigate to Tenants -> Your Tenant and then select the Identities tab. Scroll to the Messenger settings section. Configure this with the messenger you just created.

Enable Phone Verification Gating

Under Phone, enable Verify identity
Choose your message template. The default template is Phone Verification, and that will work fine for this tutorial
Verification strategy . For this tutorial, keep the default value of FormField. For future reference, this can be either:
- ClickableLink - sends an SMS message with a link to verify the user’s phone number
- FormField - sends a code which the user will provide to FusionAuth
Ensure that the Unverified behavior value is Gated

After these steps, you should end up with a configuration screen that looks like this:

Make sure you save the configuration.

Customize the Phone Verification Template

Navigate to Customizations -> Message Templates . Edit the Phone Verification template by selecting the Edit item from the action menu.

Modify the text template as desired and then save. You can also create localized versions of the message template under the Localization tab.

Customizing the phone verification message template

Configure the Application

Navigate to Applications . Edit your application by clicking on the blue Edit button.

Enable self service registration by selecting the Registration tab, and then scrolling to the Self service registration section.

You can create a user with an unverified phone number in other ways than self service registration. However, self service registration is the simplest way to create a user without a verified phone number.

Enable self service registration and configure the displayed and required fields as desired (in particular, choose Phone for the Login type).

Next, navigate to the OAuth tab. Enable the Authorization Code grant.

In addition, ensure you have entered a valid URL in the Authorized redirect URLs field. (The value of this redirect URL doesn’t really matter for this tutorial. But for production use, ensure the code at that endpoint can exchange an authorization code for a token.)

Save the application configuration. You’ll be returned to the list of applications.

Click on the green View button of your application to see the details of your application.

View application details to see the relevant URLs

Look for the Registration URL . It’ll be something like https://local.fusionauth.io/oauth2/register?client_id=85a03867-dccf-4882-adde-1a79aeec50df&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Foauth-redirect. Copy that value as you’ll use it below.

At the same time, find the OAuth IdP login URL , and copy that as well.

Test It Out

Now, test out the functionality. Register a new account. Make sure to use a different browser or incognito mode so that the admin account you logged in with while configuring FusionAuth doesn’t interfere with new user registration.

Visit the registration URL copied above. You’ll be prompted to register. Fill out the form with a valid phone number. After registration is complete, you’ll receive a message prompting you to verify the phone number.

This user account will be gated and unable to completely log in if you have registered but not yet verified the phone number. In your browser where you registered, you’ll see a form similar to below:

Form field default phone verification gate screen

To test the gating, open a different browser (not a window, but an entirely different browser) and visit the login URL copied above. Enter the phone number and password for the user you just registered.

You’ll be sent to the same phone verification gate page.

No matter which API or hosted login page you use, no JWT will be issued until the user has been verified. The user will continue to see the verification prompt when they log in until then.

If an API is being used to authenticate the user, the API will return a status code indicating phone verification has not yet occurred. Please see the Login API for more details.

If you view the user in the administrative user interface, you’ll see a question mark next to their phone number. This indicates that their phone number has not yet been verified.

Once you have verified the phone number by entering the code from the message, you can now log in and will be sent to the configured redirect URL.

The User Object

The user object changes before, during, and after the phone verification occurs. Let’s look at the JSON.

If a user is created and phone verification is disabled, the verified attribute of the identity object will be false with a reason of Disabled.

User Object With Phone Verification Turned Off Initially JSON

{
  "active": true,
  "birthDate": "1981-06-04",
  "connectorId": "e3306678-a53a-4964-9040-1c96f36dda72",
  "data": {
    "Company": "PiedPiper",
    "PreviousCompany": "Aviato",
    "user_type": "iconclast"
  },
  "phoneNumber": "+13035551212",
  "encryptionScheme": "salted-pbkdf2-hmac-sha256",
  "firstName": "Erlich",
  "id": "00000000-0000-0000-0000-000000000001",
  "identities": [
    {
      "primary": true,
      "type": "phoneNumber",
      "value": "+13035551212",
      "verified": false,
      "verifiedReason": "Disabled"
    }
  ],
  "insertInstant": 1630520102103,
  "lastLoginInstant": 1630639038934,
  "lastName": "Bachman",
  "lastUpdateInstant": 1630602397679,
  "passwordChangeRequired": false,
  "passwordLastUpdateInstant": 1630520102697,
  "tenantId": "30663132-6464-6665-3032-326466613934",
  "twoFactor": {},
  "usernameStatus": "ACTIVE",
  "verified": false
}

If a user is created while phone verification is enabled, the verified attribute of the identity object will be false with a reason of Pending

User Object With Phone Verification Turned On Initially JSON

{
  "active": true,
  "birthDate": "1981-06-04",
  "connectorId": "e3306678-a53a-4964-9040-1c96f36dda72",
  "data": {
    "Company": "PiedPiper",
    "PreviousCompany": "Aviato",
    "user_type": "iconclast"
  },
  "phoneNumber": "+13035551212",
  "encryptionScheme": "salted-pbkdf2-hmac-sha256",
  "firstName": "Erlich",
  "id": "00000000-0000-0000-0000-000000000001",
  "identities": [
    {
      "primary": true,
      "type": "phoneNumber",
      "value": "+13035551212",
      "verified": false,
      "verifiedReason": "Pending"
    }
  ],
  "insertInstant": 1630520102103,
  "lastLoginInstant": 1630639038934,
  "lastName": "Bachman",
  "lastUpdateInstant": 1630602397679,
  "passwordChangeRequired": false,
  "passwordLastUpdateInstant": 1630520102697,
  "tenantId": "30663132-6464-6665-3032-326466613934",
  "twoFactor": {},
  "usernameStatus": "ACTIVE",
  "verified": false
}

Naturally, the user’s phone number identity will change to verified: true with verifiedReason: "Completed" once the user verifies their phone number.

Users imported through the Import API will have whatever attributes are initially imported regardless of verification or gate settings.

Common Questions

Question: Will all my existing users retroactively get emails or SMS messages for either gate once enabled?

Answer: No. However, if existing users have unverified identities (meaing verified: false with verifiedReason: "Pending"), and gating is enabled, then those users will be required to verify those identities at their next login.

To double-check your users’ email verification status, click on Users -> Search Bar and use this Elasticsearch query string: verified: false. Note, this will return if either user or user.registrations[x] is unverified. Users found by this query will be required to verify either their email or application registration once the gate is enabled. However, they will not be emailed until they log in. During the login process, they will be required to click on a link to have a verification email sent to them.

As of version 1.59.0, it’s not yet possible to search for unverified phone number identities.

Question: What if I have accidentally/inadvertently imported users with a verified: false value (either on the user or application registration)? In other words, can I do this manually.

Answer: Currently, there is no way to change this. However, there is an open issue adding this functionality. Please upvote if you believe this is needed.

Question: What does it mean to enable both registration and email gates and verification paths?

Answer: If you enable both registration verification and email verification, there will be a bit of redundancy (this is fine and expected). Consider the use case of ten applications and one common tenant. Maybe nine of those applications require only email verification, but the tenth application requires an application gate to force user opt-in behaviors. Specifically, the user on the tenth application will get two emails to verify both their registration and their email.

Troubleshooting Phone Verification

Links Sent to Users Don’t Function As Expected

Users cannot verify their phone number. The link or code does not work (it is expired or there is some other error).

Check External Identifier Timeouts

Ensure your external identifier timeouts are appropriate. Reasonable defaults are set, but they can be adjusted ( Tenants -> Advanced Tab -> External identifier durations ), with particular attention paid to Phone Verification duration.

Next Steps

Now that you’ve successfully set up gated phone verification, take the next steps to integrate this functionality into your application:

Discover how to modify your theme to make the phone verification gate pages look like your application.
Learn more about message templates and how to customize them.

Results

Recent