Two Factor

Description

The Two-Factor plugin adds an extra layer of security to your WordPress login by requiring users to provide a second form of authentication in addition to their password. This helps protect against unauthorized access even if passwords are compromised.

Setup Instructions

Important: Each user must individually configure their two-factor authentication settings.

For Individual Users

1. Navigate to your profile: Go to “Users” → “Your Profile” in the WordPress admin
2. Find Two-Factor Options: Scroll down to the “Two-Factor Options” section
3. Choose your methods: Enable one or more authentication providers (noting a site admin may have hidden one or more so what is available could vary):
   • Authenticator App (TOTP) – Use apps like Google Authenticator, Authy, or 1Password
   • Email Codes – Receive one-time codes via email
   • Backup Codes – Generate one-time backup codes for emergencies
   • Dummy Method – For testing purposes only (requires WP_DEBUG)
4. Configure each method: Follow the setup instructions for each enabled provider
5. Set primary method: Choose which method to use as your default authentication
6. Save changes: Click “Update Profile” to save your settings

For Site Administrators

• Plugin settings: The plugin provides a settings page under “Settings → Two-Factor” to configure which providers should be disabled site-wide.
• User management: Administrators can configure 2FA for other users by editing their profiles
• Security recommendations: Encourage users to enable backup methods to prevent account lockouts

Available Authentication Methods

Authenticator App (TOTP) – Recommended

• Security: High – Time-based one-time passwords
• Setup: Scan QR code with authenticator app
• Compatibility: Works with Google Authenticator, Authy, 1Password, and other TOTP apps
• Best for: Most users, provides excellent security with good usability

Backup Codes – Recommended

• Security: Medium – One-time use codes
• Setup: Generate 10 backup codes for emergency access
• Compatibility: Works everywhere, no special hardware needed
• Best for: Emergency access when other methods are unavailable

Email Codes

• Security: Medium – One-time codes sent via email
• Setup: Automatic – uses your WordPress email address
• Compatibility: Works with any email-capable device
• Best for: Users who prefer email-based authentication

FIDO U2F Security Keys

• Deprecated and removed due to loss of browser support.

Dummy Method

• Security: None – Always succeeds
• Setup: Only available when WP_DEBUG is enabled
• Purpose: Testing and development only
• Best for: Developers testing the plugin

Important Notes

HTTPS Requirement

• All methods work on both HTTP and HTTPS sites

Browser Compatibility

• TOTP and email methods work on all devices and browsers

Account Recovery

• Always enable backup codes to prevent being locked out of your account
• If you lose access to all authentication methods, contact your site administrator

Security Best Practices

• Use multiple authentication methods when possible
• Keep backup codes in a secure location
• Regularly review and update your authentication settings

For more information about two-factor authentication in WordPress, see the WordPress Advanced Administration Security Guide.

For more history, see this post.

Actions & Filters

Here is a list of action and filter hooks provided by the plugin:

• two_factor_providers filter overrides the available two-factor providers such as email and time-based one-time passwords. Array values are PHP classnames of the two-factor providers.
• two_factor_providers_for_user filter overrides the available two-factor providers for a specific user. Array values are instances of provider classes and the user object WP_User is available as the second argument.
• two_factor_enabled_providers_for_user filter overrides the list of two-factor providers enabled for a user. First argument is an array of enabled provider classnames as values, the second argument is the user ID.
• two_factor_is_required_for_user filter controls whether two-factor authentication is required for a user. Return false to bypass the two-factor flow (e.g. for trusted IP addresses). First argument is a boolean (whether the user has a primary provider configured), the second argument is the WP_User object.
• two_factor_fallback_provider_for_user filter overrides the provider forced on when none of a user’s stored two-factor providers are still registered (e.g. after a provider plugin is deactivated). Defaults to Two_Factor_Email. First argument is the provider classname, the second is the user ID, the third is the array of provider classnames that were stored for the user but are no longer registered. The returned provider must be registered and available to the user (is_available_for_user()), or the user is shown an error instead of being let through with a fallback.
• two_factor_user_authenticated action which receives the logged in WP_User object as the first argument for determining the logged in user right after the authentication workflow.
• two_factor_user_api_login_enable filter restricts authentication for REST API and XML-RPC to application passwords only. Provides the user ID as the second argument.
• two_factor_email_token_ttl filter overrides the time interval in seconds that an email token is considered after generation. Accepts the time in seconds as the first argument and the ID of the WP_User object being authenticated.
• two_factor_email_token_length filter overrides the default 8 character count for email tokens.
• two_factor_backup_code_length filter overrides the default 8 character count for backup codes. Provides the WP_User of the associated user as the second argument.
• two_factor_rest_api_can_edit_user filter overrides whether a user’s Two-Factor settings can be edited via the REST API. First argument is the current $can_edit boolean, the second argument is the user ID.
• two_factor_before_authentication_prompt action which receives the provider object and fires prior to the prompt shown on the authentication input form.
• two_factor_after_authentication_prompt action which receives the provider object and fires after the prompt shown on the authentication input form.
• two_factor_after_authentication_input action which receives the provider object and fires after the input shown on the authentication input form (if form contains no input, action fires immediately after two_factor_after_authentication_prompt).
• two_factor_login_backup_links filters the backup links displayed on the two-factor login form.
• two_factor_login_nonce_failed action which fires when a login nonce fails verification. Provides the ID of the user the nonce was presented for as the first argument, and the reason as the second: no_nonce_stored, expired, or mismatch.
• two_factor_log_login_nonce_failures filter overrides whether a failed login nonce verification is written to the PHP error log. Defaults to true for expired and mismatch, and false for no_nonce_stored, which any unauthenticated request can reach. Provides the user ID as the second argument and the reason as the third.

WP-CLI Commands

The plugin includes a wp two-factor WP-CLI namespace for managing two-factor authentication from the command line. All commands accept a user by ID, login, or email.

• wp two-factor status <user> — Shows a user’s current 2FA status (read-only). Supports --format=json.
• wp two-factor list-providers — Lists all registered two-factor providers.
• wp two-factor enable <user> <provider> — Enables a provider for a user. Providers that require a shared secret (like TOTP) can’t be enabled this way and will point you to the profile page instead.
• wp two-factor disable <user> [<provider>] — Disables a single provider, or performs a full reset of all 2FA for the user when no provider is given. Both forms prompt for confirmation unless --yes is passed.
• wp two-factor backup-codes generate <user> [--count=<n>] — Generates a fresh set of backup codes for a user, replacing any existing ones. Defaults to 10 codes.
• wp two-factor unlock <user> — Clears a user’s login rate-limit/throttle without changing their 2FA configuration.

Run wp help two-factor for the full list, or wp help two-factor <command> for options and examples for a specific command.

Redirect After the Two-Factor Challenge

To redirect users to a specific URL after completing the two-factor challenge, use WordPress Core built-in login_redirect filter. The filter works the same way as in a standard WordPress login flow:

add_filter( 'login_redirect', function( $redirect_to, $requested_redirect_to, $user ) {
    return home_url( '/dashboard/' );
}, 10, 3 );

Technical details