Repository navigation
Article doesn't do a good job of explaining Only allow secure two-factor methods #38087
Description
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?
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)
Activity
Habbie commentedon May 6, 2025
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 commentedon May 6, 2025
For perspective, here's what that screen shows:
The link at the bottom of this text should have been to Requiring secure methods of two-factor authentication in your organization
[-]Article doesn't discuss `Only allow secure two-factor methods`[/-][+]Article doesn't do a good job of explaining `Only allow secure two-factor methods`[/+]jsoref commentedon May 6, 2025
A user in my org reported:
jsoref commentedon May 7, 2025
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 commentedon May 7, 2025
@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 commentedon May 13, 2025
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 commentedon May 13, 2025
@setharnold I'll add it to the list of things causing friction in this article. Thanks.
github-actions commentedon Jun 13, 2025
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.
8 remaining items
Sharra-writes commentedon Jun 19, 2025
@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 commentedon Jun 19, 2025
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 commentedon Sep 29, 2025
@Sharra-writes, we're back from Greece and this bug is still a problem.
Re @Habbie #38087 (comment)
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
docs/content/organizations/keeping-your-organization-secure/managing-two-factor-authentication-for-your-organization/preparing-to-require-two-factor-authentication-in-your-organization.md
Line 23 in 7a90f72
Note that the text is wrong in that it says
will be removed, what it means iswill 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
Users can only use secure two-factor methods: authenticator apps, passkeys, security keys, and the GitHub mobile app. Learn more about two-factor authentication.
As that's the only page that at least explains that having
SMSenabled 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 commentedon Sep 29, 2025
For people wondering what the admin side looks like,
https://github.com/organizations/:organization/settings/security
The
View organization membershiplink leads to a page with:There's no explanation of how
and 
differ or what they mean.
Sharra-writes commentedon Sep 30, 2025
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 commentedon Oct 2, 2025
@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 commentedon Oct 3, 2025
Lemme make a PR. That will probably be all I'll manage today...
jsoref commentedon Oct 3, 2025
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 commentedon Oct 3, 2025
I'll make a PR about purgatory since that's something I can touch.
Sharra-writes commentedon Oct 3, 2025
@jsoref Ah, sorry, I thought the link was in an article. If it's in an actual UI thing, that's a support issue.
subatoi commentedon Sep 3, 2026
@jsoref Hello—as you'll know, we recently merged the docs PR you raised to clarify this as best as possible #40665
As far as the docs are concerned, there's not much more I can do at this time. Is there a community discussion for this to report the confusing UI aspects?
subatoi commentedon Sep 4, 2026
I'm going to go ahead and close this out, as I don't think there's realistically much more we can do to improve clarity on the subject on the docs specifically. As mentioned above, please go ahead and raise a community discussion in relation to the UI issues you've highlighted. Thank you very much
jsoref commentedon Sep 4, 2026