Two Factor Authentication Frequently Asked Questions 🔑 🗝️

[github-staff]

At the end of 2022, we announced on our blog that GitHub will require all users who contribute code on GitHub.com to enable one or more forms of two-factor authentication (2FA) by the end of 2023. We started the phased roll-out in March 2023 so that we could learn about the efficacy of the program and adjust as we scaled to larger groups.

As more users are required to enroll, we’ve noticed questions, comments, and feedback in the community. We’re here to help make adopting 2FA on your GitHub account as straightforward as possible. For these and additional information, see the FAQ in our docs.

Why did GitHub make this change? #

Most security breaches are not the product of exotic zero-day attacks but rather involve lower-cost attacks like social engineering, credential theft or leakage, and other avenues that provide attackers with a broad range of access to victim accounts and the resources they have access to. In fact, passwords, which we all rely on, are the root cause of more than 80% of data breaches.

That’s why GitHub is committed to helping all developers employ strong account security while staying true to our promise of an excellent user experience.

What should I expect when I’m required to enable 2FA? #

GitHub has designed a rollout process intended to both minimize unexpected interruptions and productivity loss for users and prevent account lockouts. Groups of users will be asked to enable 2FA over time, each group selected based on the actions they’ve taken or the code they’ve contributed to.

1. If you are part of a pending 2FA enablement group, you will receive an email notification informing you of your deadline to enable 2FA, as well as steps on how to set up 2FA and our recommended best practices. You’ll get this email approximately 45 days before the deadline.
   • When your group’s timeline begins, you’ll start seeing weekly reminder banners on GitHub.com, which will guide you to the 2FA onboarding process.
   • You’ll also receive occasional emails notifying you of your coming 2FA enablement deadline.
2. Once the enablement deadline passes, you’ll be asked to enable 2FA every time you access GitHub.com. You can snooze this prompt once a day for up to one week to provide you with flexibility, but after that week you won’t be able to access GitHub.com until you’ve enabled 2FA.
   • This one-week snooze period only starts when you access GitHub after the deadline, so if you’re on vacation, don’t worry–you won’t be locked out of GitHub.com.
3. Twenty-eight (28) days after you enable 2FA, you’ll be asked to perform a 2FA check-up while using GitHub.com, which validates that your 2FA setup is working correctly. Previously signed-in users will be able to reconfigure 2FA if they have misconfigured or misplaced second factors during onboarding.

If your project takes off or you become the maintainer of a critical repository, you might suddenly qualify for a group that’s already begun their enrollment timeline. If that happens, you’ll start your 45-day period the next day, following the same timeline described above.

Why was my account selected for mandatory 2FA? #

You have taken some action on GitHub that showed you were a contributor. This includes publishing an App or Action for others, creating a release for your repository, or being a contributor to specific high-importance repositories, such as the projects that the Open Source Security Foundation tracks.
Being an administrator of one of those repositories, as well as an organization or enterprise administrator, also makes you eligible to be enrolled.

How much does this cost? #

2FA and any corresponding security measures have plenty of options that are at no cost to you. TOTP apps, device-embedded security keys (like your computer’s fingerprint reader), and the GitHub Mobile app (if TOTP or SMS have been enabled) are some free options available to you.

Why isn’t email-based authentication an option? #

The account's email address is already used for password reset, which is a form of account recovery. If an attacker has access to an email inbox, they can reset the password for an account and pass the email device verification check, reducing the account's protection to a single factor (email inbox access). We require a second factor to prevent this scenario, meaning that second factor must be distinct from your email inbox. When you enable 2FA, we will no longer perform email verification on login.

Options using your phone include: TOTP apps, SMS (if supported in your country), and the GitHub mobile app.

See the next question for options if you don’t have a mobile device.

How can I authenticate if I don’t want to use a mobile device? #

If you can’t or won’t use a mobile device for 2FA, there are multiple options for standalone TOTP applications that run across platforms. https://keepassxc.org/ was recommended by community member @ldez, which is an open, free desktop application, and for browser-based plugins there's 1Password. Any code that is compatible with RFC 6238 will work, using the manual setup options documented in "Configuring two-factor authentication".

What should I do if my country isn’t supported by SMS at this time? #

If your country is not on the list, then we aren't currently able to reliably deliver text messages to your country. We track delivery rates across all countries, including ones not in the list, and review it to understand when we have to remove countries or can add them back. We do not add countries with low deliverability rates, because it leads to users being locked out of their accounts when they can’t receive the SMS for 2FA.

If GitHub doesn’t support two-factor authentication via text message for your country of residence, you must set up authentication via a TOTP application. For more information on how to configure 2FA, please review our documentation.

Do I have to give GitHub my phone number?? #

No. Privacy is important to us. We’re not trying to collect your phone number, which is one reason we don’t default to suggesting SMS! Every other option, from TOTP apps and security keys to the GitHub Mobile app (if TOTP has been enabled) doesn’t require you giving your phone number to GitHub, and we strongly prefer you use those instead of SMS.

I don’t want to install a proprietary app to use TOTP! #

The good news is TOTP is an open standard so there are free, nonproprietary apps for you to use. Community member @ldez has recommended KeePassXC. For more options, we recommend doing a quick search in your browser for open source TOTP apps.

What options do you have for users who rely on assistive technology and users with accessibility requirements? #

GitHub provides numerous options for two-factor authentication (2FA), and these provide a wide range of flexibility for users with disabilities.

GitHub strongly recommends the use of time-based one-time password (TOTP) applications. There are a variety of TOTP applications for desktop and mobile devices. Users can do their own research to find a TOTP application that best meets their accessibility needs. To get started, search for “TOTP app” in your browser. You can also refine your search by adding keywords like “free” or “open source” to match your preferences.

If you have a mobile phone and live in a region where we support SMS messages, getting set up with SMS does not require any additional apps, and you can rely on the assistive technology you already have on your mobile device.

If efficiency is important to you, consider using passkeys to sign in after you’ve configured 2FA. Passkeys allow you to sign-in with very few steps as they meet both password and 2FA requirements. Using passkeys in conjunction with your preferred password manager enables a fast and efficient experience across all your devices.

Questions and feedback about the accessibility of a third-party application should be directed to the application provider. If you have feedback about the accessibility of GitHub products, please connect with our community using the accessibility community discussions page.

I don’t have the time to do all these steps - do you have a shortcut? What options do you have for users who rely on assistive technology and users with accessibility requirements? #

There’s no shortcut to make setting up 2FA faster, but adding a passkey once 2FA is set up is really quick, and makes signing in faster than using a password. Passkeys satisfy both password and 2FA requirements, so you can complete your sign in with a single step. You can also use passkeys for sudo mode and resetting your password.

Unlike security keys, passkeys have the security benefit of being user-verifying. This means passkeys verify your identity using "something you know" or "something you are", such as a PIN or biometric check of your fingerprint or face. When you sign in to GitHub.com using a passkey, you are using your device's authentication system (such as Mac TouchID, or Windows Hello) to prove your identity, which then unlocks a private key that GitHub can validate. Learn more about passkeys.

Passkeys are now generally available. For more information, see Enabling and disabling the feature preview for passkeys..

Can I leave feedback on the 2FA and this process? #

Absolutely, we’re all ears. 2FA will be required for many users, but that doesn’t mean we don’t welcome your thoughts on how we can make it better. Feel free to start a post here and choose the Security and Privacy label for your post.

To leave feedback on passkeys (public beta) specifically, please share in this discussion.

Where can I learn more about 2FA? #

Check out our docs:

• About 2FA
• Configure 2FA