Add: Site-wide Two-Factor enforcement per user role

[masteradhoc]

Fixes #846

What?

Adds a Two-Factor Enforcement section to the plugin's settings page that lets administrators require 2FA for specific user roles.

Why?

There is no built-in way to mandate Two-Factor authentication for all users in a given role. Site owners — especially those running membership or multi-user sites — need a way to enforce 2FA for existing users and automatically enroll new users without requiring each user to opt in manually.

See: https://wordpress.org/support/topic/can-i-by-default-turn-on-this-feature-for-all-my-existing-and-for-new-user/ or #307

How?

Three files were changed:

settings/class-two-factor-settings.php

• Saves a new two_factor_enforced_roles option (array of role slugs) alongside the existing provider option.
• Renders a new "Two-Factor Enforcement" section below "Enabled Providers" with a checkbox per registered role (including custom roles).
• Shows an admin notice warning when enforcement is active but the Email provider has been disabled site-wide, because enforcement cannot safely fall back to providers like TOTP that require prior per-user setup (e.g. scanning a QR code) before they can authenticate.

two-factor.php

• two_factor_enforce_for_user() — hooked on two_factor_enabled_providers_for_user at priority 20. If a user belongs to an enforced role but has no provider configured, the Email provider is injected at runtime so they are challenged on their next login without any manual setup. If the Email provider is disabled site-wide, the function returns unchanged (fails closed) rather than injecting a provider the user has not configured.
• two_factor_force_on_user_register() — hooked on user_register. Writes _two_factor_enabled_providers meta immediately for new users in an enforced role, so enforcement applies from their very first login. Skipped if the Email provider is disabled site-wide.

class-two-factor-core.php

• uninstall() now also deletes two_factor_enabled_providers and two_factor_enforced_roles so no orphaned options are left behind when the plugin is removed.

Testing Instructions

1. Install and activate the plugin on a site with multiple user roles.
2. Go to Settings → Two-Factor and confirm the new "Two-Factor Enforcement" section appears below "Enabled Providers".
3. Check one or more roles (e.g. Subscriber) and click Save Settings.
4. Confirm the checkboxes persist after saving.
5. Log in as a user in an enforced role who has not configured 2FA — confirm they are challenged for an email verification code.
6. Create a brand-new user in an enforced role and verify that their _two_factor_enabled_providers user meta is set to ["Two_Factor_Email"] immediately after registration.
7. Log in as that new user and confirm the 2FA challenge appears.
8. Uncheck a role, save, and confirm users in that role are no longer challenged.
9. Disable the Email provider under "Enabled Providers" while keeping a role enforced — confirm the admin notice warning appears and that users in the enforced role are not challenged (no silent fail-open).
10. Uninstall the plugin and confirm neither two_factor_enabled_providers nor two_factor_enforced_roles remain in the options table.

Screenshots or screencast

Changelog Entry

Added - New "Two-Factor Enforcement" settings section allowing administrators to require 2FA for specific user roles, with automatic Email-provider enrolment for existing users at login and for new users at registration. An admin notice is shown if enforcement is active but the Email provider is disabled.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @thomasfedb.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: thomasfedb.

Co-authored-by: masteradhoc <masteradhoc@git.wordpress.org>
Co-authored-by: georgestephanis <georgestephanis@git.wordpress.org>
Co-authored-by: dknauss <dpknauss@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Copilot]

Pull request overview

Adds role-based Two-Factor enforcement to the plugin, allowing admins to mandate 2FA for selected user roles via the settings UI and automatically apply enforcement for existing users (at login) and new users (at registration).

Changes:

• Persist a new two_factor_enforced_roles option and render a role-checkbox “Two-Factor Enforcement” section on the settings page.
• Enforce 2FA for users in enforced roles by injecting a provider when the user has none enabled.
• Auto-enable a provider for newly registered users in enforced roles by writing 2FA user meta on user_register.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
two-factor.php	Adds enforcement filter for role-based 2FA and auto-enrollment on registration.
settings/class-two-factor-settings.php	Adds settings UI + saves enforced roles option.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[thomasfedb]

@masteradhoc I would be very keen to roll this out. Is there anything that can be contributed to getting this merged?

[masteradhoc]

Thanks for your comment @thomasfedb. If you could help test this PR and share your feedback that would be amazing and a good step forward!

[thomasfedb]

Thanks for your comment @thomasfedb. If you could help test this PR and share your feedback that would be amazing and a good step forward!

@masteradhoc I've now tested this branch properly. Summary: it works as described, and I've sent tests your way.

• Ran the full PHPUnit suite on the branch.
• Verified the key behaviors in a live WP 6.8.2 test environment: Email injection for enforced roles, existing user configurations left untouched, enrolment at registration, and the fail-closed path when the Email provider is disabled site-wide (the earlier fail-open concern from the bot review is fixed in the current revision).
• Opened Add tests for role-based Two-Factor enforcement masteradhoc/two-factor#4 against your branch adding test coverage for all of the above.

[masteradhoc]

Thank you, @thomasfedb, for your work on testing and writing the unit tests. I’ve merged them.
As soon as another contributor has had a chance to review the PR, we’ll get this one merged. :)

We’re always happy to receive your insights, code contribution and/or testing support on any open PR whenever you have the time.

[thomasfedb]

@masteradhoc any updates on getting this change live?

[masteradhoc]

@thomasfedb Currently part of the team is working on the 7.1 Release. I hope to get more contributors back as soon as the release is fully done :)

[georgestephanis]

My only uncertainty is if there's not a workable bypass mechanism for broken outbound mail system or something. Which would probably just be to use wp-cli or phpmyadmin to override the setting or something. So it should be fine?

[thomasfedb]

@georgestephanis do you know when this will go into a release?