Skip to content

Update user and admin docs, prepare for more screenshots #701

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

Update user and admin docs, prepare for more screenshots #701

wants to merge 1 commit into from
+96 −10

Conversation

jeffpaul
Copy link
Member

@jeffpaul jeffpaul commented Jul 3, 2025

What?

This pull request significantly updates the readme.txt file for the Two-Factor Authentication (2FA) plugin, enhancing user guidance and improving the documentation. Key changes include the addition of detailed setup instructions, descriptions of authentication methods, and answers to frequently asked questions (FAQs).

Enhanced User Guidance:

  • Added comprehensive setup instructions for individual users and site administrators, including steps to enable and configure 2FA methods like TOTP, email codes, and FIDO U2F security keys (readme.txt, readme.txtL13-R91).
  • Included security best practices, such as enabling backup codes and using multiple authentication methods for better protection (readme.txt, readme.txtL13-R91).

Improved Documentation of Authentication Methods:

  • Provided detailed descriptions of each authentication method, including security levels, setup instructions, compatibility, and use cases (e.g., TOTP, email codes, backup codes, FIDO U2F, and dummy method) (readme.txt, readme.txtL13-R91).
  • Highlighted HTTPS and browser compatibility requirements for FIDO U2F keys (readme.txt, readme.txtL13-R91).

Added FAQs and Clarifications:

  • Addressed common questions, such as the absence of site-wide settings, account recovery options, and WebAuthn support. Linked to relevant GitHub issues for further details (readme.txt, readme.txtR123-R141).

Updated Visual References:

  • Expanded the screenshots section to include new visuals, such as the TOTP setup QR code and backup codes interface, to help users better understand the plugin's features (readme.txt, readme.txtR123-R141).

Why?

Closes #699.

How?

Testing Instructions

Screenshots or screencast

Changelog Entry

Changed - Updated WP.org readme with additional user and administrative docs.

@jeffpaul jeffpaul added this to the 0.14.0 milestone Jul 3, 2025
@jeffpaul jeffpaul self-assigned this Jul 3, 2025
@jeffpaul
Copy link
Member Author

jeffpaul commented Jul 3, 2025

@kasparsd related to your thoughts on #699, some questions:

I'll update here once you weigh-in on those questions. I'll work on some additional screenshots to note what I added here as captions in this readme update.

@jeffpaul jeffpaul modified the milestones: 0.14.0, 0.15.0 Jul 3, 2025
kasparsd
kasparsd approved these changes Jul 3, 2025
View reviewed changes
Copy link
Collaborator

@kasparsd kasparsd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great! Amazing work.

To answer your questions:

  1. IMHO none of the magic-link plugins will work if the two-factor is enabled.

  2. I suggest we link to https://wordpress.org/plugins/two-factor-provider-webauthn/ directly because it integrates specifically with the two-factor plugin and does it really well.

kasparsd
kasparsd reviewed Jul 3, 2025
View reviewed changes
readme.txt

## Setup Instructions

**Important**: Each user must individually configure their two-factor authentication settings. There are no site-wide settings for this plugin.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe link to the issue where this is being discussed?

readme.txt
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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe follow the new order in the settings which have app first followed by backup codes (to ensure they have fallback)?

readme.txt

= Why doesn't this plugin have site-wide settings? =

This plugin is designed to work on a per-user basis, allowing each user to choose their preferred authentication methods. This approach provides maximum flexibility and security. Site administrators can still configure 2FA for other users by editing their profiles. For more information, see [issue #437](https://github.com/WordPress/two-factor/issues/437).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we also link to all the available actions/filters in the readme, saying that on larger sites it is recommended to enforce certain requirements via code?

@kasparsd
Copy link
Collaborator

kasparsd commented Aug 9, 2025

@jeffpaul I would like to merge this for the next release. Would you have time to iterate on it now or can we merge it as is and update later?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@kasparsd kasparsd kasparsd approved these changes

Assignees

@jeffpaul jeffpaul

Labels
None yet
Projects
None yet
Milestone
0.15.0
Development

Successfully merging this pull request may close these issues.

Improve user-facing documentation
2 participants
@jeffpaul @kasparsd