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

[jsoref]

Code of Conduct

• [x] 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.

• [x] 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.

  • [x] 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.

[ghost]

Send me the SMS

On Tue, 6 May 2025 at 18.42 Josh Soref @.***> wrote:

jsoref left a comment (github/docs#38087) https://github.com/github/docs/issues/38087#issuecomment-2855404448

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.

— Reply to this email directly, view it on GitHub https://github.com/github/docs/issues/38087#issuecomment-2855404448, or unsubscribe https://github.com/notifications/unsubscribe-auth/BKS3BTDI2DZPRBKIGVTBPXT25DYBJAVCNFSM6AAAAAB4RYXKBKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQNJVGQYDINBUHA . You are receiving this because you are subscribed to this thread.Message ID: @.***>

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

[github-actions[bot]]

A stale label has been added to this issue and it has been closed, because it has been open for 30 days with no activity. If you think this issue should remain open, please add a new comment.

[jsoref]

@Sharra-writes

[Sharra-writes]

@jsoref Ugh, we're trying to track down what's going on with the stale action/workflow, but it's probably a problem with the action, and that's harder to work out.

[jsoref]

The action here and a similar one in community are really annoying.

I understand the goal, but as a heavy user of these repositories, I suffer more than the average person.

I'd really rather they be taken out of service until someone can prove they behave. Humans really can understand things that haven't been touched are probably not under active consideration. And for the ones where there is just a stream of people complaining, the bot doesn't help anyway.

[Sharra-writes]

@jsoref Sorry, missed the comment. The bot is helpful for us, because a lot of the time we do want to do everything, and there's this pervasive sense of "if I can just get a couple of hours free to pursue it..." that's exacerbated by the fact that the whole company is async and you never know if that one person you really need to see a thing is in a totally different time zone and offline or on vacation or whatever, because you don't know who that person is. The bot is kind of a reminder for us that there are only so many hours in a day, and we can't pursue everything. When it closes something, it makes us stop and think, "Oh, did I really have time to pursue that?" The answer is usually no. But when it's yes, it's also a reminder to check for things that got lost.

I do get a notification for state changes like added labels or closed issues, and now that I'm more comfortable in the role and know what I'm doing, I definitely check to see what's going on. It's possible something could escape my attention, but I'm aware you make a lot of good contributions here, I know the bot is flailing, and I'm going to be keeping a eye out for things from regular contributors that get mistakenly closed.

I've proposed adding a delay between the stale label getting added and the issue getting closed so I have more time to react, but basically everyone is on vacation this week, so we'll see if anyone has objections when they get back.

[jsoref]

I understand. Certainly for this repository I occasionally take stabs at the tickets I've filed.

I have a couple of PRs elsewhere that I owe rebases for...

Enjoy your vacation.

I appreciate the recognition.

[jsoref]

@Sharra-writes, we're back from Greece and this bug is still a problem.

Re @Habbie https://github.com/github/docs/issues/38087#issuecomment-2855380916

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.

Technically, that is mentioned here:

https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/preparing-to-require-two-factor-authentication-in-your-organization

https://github.com/github/docs/blob/7a90f722ac1f73b5e71c1043ea58e85565f13c84/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/preparing-to-require-two-factor-authentication-in-your-organization.md?plain=1#L23

When you require use of 2FA for your organization, {% ifversion ghes < 3.17 %}members and {% endif %}outside collaborators (including bot accounts) who do not use 2FA will be removed from the organization and lose access to its repositories.{% ifversion fpt or ghec %} If you require secure methods of 2FA, outside collaborators who have SMS 2FA configured will be removed. {% endif %} They will also lose access to their forks of the organization's private repositories.

Note that the text is wrong in that it says will be removed, what it means is will be put in purgatory. They're still members, they just can no longer see the repositories (including public repositories!). It's actually worse than being removed. If they were removed, they'd at least be able to see public repositories owned by the org.

Could someone please change: https://github.com/organizations/:organization/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.

-Users can only use secure two-factor methods: authenticator apps, passkeys, security keys, and the GitHub mobile app. [Learn more about two-factor authentication](https://docs.github.com/authentication/securing-your-account-with-two-factor-authentication-2fa/about-two-factor-authentication).
+Users can only use secure two-factor methods: authenticator apps, passkeys, security keys, and the GitHub mobile app. [Learn more about two-factor authentication](https://docs.github.com/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/preparing-to-require-two-factor-authentication-in-your-organization).

As that's the only page that at least explains that having SMS enabled is why a user will be locked out, as opposed to the current page which doesn't explain that the presence of SMS will lock a user out.

[jsoref]

For people wondering what the admin side looks like,

https://github.com/organizations/:organization/settings/security

Two-factor authentication

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

• [x] Require two-factor authentication for everyone in the :organization_pretty_name organization. Organization members who do not have two-factor authentication enabled will be unable to access resources owned by the Check Spelling sandbox organization, but will remain a member of :organization_pretty_name 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.

  • [x] 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 View organization membership link leads to a page with:

There's no explanation of how and differ or what they mean.

[Sharra-writes]

Hi, @jsoref! Hope you had a good time in Greece!

To update my side of this, it admittedly keeps getting lost in my pile of things because I've had a very hard time figuring out who to talk to. It's been made clear that it's not a big priority for the docs team, because the wording was negotiated with other teams some time ago, and it was complicated. I don't see why open source changes couldn't be made, but I have had trouble pinpointing which security team or teams I would need to talk to in order to get approval for changes to the wording. I'm getting shuffled around a lot, though that may be in part because I don't have precise wording for anyone to review yet.

I think that link could probably be updated without a whole involved approval process, at least. Hopefully.

I agree that the explanation doesn't match the reality, and I would very much like to see it improved, especially since the way the whole SMS thing works is admittedly unexpected.

On the admin side, I'm afraid that's probably going to be a support matter, since there's a lot of UI stuff there, but I know you're posting it here for reference.

[Sharra-writes]

@jsoref Okay, I'm finally caught up on all my other work. Do you want me to open a PR for changing (or adding?) the link, or do you want to do it? The disadvantage of me doing it is that I can't then approve it, and that's an extra step, but I don't mind doing it.

[jsoref]

Lemme make a PR. That will probably be all I'll manage today...

[jsoref]

Oh, the link I want is on the code side, it's for the actual system page. I can't make the PR I'm suggesting.

[jsoref]

I'll make a PR about purgatory since that's something I can touch.

[Sharra-writes]

@jsoref Ah, sorry, I thought the link was in an article. If it's in an actual UI thing, that's a support issue.