Identity Pre-Verification Using Email Verification Form

Overview

As of version 1.62.0, FusionAuth can be configured to pre-verify users’ identities, in the registration process, before user creation.

To enable pre-verification, do the following:

• Configure the Tenant Email Server
• Enable verification for the identity type(s) on the tenant
• Create an advanced registration form with the verification step
• Enable self-service registration in your app

Prerequisites

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

• FusionAuth version 1.62.0 or greater. If you already have a FusionAuth instance, see the upgrade guide. To set up your own instance, see the installation guide.

• A licensed paid plan. To buy a plan, visit the pricing page. To activate your instance, visit the Reactor page.

Difference Between Verification, Gating, And Identity Pre-Verification

Verification: user created, attributes updated on user or identity

• Available to both hosted pages (Self-service registration Advanced forms) and API
• No automatic gating you must handle in your application code
• User already exists

Gating: hosted page concept, only enforced on hosted pages

• If you change your email, you won’t run into the gating until you log in again
• Available on hosted pages (Self-service registration Advanced forms) and Self-service registration Basic
• User already exists

Identity Pre-verification: user not created until email has been verified

• Available to both hosted pages and API
• Can add gating manually yourself via API (prevent interactions after login if not verified)
• User doesn’t exist (only Identity does)

FusionAuth’s built-in registration and identity verification flows update the verified and verifiedReason attributes on a user’s registration or on a user identity. You can gate the user (or prevent them from continuing with authentication) 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 stops the user from receiving a JWT or essentially completing the authentication workflow. In this flow, FusionAuth enforces a “gate” for a user until they verify their email or phone. Gating happens after user creation.

Identity 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 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.

When tested successful, save the configuration.

Follow this guide to learn more on how to Configure The SMTP Server

Enable Verification For The Email Identity

Enable identity verification in your tenant by navigating to Tenants -> Edit Tenant -> Identities tab with the following steps:

In the Identity verification settings Email section:

• Enable the Verify identity toggle.
• Select the Email Verification template in the Verification template dropdown.
• All other fields can be left as default or changed based on your needs.

Since there are other scenarios where gating can be applied for existing users, and you need FusionAuth instead of your Application to handle Gate Accounts Until User Email Verified ensure that the Unverified behavior value is Gated.

Create An Advanced Registration Form With The Verification Step

Before you can use the email identity pre-verification during registration, you need to create an Advanced Registration Form that includes a verification step for the email address field.

First, ensure that a mandatory email address Form Field exists. By navigating to Customizations -> Form Fields and create a new Form Field with the Field key user.email and Required set to true, if one does not already exist.

With the Email address form field available, let’s Create a Form for email identity verification during registration.

Navigate to Customizations -> Forms and click Add Form in the upper right. Give the form a Name of Email Verification, then add the following components to the form:

• Add the first step by clicking Add Step -> Form Fields .
• Add the field by clicking Add field , selecting the Field Email address (the email address field you created earlier), and clicking Submit.
• Add the second step: Add Step -> Verification , selecting Email Verification .
• Always add the password field as the final step: Add Step -> Form Fields , selecting the Field Password and clicking Submit.

Enable Self-Service Registration In Your App

With all the previous steps done, you can now enable Advanced Self-service registration by associating the created Advanced Registration Form with an Application, as described in Associate a Form With an Application.

Navigate to Applications -> Your Application -> Registration tab for the Tenant you have enabled Identity verification for.

In the Self-service Registration configuration section:

• Enable the Self-service Registration Enabled toggle.
• Ensure the Registration type is set to Advanced.
• Select the earlier created Email Verification form in the Advanced Registration Form dropdown.
• Save the application.

Test It Out

To test the email identity pre-verification during registration, navigate to the Self-service registration page for your application.

Follow these steps to validate the email identity pre-verification flow:

1. Open your application’s Self-service Registration page. You can find a direct link in the OAuth2 & OpenID Connect Integration details on the Applications -> Your Application -> View in the Details page.
2. Enter a valid email address and click Next to initiate pre-verification.
3. If testing locally, visit MailCatcher at http://localhost:1080/ (or your chosen mock SMTP tool) and open the FusionAuth verification email.
4. Follow the instructions in the email to verify your address. After the successful verification, you will be directed to the last step of setting your password.
5. Once you complete the password step, you will be directed to your application already logged in with a verified email.
6. Confirm the verification status by viewing the user in the admin UI by navigating to Users -> [select user] -> Manage . A verified email displays a green checkmark icon next to the address.

Common Questions

Question: Why is my verification step not showing up in registration?

Answer: There are several reasons why this can happen:

1. The tenant the user is created with does not have verification enabled (forms can be shared with multiple tenants, so there is no guarantee, when the form is created, which tenant the form will be used with).
2. If the user.email field is optional and the user chooses not to enter a value, then verification steps for those fields will be skipped.
3. When registration is being completed for an existing user, to an application, verification steps are skipped, because they only apply to new users. For existing users, see Gate Users Until They Verify Their Email for more details.

Troubleshooting

• No email received
  • Verify the tenant SMTP configuration and send a test message from Tenants -> Email .
  • Check your spam/junk folder and any email filtering or allow-listing rules.
• Verification step is missing on the form
  • In Tenants -> Identities , confirm Verify identity is enabled for Email.
  • In Customizations -> Form Fields , confirm the field key is exactly user.email and it is marked Required.
  • In Customizations -> Forms , ensure the form includes the Email Verification step between the email field step and the password step.
  • In Applications -> Registration , confirm Registration type is Advanced and the correct form is selected.
  • The verification step only runs for new users. If you are registering an existing user to an additional application, the step will be skipped.
• Verification link expired or invalid
  • Verification links expire after a period of time. Trigger a resend from the UI or re-start the flow to generate a new link, then complete verification promptly.
• Users are not Gated with an unverified email.
  • Identity pre-verification happens before user creation. Email registration gating (post-creation) is a separate feature. See Gate Accounts Until User Email Verified.
• Local testing tips
  • When testing locally, use a mock SMTP server such as MailCatcher or MailHog and ensure links in the captured messages point to a routable host for your browser.

How To Use Pre-Verification APIs

You can perform identity pre-verification entirely via API when you are not using hosted pages with Advanced Registration Forms.

• Start Identity Verification
• Send Identity Verification
• Complete Identity Verification

After you have completed identity verification, create the user by calling one of the following APIs and include the corresponding verificationIds from the Start Identity Verification for the verified identity:

• Create a User
• Create a User and Registration Combined

Follow the Identity Pre-Verification Via API tutorial for more details.

Next Steps

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

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