Using YubiKey with GitHub

Requirements

• A computer with a USB port and the latest version of Google Chrome, Mozilla Firefox, Opera, or Microsoft Edge.*
• U2F-enabled security key: Security Key, Security Key NFC, YubiKey 5 NFC, YubiKey 5C, YubiKey 5/5C Nano, YubiKey FIPS,
  YubiKey Nano FIPS, YubiKey C FIPS, YubiKey C Nano FIPS.
• Mobile phone to receive SMS with one-time passwords (or with Google Authenticator installed to receive one-time passwords through the application). Needed for the initial setup and backup.
• A GitHub account.

If your GitHub account doesn’t already have two-factor authentication enabled, follow the steps in Step 1 to enable this option. If two-step verification is already enabled, continue with Step 2.

Step 1: Enabling two-factor authentication

1. Sign in to your GitHub account.
2. Click your profile picture in the top right of the screen.
3. Select Settings
4. In the left pane select Security.
5. Click Enable two-factor authentication.
6. Select a method for obtaining one-time passwords: Set up by using an app (Setting up sign-in using the app) or Set up using SMS (SMS login setup).

Set up by using an app

To get started, you should install the application for receiving one-time passwords. We recommend using TOTP apps such as:

• Google Authenticator
• 1Password
• Authy
• LastPass Authenticator

When the mobile app is already installed:

1. Click Set up using an app
2. Save your recovery codes.
   • To save the recovery codes on your computer, click Download
   • To print the recovery codes on paper, click Print.
   • To copy the recovery codes to the clipboard, click Copy.
3. After saving your recovery codes, click Next
4. On the Two-factor authentication page, do one of the following:
   1. Scan the QR code with your mobile device’s app. After scanning, the app displays a six-digit code that you can enter on GitHub.
   2. If you can’t scan the QR code, click enter this text code,to see a code you can copy and manually enter on GitHub instead. If you’re using Microsoft Authenticator, you’ll need to use this method.
5. The TOTP mobile application saves your GitHub account and generates a new authentication code every few seconds. On GitHub — on the two-factor authentication page — enter the code from the application and click Enable.
6. After you’ve saved your backup codes and enabled two-factor authentication, it’s a good idea to sign out and sign in again. In case of problems, such as a forgotten password or a typo in the specified email address, you can use the backup codes to access your account and troubleshoot.

SMS login setup

If you are unable to use the mobile TOTP app, you can receive one-time passwords via SMS. You can also provide a second phone number for a fallback login method.

Before using this method, make sure that you have the ability to receive SMS messages. You may also be charged for incoming messages.

1. Click Set up using SMS.
2. Save your recovery codes
   • To save the recovery codes on your computer, click Download.
   • To print the recovery codes on paper, click Print.
   • To copy the recovery codes to the clipboard, click Copy.
3. After you have saved your spare codes, click Next.
4. Select a country code and enter your phone number. When your information is correct, click Send authentication code.
5. You should receive an SMS with a code. Type the code on the Two-factor authentication page, and click Enable.
6. After you’ve saved your backup codes and enabled two-factor authentication, it’s a good idea to sign out and sign in again. In case of problems, such as a forgotten password or typo in your email address, you can use recovery codes to access your account and correct the problem.

Step 2: Adding a YubiKey for two-factor authentication

Once two-factor authentication is set up via mobile app or SMS, you can add the YubiKey hardware security key as a second factor of authentication on GitHub.

1. Sign in to your GitHub account.
2. Click your profile picture in the top right of the screen.
3. Select Settings.
4. In the left pane select Security.
5. To the right of Security keys click Add.
6. Insert your YubiKey into a USB port.
7. In chapter Security keys click Register new device.
8. Type a nickname for your YubiKey, then click Add.
9. Wait your YubiKey to begin flashing, then tap the gold button or edge.

That’s all! You have now added a Security Key by Yubico to your GitHub account. Now you can easily log into your GitHub account, securely protected by two-factor authentication. All that is required to login is to enter your username and password, then touch the button or the gold-colored edge on your YubiKey.

What browsers versions support using YubiKey?

• Google Chrome: since version 38.
• Mozilla Firefox: since version 60.
• Opera: since version 40.
• Microsoft Edge: since build 17723.

* It is recommended to use the latest browser version.