Gate Users Until They Verify Their Email

Overview

As of version 1.27.0, FusionAuth can be configured to gate users’ accounts until their email has been verified. While users successfully authenticate, they won’t be able to proceed further until they have verified possession of the email address they registered with.

To enable email verification gating, do the following:

• Configure the tenant with your email server.
• Configure the tenant to enable email gating.
• Optionally customize the email 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.27.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 edition and valid license. If you need to buy an edition, please visit the pricing page. If you need to activate your instance, please visit the Reactor page.

Gating vs Verification

FusionAuth ships with registration verification and email verification flows. These verification flows toggle an attribute (verified) on a user object and on a registration array (for a user). As a developer, you have the option to gate the user (or prevent from “continuing” auth) based on these attributes when writing your application and integration code.

However, with paid editions of FusionAuth, 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 Tenant Email Server

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 Tenants -> Your Tenant and then select the Email tab. Scroll to the SMTP settings section. Configure this with your SMTP server information. If you are testing locally, you can use a mock email server like mailcatcher.

Ensure a test email is delivered. If you have any issues, follow the steps in the email troubleshooting documentation.

Save the configuration.

Enable Email Verification Gating

Navigate to Tenants -> Your Tenant and then select the Email tab. Scroll to the Email verification settings section.

• Enable Verify email .
• Choose your email template. The default template is Email verification, and that will work fine for this tutorial.
• Update the Verification strategy . This can be either ClickableLink or FormField. The former sends an email with a link to verify the user’s address. The latter emails a code which the user will provide to FusionAuth. For this tutorial, use ClickableLink.
• 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 Email Verification Template

Navigate to Customizations -> Email Templates. Edit the Email Verification template by clicking on the blue “Edit” button.

Modify the HTML and text templates as desired and then save them. You can also localize the messages.

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.

Enable self service registration and configure the displayed and required fields as desired.

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.

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 email address. After registration is complete, you’ll receive an email prompting you to verify the email address.

Here is the email in the mailcatcher user interface:

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

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 email and password for the user you just registered.

You’ll be sent to the same email 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 email 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 email address. This indicates that their email has not yet been verified.

Once you have verified the email address by clicking on the link, 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 email verification occurs. Let’s look at the JSON.

If a user is created and email verification is disabled, the verified attribute of the user object will be true. This is because FusionAuth treats all users as having verified emails when email verification is disabled.

User Object With Email 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"
  },
  "email": "admin@fusionauth.io",
  "encryptionScheme": "salted-pbkdf2-hmac-sha256",
  "firstName": "Erlich",
  "id": "00000000-0000-0000-0000-000000000001",
  "insertInstant": 1630520102103,
  "lastLoginInstant": 1630639038934,
  "lastName": "Bachman",
  "lastUpdateInstant": 1630602397679,
  "passwordChangeRequired": false,
  "passwordLastUpdateInstant": 1630520102697,
  "tenantId": "30663132-6464-6665-3032-326466613934",
  "twoFactor": {},
  "usernameStatus": "ACTIVE",
  "verified": true
}

If a user is created while email verification is enabled, then the verified attribute will have the value false:

User Object With Email 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"
  },
  "email": "admin@fusionauth.io",
  "encryptionScheme": "salted-pbkdf2-hmac-sha256",
  "firstName": "Erlich",
  "id": "00000000-0000-0000-0000-000000000001",
  "insertInstant": 1630520102103,
  "lastLoginInstant": 1630639038934,
  "lastName": "Bachman",
  "lastUpdateInstant": 1630602397679,
  "passwordChangeRequired": false,
  "passwordLastUpdateInstant": 1630520102697,
  "tenantId": "30663132-6464-6665-3032-326466613934",
  "twoFactor": {},
  "usernameStatus": "ACTIVE",
  "verified": false
}

Naturally, this will change to verified: true once the user verifies their email.

Common Questions

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

Answer: No. More specifically, this is an accurate statement if you have never enabled email verification and/or application registration verification and imported your users with a verified: true value (as applicable).

To double-check your users, 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.

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 value manually. However, there is an open issue adding this functionality. Please upvote if you believe this is needed.

https://github.com/FusionAuth/fusionauth-issues/issues/1319

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

Next Steps

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

• Discover how to modify your theme to make the email verification gate pages look like your application.
• Learn more about email templates and how to customize them.
• Have the user submit a passcode rather than click a link. With this option, the user will be prompted with a screen similar to the below image.