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.

By default, the Two-Factor Authentication 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.

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.

Limitations

• Settings are per-environment. For WordPress multisite environments, different settings cannot be applied per-network site.
• If the remove_all_filters() function exists in application code, WordPress Security Controls will not work as expected. 

Access

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“:
   • 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.
2. 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.
3. 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 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.

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

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:

// 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. 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 directory.

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

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

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 directory. For example:

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

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

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

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. To test 2FA locally, add the wpcom_vip_is_two_factor_local_testing filter to a file located within /client-mu-plugins and set it to __return_true.

add_filter( 'wpcom_vip_is_two_factor_local_testing', '__return_true' );