This page describes the settings for Two-Factor Authentication and reCAPTCHA. For help setting up 2FA on your login or logging into a site using 2FA, click here.

Two-Factor Authentication Options

User Summary

This table counts the total users for each user role and the number of users with 2FA active or inactive. On sites with a large number of users, counts are replaced with a “Show User Counts” button, since counting WordPress users by role can be slow. Clicking the button will show the table, but may take several seconds on some sites.

If you have required 2FA for some roles, the “2FA Inactive” column will also include a link to view users who will have 2FA required but have not yet set it up in their accounts. Click the link to see which users are still in the grace period, and which have been locked out.

Users who have custom capabilities outside of a normal role or users who have multiple roles are counted under “Custom Capabilities / Multiple Roles”.

Note: For multisite installations, only the main site is currently counted here. The WordPress “Users” page for each sub-site can be used to see which users have 2FA activated or inactive, and users who have been locked out when 2FA is required for their role.

2FA Roles

By default, only admins are allowed to use 2FA, or super-admins on multisite installations. You can enable 2FA for other roles on the site, and each user can manage their own 2FA devices. Non-admin users will see a separate Login Security menu on the WordPress menu, when you enable 2FA for their roles.

For each role, you can choose from the following:

• Required – This role will need to have 2FA enabled in order to log in. Users are granted a grace period by default, from the date that this option is enabled.
• Optional – This role can use 2FA, but is not required to enable it.
• Disabled – This role cannot use 2FA. This choice is not available for administrators.

Important: When 2FA is required for admins, the requirement does not apply until at least one admin has set up 2FA. This prevents you from locking out all admins by mistake, if you log out before setting up 2FA, or if your session expires. In addition, requiring 2FA for customers on e-commerce sites is not recommended as some customers may experience difficulties setting up or using two-factor authentication. Instead, using the “Optional” mode for users with the customer role is recommended, which will allow customers to enable 2FA, but will not require them to do so.

Please note that some users will lose their 2FA codes over time, often from a lost or broken phone. If the user also did not save their backup codes, or saved them on the same device, they may not be able to log in. You may need to disable 2FA for them, but you should validate their identity, to be sure that someone is not trying to take over their account with a stolen password.

By default, users must be able to see wp-admin pages in order to set up 2FA. If you use WooCommerce, you can enable “Show Wordfence 2FA menu on WooCommerce Account page” to allow the Customer role to see the 2FA settings on their account page. If you use a membership or forum plugin that does not allow low-privileged roles to see wp-admin, you can enable “2FA Management Shortcode”, and place a shortcode on the user’s account page. In some cases, using these options may require CSS changes, if the color or layout of the form needs to be adjusted. We recommend checking any customized pages while logged in as a customer or subscriber (or any other low-privileged user), when enabling this option.

Grace Period

When 2FA is set to “Required” for a role, a grace period allows the users a number of days to set up 2FA before they will be locked out. If a user is locked out, an admin will need to allow them to log in again. The default is 10 days, based on when the “Required” option was set, or the account’s creation date, whichever is newer.

Admins (or super-admins on multisite) do not get a grace period by default. When creating an admin, you can choose the option “Allow a grace period for this user prior to requiring Wordfence 2FA”, if necessary.

If a user is locked out, you can set a grace period for that specific user on their Profile page or the 2FA page for that user. You can also revoke a grace period that was set manually.

When 2FA is required for a role, you can also choose to send an email notification to users in that role, using the drop-down list below the Grace Period setting. Choose a role and click the Notify button, to send an email to users who are still in the grace period. We recommend explaining 2FA to your users who will be affected first, and using this email as a reminder.

Important: If you set the Grace Period to 0 and set any role set to “Required”, then users in that role who do not have 2FA enabled will not be able to log in. This includes newly-created users. You would need to manually allow a grace period for each user if you set the Grace Period to 0. Alternately, you could create users in a lower role that has 2FA set to “Optional”, and only promote their accounts to a higher role after they have set up 2FA.

2FA Notifications

The fields for “2FA Role” and “2FA Relative URL (optional)”  are available for roles where the 2FA role is set to “Required” and a “Grace Period” is defined. In that event, you can define a relative URL, such as /my-account/ for WooCommerce, and can also include a query string or fragment, if needed. If left undefined, the email will send a link to the recipients with the standard link to the Login Security plugin page. Once the role and optional URL field are completed, you can click the “Notify” button to send an email to the appropriate role on the site, notifying them of the date 2FA needs to be setup.

Allow remembering device for 30 days

When this option is enabled, users can click a checkbox to remember their device for 30 days. This sets a cookie unique to their device that will allow them to log in without using 2FA from that device and browser. This feature is for convenience, but it is less secure than requiring 2FA for each login.

Require 2FA for XML-RPC call authentication

This option is set to “Required” by default, to prevent logins without 2FA via xmlrpc.php. Attackers often target xmlrpc.php with password guessing attacks, so it is important to keep this feature enabled if possible.

