Title: Enforce Two-Factor Authentication
Author: WordPress VIP Documentation
Published: September 17, 2020
Last modified: March 10, 2026

---

 1. [Security Controls](https://docs.wpvip.com/security-controls/)
 2. [WordPress Security Controls](https://docs.wpvip.com/security-controls/wordpress/)
 3. Enforce Two-Factor Authentication

#  Enforce Two-Factor Authentication

Two-factor authentication (also known as 2FA) is a method for securely granting 
users access to a site or application. This method requires a user to _know_ something(
e.g. a password), and requires a user to _possess_ an object (e.g. their mobile 
device or a hardware security key) or a unique biological trait (e.g. a fingerprint).
Requiring multiple forms of verification is a basic way to protect a site against
security compromises due to leaked or guessed passwords.

The Two-Factor Authentication plugin also applies protection to a site’s XML-RPC
and WP REST API endpoints. If 2FA is enabled for a WordPress user’s account, their
login credentials cannot be used to authenticate the XML-RPC or WP REST API endpoint.
If 2FA is disabled, a user’s credentials—if obtained by a bad actor—could be used
to authenticate those endpoints and perform nefarious actions.

Settings to enforce 2FA for user roles based on their capabilities can be managed
in the Enforce Two-Factor Authentication module of [the **WordPress Security Controls** panel](https://docs.wpvip.com/security-controls/wordpress/).

By default, the [Two-Factor Authentication](https://github.com/WordPress/two-factor)
plugin is active on all WordPress sites on the VIP Platform and provides several
options for user authentication (e.g., Authenticator App, SMS, Email). On a new 
WordPress environment, 2FA is enforced for all users that have an Editor, Administrator,
or Super Admin (WordPress multisite) role.

**Note**

WordPress environments that existed prior to the release of **WordPress Security
Controls** were created with a default setting of 2FA enforcement only for Administrator
and Super Admin roles.

## Limitations

 * Settings are per-environment. For WordPress multisite environments, different
   settings cannot be applied per-network site.
 * **WordPress Security Controls** [utilizes a specific set of filters](https://github.com/Automattic/vip-security-boost/).
   If these filters are removed in custom application code, the feature will not
   work as expected.

## Access

**Prerequisite**

To access and manage settings for Enforce Two-Factor Authentication in the **WordPress
Security Controls** panel, a user must have an [App write role](https://docs.wpvip.com/manage-user-access/vip-dashboard/app-role/)
for an application or an [Org admin role](https://docs.wpvip.com/manage-user-access/vip-dashboard/org-roles/).

To access settings for Enforce Two-Factor Authentication in the **WordPress Security
Controls** panel in the VIP Dashboard:

 1. Navigate to the VIP Dashboard for an application.
 2. Select an environment from the dropdown located at the upper left of the dashboard.
 3. Select “**Security Controls**” from the sidebar navigation at the left of the screen.
 4. Select “**WordPress**” from the navigation submenu.
 5. Select the accordion module titled “**Enforce Two-Factor Authentication**“.

## Configure

In the Enforce Two-Factor Authentication module of **WordPress Security Controls**,
configure a mode of 2FA enforcement for users based on the capabilities of their
user roles.

 1. Select one of the enforcement modes listed below the label “**2FA Requirements**“:
 2.  * **Elevated Security:** All users with a role that can create and edit content(
       i.e. Administrator, Editor, Author, Contributor)
     * **Default:** All users who can edit and publish the content of other users (
       i.e. Administrator, Editor)
     * **Customize:** Enforce 2FA for a group of users selected from the list of options
       labeled “**User Capabilities**” based on the capabilities of their role.
 3. If configuring the Enforce Two-Factor Authentication module for a production environment,
    optionally toggle the box labeled “**Apply these settings to all environments in
    this application**” to apply the 2FA configurations to all of the application’s
    environments.
 4. Select the button labeled “**Save Changes**” to apply the updated setting to the
    environment.

### Notice banners in the WordPress Admin dashboard

A notice banner will be displayed at the top of [the Users screen](https://wordpress.org/documentation/article/users-screen/)
in the WordPress Admin dashboard if any users on a site with an Administrator or
Editor role do not have 2FA enabled for their accounts.

This banner will _not_ display if:

 * All users with Administrator or Editor roles have 2FA enabled.
 *  2FA has been code-disabled for an environment.

![](https://docs.wpvip.com/wp-content/uploads/sites/2/2025/09/2FA-Disabled-1024x71.
png)

Example screenshot of 2FA notice banner in the WordPress Admin dashboard

## Enforce 2FA with custom code

Whenever possible, configurations for 2FA enforcement should be made in the **WordPress
Security Controls** panel. Enforcing 2FA in custom code might be necessary in some
situations, for example to enforce 2FA for custom user roles or for capabilities
other than those listed in the “User Capabilities” section of Enforce Two-Factor
Authentication in the VIP Dashboard.

If 2FA is enforced in custom code, the logic for enforcement in the custom code 
will not be represented in the settings of the Enforce Two-Factor Authentication
module.

### Code-enforce 2FA for custom user roles and specific capabilities

**Note**

`wpcom_vip_is_two_factor_forced` is a legacy filter that can be used to enforce 
2FA for specific [roles and capabilities](https://wordpress.org/support/article/roles-and-capabilities/#capabilities).
Because this filter will eventually be deprecated, it is recommended to discontinue
the use of this filter and manage 2FA enforcement in **WordPress Security Controls**
instead. Or, transition to using the `vip_wsc_forced_mfa_users_additional_capabilities`
filter to enforce 2FA by capabilities that cannot be configured in the Enforce Two-
Factor Authentication module.

Use the `vip_wsc_forced_mfa_users_additional_capabilities` filter to enforce 2FA
for users that have a specific capability. This filter is only effective for capabilities
that are not already configurable in the Enforce Two-Factor Authentication module.

In this code example, 2FA is enforced for all users that have been granted an `upload_files`
capability:

/client-mu-plugins/example-plugin.php

    ```lang-php
    // In addition to the 2FA enforcement settings in WordPress Security Controls, enforce 2FA for all users who have been granted the capability to upload files.

    add_filter( 'vip_wsc_forced_mfa_users_additional_capabilities', function () {

        return [ 'upload_files' ];
    } );
    ```

#### Legacy filter

`wpcom_vip_is_two_factor_forced` is a legacy filter that can be used to enforce 
2FA for specific [roles and capabilities](https://wordpress.org/support/article/roles-and-capabilities/#capabilities).
2FA that is enforced for specific roles or capabilities by the `wpcom_vip_is_two_factor_forced`
filter will override any 2FA enforcement settings in the **WordPress Security Controls**
panel.

This code will only work as expected if it is added to a file within the [`client-mu-plugins`](https://docs.blah.vipdev.lndo.site/wordpress-skeleton/client-mu-plugins-directory/)
directory.

In this code example, 2FA is enforced for all user roles that have the `moderate_comments`
capability:

/client-mu-plugins/example-plugin.php

    ```lang-php
    add_action( 'set_current_user', function() { 
        $limited = current_user_can( 'moderate_comments' );
        add_filter( 'wpcom_vip_is_two_factor_forced', function() use ( $limited ) {
            return $limited;
        }, PHP_INT_MAX );
    } );
    ```

### Code-enforce 2FA for all users

**Note**

The enforcement of 2FA for all user accounts of a WordPress site is a configuration
option in **WordPress Security Controls**. It is recommended to discontinue 2FA 
enforcement in application code as soon as possible and transition to 2FA management
in **WordPress Security Controls** instead.

To code-enforce 2FA for all users on an environment, set the `wpcom_vip_is_two_factor_forced`
filter to `__return_true` in a file added to the [`client-mu-plugins`](https://docs.blah.vipdev.lndo.site/wordpress-skeleton/client-mu-plugins-directory/)
directory. For example:

/client-mu-plugins/example-plugin.php

    ```lang-php
    add_filter( 'wpcom_vip_is_two_factor_forced', '__return_true' );
    ```

Custom code that enforces 2FA for all user accounts on a WordPress environment with
the legacy filter `wpcom_vip_is_two_factor_forced` set to `__return_true` will override
any other settings that are made for 2FA enforcement in the environment’s **WordPress
Security Controls** panel.

### Code-disable enforcement of 2FA for all users

**Caution**

**Disabling 2FA for all users is strongly discouraged.**

If 2FA for users is code-disabled, the site’s XML-RPC endpoint should also be disabled
to maintain site security. To disable the XML-RPC endpoint without blocking necessary
calls made by Jetpack, set [the XML-RPC Authentication module](https://docs.wpvip.com/security-controls/wordpress/xml-rpc/)
in the **WordPress Security Controls** panel to the “Disable authentication” mode.

It is possible to code-disable the enforcement of 2FA for all users by setting the`
wpcom_vip_is_two_factor_forced` filter to `__return_false`. Disabling 2FA enforcement
for all users in application code will override any settings for 2FA enforcement
in the **WordPress Security Controls** panel.

Setting `wpcom_vip_is_two_factor_forced` to `__return_false` will disable the _enforcement_
of 2FA, but users will still have the option to enable and configure 2FA for their
individual account. In addition, 2FA will remain active for users that had a 2FA
method enabled prior to the filter being set to `__return_false`.

This code will only work as expected if added to a file within the [`client-mu-plugins`](https://docs.blah.vipdev.lndo.site/wordpress-skeleton/client-mu-plugins-directory/)
directory.

/client-mu-plugins/example-plugin.php

    ```lang-php
    add_filter( 'wpcom_vip_is_two_factor_forced', '__return_false' );
    ```

## Enable 2FA for a user’s individual account

For a user to enable 2FA for their existing WordPress account on a site:

 1. Access the WordPress Admin dashboard by logging in with the account’s username 
    and password.
 2. Select “**Users** > **Profile**” from the the navigation sidebar to access the 
    setting options for the user account.
 3. In the section titled “**Two-Factor Options**“, select the preferred authentication
    method(s)
 4. Select the “**Update Profile**” button to save the updated settings.

## Reset 2FA for a locked out user

**Prerequisite**

To assist other users that are locked out of their user account for reasons related
to 2FA, a user must have an [Administrator](https://wordpress.org/support/article/roles-and-capabilities/#administrator)
or [Super Admin](https://wordpress.org/support/article/roles-and-capabilities/#super-admin)
role for that site

Before an Administrator or Super Admin disables or resets 2FA for a user, confirm
that the user has indeed lost access to their account. Because emails can be faked,
confirm with the individual in person or over the phone.

Once the Administrator or Super Admin have confirmed the user’s identity:

 1. Log into the site to access the WordPress Admin dashboard.
 2. Select “**Users**” from the the navigation sidebar.
 3. Search for the locked out user by their email address or username.
 4. Select the user’s username from the search results.
 5. In the “**Two-Factor Options**” section of the user’s profile, complete one of 
    the following options:

 * **Option 1: Deselect all available two-factor methods. **
   This will allow the
   user to login without needing any additional code.
 * **Option 2: Enable the Backup Verification Codes option. **
   Select the “**Generate
   Verification Code**” button to generate a one-time use code.Send the backup code
   to the user to log in to their account.

Once the user regains access to their account, they should make additional updates
to their 2FA settings to prevent losing access in the future (e.g. resetting the
phone number). The user should also print out their backup codes to prevent future
lockouts.

## Test 2FA on a local environment

By default, the enforcement of 2FA is disabled on [the VIP Local Development Environment](https://docs.wpvip.com/vip-local-development-environment/).
To test 2FA locally, add the `wpcom_vip_is_two_factor_local_testing` filter to a
file located within `[/client-mu-plugins](https://docs.wpvip.com/wordpress-skeleton/client-mu-plugins-directory/)`
and set it to `__return_true`.

/client-mu-plugins/example-plugin.php

    ```lang-php
    add_filter( 'wpcom_vip_is_two_factor_local_testing', '__return_true' );
    ```

Last updated: March 10, 2026