Gate Users Until They Verify Their Phone

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 phone verification 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 vs Pre-Verification#

Phone Verification is not a premium feature; gating is a premium feature. When you enable gating, users cannot receive a JWT to complete the authentication workflow 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. Gating happens after user creation.

Pre-verification applies the same concept, but user identities must be verified before user creation.

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.
Update the Verification strategy . This can be either ClickableLink or FormField. The former sends an SMS message with a link to verify the user’s phone number. The latter sends a code which the user will provide to FusionAuth. For this tutorial, keep the default value of FormField.
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 clicking on the blue Edit button.

Modify the text template as desired and then save. You can also localize the messages.

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 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 screen 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 Emailed to Users Don’t Function As Expected#

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

Check the Email Template#

Ensure you have selected the correct email template.

For Email Verification

If attempting to verify email addresses, ensure you have selected the appropriate template (Email Verification as opposed to Registration Verification in this instance)

For Application Registration

If attempting to verify application registration, ensure you have selected the appropriate template (Registration Verification as opposed to Email Verification in this instance)

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 Email Verification, Phone Verification, and Registration Verification durations.

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#

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

Gate Users Until They Verify Their Phone

Overview#

Prerequisites#

Gating vs Verification vs Pre-Verification#

Configure the Messenger#

Configure the Tenant with the Messenger#

Enable Phone Verification Gating#

Customize the Phone Verification Template#

Configure the Application#

Test It Out#

The User Object#

Common Questions#

Troubleshooting Phone Verification#

Links Emailed to Users Don’t Function As Expected#

Check the Email Template#

Check External Identifier Timeouts#

Links Sent to Users Don’t Function As Expected#

Check External Identifier Timeouts#

Next Steps#

Results

Recent