Plugins, features, and external apps or services that require authenticated XML-RPC calls are usually not compatible with this option. For example, if you use the WordPress app on your phone with a user account that uses 2FA, you will most likely need to set this option to “Skipped”, unless you have specific IPs or ranges you can safely add to the allowlist.

Custom applications that log in via XML-RPC may be made compatible if they can generate a TOTP code and append the current code to the password during authentication. Codes still expire after the first use, so this may not be practical if your custom application may send authenticated requests more than once every 30 seconds. If you are developing a new app or integration, then using the Application Passwords feature added in WordPress 5.6 may be the best solution, and should be implemented using the Authorization HTTP header.

Disable XML-RPC authentication

This option rejects all XML-RPC requests that require authentication, whether they have a valid username and password or not. It applies to all logins, not only those for users with 2FA enabled.

This option is not compatible with the WordPress phone app, the Jetpack plugin, or most other services that use XML-RPC with a WordPress username and password.

WooCommerce and Custom Integrations

WooCommerce integration

Enable this checkbox if you are using WooCommerce and would like Wordfence Login Security features such as the reCAPTCHA and 2FA to work on the WooCommerce Account page. We recommend testing your login pages after enabling this option, to be sure there are no conflicts with other plugins that modify the login page. Currently, the CAPTCHA is not compatible with the WooCommerce option “Allow customers to create an account during checkout” as it is only applied on the default, standalone WooCommerce registration form. However, the CAPTCHA icon can appear on the checkout page if “Allow customers to log into an existing account during checkout is enabled” because it is applied to WooCommerce login forms.

Show Wordfence 2FA menu on WooCommerce Account page

This option will remain disabled until the “WooCommerce Integration” is first enabled and saved. When enabled, a Wordfence 2FA tab will be added to the WooCommerce account menu which will provide access for users to manage their 2FA settings outside of the WordPress admin area. If you allow the “Customer” role to use 2FA, this will be the only place they can set up 2FA, since they cannot see wp-admin pages. Testing the WooCommerce account interface after enabling this feature is recommended to ensure theme compatibility.

2FA Management Shortcode

When enabled, the “wordfence_2fa_management” shortcode may be used to provide access for users to manage 2FA settings on custom pages. Depending on how your site is built, you may be able to simply use the shortcode in your user account page template, but in other cases, you may need to edit PHP files. If you’re not familiar with modifying PHP files, you will want to enlist the help of a developer to put this in place. You will also likely need to customize styles to make the 2FA setup fit with your site. Testing this shortcode with your site setup is necessary to verify theme and plugin compatibility.

This option is not necessary for sites where users can see the “Login Security” menu when using wp-admin/ or when using the separate option to show the 2FA menu on the WooCommerce account page.

Use single-column layout for WooCommerce/shortcode 2FA management interface

When enabled, Wordfence will use a vertical stacked layout as opposed to horizontal columns for the 2FA management interface embedded through the WooCommerce integration or via a shortcode. Adjust this setting as appropriate to match your theme. This may be overridden using the “stacked” attribute for individual shortcodes.

reCAPTCHA

This CAPTCHA implementation uses Google’s reCAPTCHA v3. See documentation from Google for more details:

https://developers.google.com/recaptcha/docs/v3

Enable reCAPTCHA on the login and user registration pages

Please note that our Google reCAPTCHA feature currently only works for the default WordPress login and registration pages and also the default WooCommerce login and registration page so it may not work on custom login and registration pages generated by your theme or other plugins.  Enabling this feature will add a CAPTCHA test to WordPress’s login and registration forms. After enabling the checkbox you will need to enter a Site Key and Secret Key, available below. Currently you will need to press the “v3 Admin Console” button and not the “Get Started” button:

https://www.google.com/recaptcha/about/

Note: To use the CAPTCHA on the default WooCommerce login and registration page, you must also enable “WooCommerce integration”. We recommend testing your WooCommerce login forms after enabling this option, to be sure there are no conflicts with other plugins that modify login forms.

How it works

When this feature is enabled, it displays a reCAPTCHA logo on the WordPress login and registration forms. Unlike older CAPTCHA implementations, it does not require the user to read distorted letters, click road signs, or click a checkbox. Instead, Google calculates a score for each user.

One drawback is that you cannot see the reason that Google has given a lower score. There may be cases where a real user is blocked from logging in or registering, if Google determines that they may be a bot.

Scores from each user’s last login attempt are shown on the standard WordPress Users page. Keep in mind that it may be from the user attempting to log in, or a bot attempting to log in with their username. Scores are also aggregated in a chart on the login security settings page, including both good and bad login attempts.

The reCAPTCHA service requires scripts that are loaded from Google and calls to their servers to validate that visitors are real people.

What users will see

Generally, most users should see only a Google reCAPTCHA logo on the login and registration pages.

If any valid users get a low score from Google reCAPTCHA and are blocked while logging in, they will see a message saying “Additional verification is required for login”, and asking them to check their email. They should receive an email with a link that will allow them to log in.

