What you need to know about 2FA before switching phones

What you need to know about 2FA before switching phones

Sometimes life forces you to change devices unexpectedly and that can cause issues if you use 2FA and haven’t planned for what happens when you need to switch your 2FA device. For instance, I recently went paddleboarding. :surfing_woman: Against conventional wisdom, I left my phone in my pocket and forgot about it. Later, I jumped in the water to cool off. I thought to myself: “it’s fine, I think it’s waterproof!”

One of my loved ones explained that my phone was actually water resistant, and that’s… completely different from being waterproof. Now I’m in the market for a new phone and I know I’ll need to migrate my 2FA configurations, including one for GitHub.

As a part of this process, I worked with my colleagues on this mini-guide that goes over what you need to know about 2FA on GitHub.com before switching over to another phone - whether you plan to or not.

Getting started with 2FA

First things first: what is 2FA, and why is it important?

Two-factor authentication (2FA) is an extra layer of security used when logging into websites or apps. With 2FA, you have to log in with your username and password and provide another form of authentication that only you have access to.

On GitHub.com, you can set up your GitHub account to require an authentication code in addition to your password when you sign in. Our team wrote an entire collection of guides for securing your account with two-factor authentication (2FA).

We suggest following this step-by-step guide for configuring two-factor authentication for your account.

What to do if you’ve already configured 2FA with an Authenticator App

Already configured 2FA and using an Authenticator App? Here are some tips to make the most of your migration.

Before changing phones, be sure you have some backup recovery methods. These can be:

If you use an authenticator app on your phone as your primary two-factor authentication method, 2FA must be reconfigured on the new device when switching to a new phone or wiping your existing phone’s data. These backup recovery methods can only be set up while logged in to the account.

When you get your new phone, if you’re still logged in to your account, go to your account’s security settings to reconfigure 2FA for the new device. Then, click Set up using an app, and follow the steps using your new device.

  1. Download (or print) a copy of the recovery codes
  2. Scan the QR code from the new TOTP application
  3. Enter the code generated by the TOTP application to confirm the new settings
  4. If successful, you’ll be redirected back to your two-factor authentication settings with a “Two-factor authentication successfully enabled!” banner

If you’re not logged in, you will need to use a recovery code, an authentication code sent to your backup phone number, or your security key to log in then reconfigure 2FA for the new device using the steps above.

Frequently Asked Questions (FAQs)

What if I no longer have the original authenticator app?

Be sure to check for your recovery codes, since that is a necessary step when configuring 2FA. You might have them saved somewhere! The default filename is github-recovery-codes.txt.

Other than that, you can send a code to your backup phone number or use a security key, if those were previously configured. This recovery process is also available to those who know their password and have previously set up the related recovery methods.

I forgot my password… how can I access the account?

You can reset your password (and other access credentials) yourself by following our guide on updating your GitHub access credentials.

When resetting the password, a valid second factor of authentication is still necessary to access an account protected by 2FA. We suggest looking for your recovery codes, send a code to your backup up phone number, or try a security key (if those methods were configured).

I don’t think I have any other methods set up. What do I do now?

We may not be able to recover the account without a valid second factor of authentication from the recovery methods. If this is the case, please contact us. We can check for any recovery methods that you might’ve missed or discuss the next steps in moving forward.

6 Likes

Very informative! Thank you @francisfuzz !

1 Like

I went through a nightmare when I switched laptops and although I had copied the recovery codes before formatting my old laptop they did not work. The Github support person told me there was no way out. I had to create a new account.

I’m so terrified of that happening. We can check if you’re using outdated recovery codes - ie, ones that had been generated and were valid but made invalid when you generated a new file, but other than that, it’s hard to trace why recovery codes aren’t working. Sometimes people have more than one account, for instance, and they get them mixed up, or overwrite the file for one with a file for the other.

A lot can happen!

I like having a U2F/WebAuthn security key myself. I don’t often lose my keys, so it’s a real, solid thing that I’m unlikely to misplace.

1 Like