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 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.
This feature is only available in paid editions of FusionAuth. Please visit our pricing page to learn more about paid editions.
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.
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 mailcatcher.and then select the tab. Scroll to the section. Configure this with your SMTP server information. If you are testing locally, you can use a mock email server like
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 toand then select the tab. Scroll to the 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
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
Ensure that the Unverified behavior value is
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
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. Edit your application by clicking on the blue "Edit" button.
Enable self registration by selecting thetab, and then scrolling to the section.
You can create a user with an unverified email address in other ways than self service registration. However, self service registration is the simplest way to create a user without a verified email.
Enable self service registration and configure the displayed and required fields as desired.
Next, navigate to 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 login and will be sent to the configured redirect URL.
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.
How helpful was this page?