Users with 2FA enabled will automatically skip the CAPTCHA scoring if entering the passsword and 2FA code together in the password field, since they are already required to enter a valid 2FA code.

If registration is enabled on your site and a user is blocked from registering due to a low score from reCAPTCHA, they are shown a form to send a message to the main admin email address listed on the WordPress General settings. This is necessary since there is no user record with a known email address for them yet. This form is rate-limited, so bots cannot send repeated requests.

reCAPTCHA human/bot threshold score

You can adjust the threshold used by the captcha if it is too strict or too lenient for your site. The default value is 0.5. You can use the score history chart described below to see the typical scores for your site. If valid users are sometimes blocked by the captcha, you can set the score lower to 0.4 or 0.3 if necessary. If bots are being allowed too often, you can raise the score to 0.6 or 0.7 for example.

reCAPTCHA score history

This chart aggregates the scores for any login attempts, from both humans and bots. Typically you should see a spike toward the high end (users) and the low end (bots). You can use these results to decide if you need to adjust the threshold above. You can reset the chart using the “Reset Score Statistics” link below it.

If scores of 0.0 appear common and regular users are sent validation emails, you may have a conflict with another plugin’s javascript, a caching issue, or an incorrect reCAPTCHA key.

Run reCAPTCHA in test mode

When this option is enabled, the captcha will record scores in the chart above but it will not block bots or visitors.

This is intended to be used for a short period — likely a few days or a few hours, depending on your traffic — to decide on whether you need to set the threshold above or below the default of 0.5 or to check for conflicts with other plugins or themes. Because it is important to remember to disable test mode, since the captcha will not block bots during testing, this option adds an admin notice that can be dismissed only by disabling test mode.

Customizing CAPTCHA behavior with WordPress filters

You can customize some aspects of the CAPTCHA process with WordPress filters in your theme’s functions.php file, or in custom plugins.

The filter “wfls_registration_blocked_message” can be used to customize the message when registration is blocked. You can write a custom message to replace the default message and admin contact link, for example, directing the visitor to email you or complete a different contact form. Your filter should return the message that you want to display to the visitor. As an example, if you want people to visit your page at /contact/ when blocked:

function my_wfls_registration_blocked_message() {
	return '<strong>REGISTRATION BLOCKED</strong>: Registration could not be completed. Please visit our <a href="/contact/">contact page</a> for help.';
}
add_filter('wfls_registration_blocked_message', 'my_wfls_registration_blocked_message');

The filter “wordfence_ls_require_captcha” can be used to disable the CAPTCHA in circumstances of your choice. This may be useful for plugins that contain REST endpoints with authentication that should not require a CAPTCHA. Your filter should return false to bypass the CAPTCHA requirement when necessary, or otherwise true when the CAPTCHA should be required.

General

Allowlisted IP addresses that bypass 2FA and reCAPTCHA

This field accepts IP addresses or ranges where 2FA and the CAPTCHA will not be required. You can use this to skip 2FA on networks you trust, like if you have a static IP and want to skip 2FA when connecting from your usual location. Another example is if you have a network with a trusted range of IPs, such as allowing users on your corporate network to log in without 2FA unless they are logging in from outside the network.

How to get IPs

When using the standalone Wordfence Login Security plugin without the full Wordfence plugin, you will see choices for how the plugin gets visitor IP addresses. This is important if you use the allowlist feature, to be sure the plugin can detect visitors’ IPs. In most cases, you can leave this set to the default value, “Use the most secure method to get visitor IP addresses.” If the correct IP is not shown, you can choose one of the other options, based on how your server has been set up.

A preview of your detected IP appears below the choices. If you know your public IP address, you can compare it to this, to be sure the correct IP is detected.

If your server is behind one or more proxies, you can click “Edit trusted proxies” to add the proxy IP addresses or ranges.

If you are using the full Wordfence plugin, the “How to get IPs” section does not appear, since the full plugin has a similar section, and enhanced automatic detection.

NTP

Wordfence Login Security uses NTP (Network Time Protocol) to check if your server’s clock is correct or if an adjustment needs to be applied. The accuracy of the clock is necessary for authenticator devices to generate a valid code for two-factor authentication.

Many shared hosts block NTP access, so Wordfence will disable its use of NTP if it detect multiple failures over a few hours. This will reset periodically, in case it was a temporary failure. Fortunately, most hosts correctly maintain their server clocks, so if this option has been automatically disabled, 2FA can often continue working without issues.

You can enable this option if it was automatically disabled, in order to try again, or you can disable it if you do not want your site to use NTP.

Delete Login Security tables and data on deactivation

This checkbox can be used to remove the Login Security tables and data. If the checkbox is enabled when the plugin is deactivated, the data will be removed at that time, including all settings, users’ 2FA codes, and backup codes. This will reset the plugin to its default state if you enable it again, and users would need to set up 2FA on their accounts again.