Article doesn't do a good job of explaining Only allow secure two-factor methods

[jsoref]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication

What part(s) of the article would you like to see updated?

The text that mentions SMS should be relegated to something approximating a footnote:

For GitHub, the second form of authentication is a code that's generated by an application on your mobile device or sent as a text message (SMS). After you enable 2FA, GitHub generates an authentication code any time someone attempts to sign into your account. The only way someone can sign into your account is if they know both your password and have access to the authentication code on your phone.

Optionally, you can add a passkey to your account. Passkeys are similar to security keys and satisfy both password and 2FA requirements, allowing you to sign in with a single step. However, to reduce the risk of account lockouts, you should also configure a fallback 2FA method, such as a TOTP mobile app or SMS-based authentication. If you have already set up a security key for 2FA that is passkey-eligible, you may be prompted to upgrade it to a passkey during registration. See About passkeys.

Add a section that talks about:

/organizations/:org/settings/security

Only allow secure two-factor methods
Users can only use secure two-factor methods: authenticator apps, passkeys, security keys, and the GitHub mobile app. Learn more about two-factor authentication.

Additional information

The setting for Only allow secure two-factor methods is pretty new and the way it behaves is incredibly surprising. I've spoken to a couple of people and so far everyone has been surprised at the process to enable it and the docs are just this page which doesn't help.

Ideally that view would warn "hey, you observer, your account has SMS enabled, you should go to https://github.com/settings/security and remove it", and ideally it would give an admin a hint about how many accounts would be impacted by this setting (there's a difference between 0, 1-5, and 1000)

[Habbie]

One of these pages should also clarify (if true, because I am not sure) that enabling 'secure' actually disables users that have SMS/text 2FA configured at all. If it is not true, it should also clarify what users would get disabled. I was surprised to find myself in the insecure list while I only ever use TOTP or Yubikey.

[jsoref]

For perspective, here's what that screen shows:

Two-factor authentication

Two-factor authentication adds another level of security for your organization. Learn more about requiring two-factor authentication in your organization.

• Require two-factor authentication for everyone in the fix-runner organization.
  Organization members who do not have two-factor authentication enabled will be unable to access resources owned by the fix-runner organization, but will remain a member of fix-runner until they update their settings. Outside collaborators who do not have two-factor authentication enabled will be removed from the organization and notified. View organization membership to see which users will be impacted.

  • Only allow secure two-factor methods
    Users can only use secure two-factor methods: authenticator apps, passkeys, security keys, and the GitHub mobile app. Learn more about two-factor authentication.

The link at the bottom of this text should have been to Requiring secure methods of two-factor authentication in your organization

[jsoref]

A user in my org reported:

I got a screen telling me something about 2FA. In 2FA page it just say I shouldn't use SMS, not explicitly telling me to delete SMS.

[jsoref]

When this feature is enabled, users will be sent to a screen that might show this:

Nothing in this screen hints that the solution is to remove SMS.

The text in the docs should clearly explain this, and the UI should have a ⚠ saying something like "this option is preventing you from accessing list of organizations because they are requiring better security than this provides".

[Sharra-writes]

@jsoref Thanks for opening this issue! This looks like it's a victim of new changes without time for documentation to catch up, so let me see if there are already plans to update this or if it somehow got overlooked.

[setharnold]

While this is being considered for reworking, please consider also trying to communicate which sets of two-factor methods must be enabled before a user can delete their SMS method. I was surprised that two Yubikeys weren't sufficient, adding the Mobile app wasn't sufficient, and I had to configure a TOTP (or HOTP?) source. Taking two false turns before stumbling on the right answer wasn't great fun.

Thanks

[Sharra-writes]

@setharnold I'll add it to the list of things causing friction in this article. Thanks.