Gate Users Until They Verify Their Email

As of version 1.27.0, FusionAuth can be configured to gate users' accounts until their email has been verified. While users can successfully start the login process, they will be blocked from completing it 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 registrationA feature that lets users create their own accounts.
• Configure your application with a redirect URLThe URL where the authorization server sends the browser after login, with an authorization code or an error.

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

Prerequisites#

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 update guide to move 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.

Gating vs Verification vs Pre-Verification#

FusionAuth ships with registration verification and identity verification flows. These verification flows update the verified and verifiedReason attributes on a user's registration or 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 Tenant Email Server#

Log in to the FusionAuth Admin UI. 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.

/admin/tenant/edit/30663132...#email

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 Identities tab. Scroll to the Identity verification settings section.

• Under email, enable Verify identity.
• 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:

/admin/tenant/edit/00000000...#identities

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.

/admin/email/template/edit/00000000...

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 View button of your application to see the details of your application.

/admin/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:

/oauth2/authorize

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 Admin UI, you'll see a question mark next to their email address. This indicates that their email has not yet been verified.

/admin/user/manage/00000000...

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 identity object will be false with a reason of Disabled.

{
  "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",
  "identities": [
    {
      "primary": true,
      "type": "email",
      "value": "admin@fusionauth.io",
      "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": true
}

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

{
  "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",
  "identities": [
    {
      "primary": true,
      "type": "email",
      "value": "admin@fusionauth.io",
      "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 email identity will change to verified: true with verifiedReason: "Completed" once the user verifies their email. Since this is for email (and not phone), this will also change the user-level user.verified field to verified: true.

Common Questions#

Do Existing Users Get Messages When I Enable a Gate?#

No. Enabling a gate sends no messages. Instead, an existing user with an unverified identity must verify the identity at their next login. An identity is unverified when the identity has verified: false and verifiedReason: "Pending". During login, the user clicks a link, and FusionAuth then sends the verification message.

When you use Elasticsearch for search, you can find the users that a gate will affect. Navigate to Users and search for verified: false. The search matches users with an unverified email address and users with an unverified registration.

How Do I Mark an Imported User as Verified?#

To verify the email address or phone number of one user in the Admin UI:

1. Navigate to Users and open the details page of the user.
2. Click the down arrow next to Edit user , then select Verify identity .
3. Select the identity and click Confirm .

The Admin UI can't mark a registration as verified. To verify a registration, or to verify many users at once, use the API:

1. Get a verification Id from the Resend Verification API for an email address, or from the Resend Registration Verification API for a registration. Set sendVerifyEmail or sendVerifyRegistrationEmail to false, so FusionAuth returns the Id without sending an email.
2. Send the verification Id to the Verify Email API or the Verify Registration API.

To skip this step in future imports, set users[x].verified and users[x].registrations[x].verified in the Import Users API.

What Happens When I Enable Both Email and Registration Verification?#

Email verification confirms that the user owns an email address, once per Tenant. Registration verification confirms that the user opted in to one Application. For example, nine Applications in a Tenant might require only email verification, while a tenth Application also requires registration verification.

When a new user signs up for the tenth Application, FusionAuth sends one email: the registration verification email. Completing registration verification also verifies the email address. When an existing user registers for the tenth Application, FusionAuth sends a registration verification email, even if the user already verified their email address.

When you turn off Allow implicit verification in the Tenant, registration verification doesn't verify the email address. Users then verify the registration and the email address separately. The setting is on the Identities tab of the Tenant. See Identity Verification Settings.

Troubleshooting Email 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)

/admin/tenant/edit/00000000...#identities

/admin/tenant/edit/00000000...#identities

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)

/admin/application/edit#registration

/admin/application/edit#registration

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.

/admin/tenant/edit/30663132...#advanced

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

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.

/oauth2/authorize