Using YubiKey with GitHub

How to set up a YubiKey with GitHub?

With hardware security keys you can get the additional protection of two-factor authentication to make your login procedure secure. Follow these step-by-step instructions to easily set up a YubiKey with GitHub accounts.

Requirements

  • A computer with a USB port and the latest version of Google Chrome, Mozilla Firefox, Opera, or Microsoft Edge. *
  • A FIDO U2F-enabled Security KeyYubiKey 5 NFC, YubiKey 5C, YubiKey 5/5C Nano.
  • A mobile phone to receive SMS with one-time passwords (or with Google Authenticator installed, to receive passwords by the app). Needed for the initial setup and backup.
  • A GitHub account.

If two-factor authentication is not enabled in your GitHub account yet, follow the procedure in Step 1 to enable it. If two-factor authentication is enabled already, skip to 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. Choose the method of how you want to receive one-time passwords, Set up by using an app or Set up using SMS.

Set up by using an app

First, you will need a time-based one-time password application installed on your mobile phone. We recommend using TOTP apps such as:

 

  1. Click Set up using an app.
  2. Save your recovery codes.
    1. To save the recovery codes on your computer, click Download.
    2. To print the recovery codes on paper, click Print.
    3. 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 2FA page, type the code and click Enable.
  6. After you’ve saved your recovery codes and enabled 2FA, we recommend you sign out and back in to your account. 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.

 

Set up by using SMS

If you’re unable to authenticate using a TOTP mobile app, you can authenticate using SMS messages. You can also provide a second number for a fallback device. If you lose access to both your primary device and your recovery codes, a backup SMS number can get you back in to your account.

Before using this method, be sure that you can receive text messages. Carrier rates may apply.

  1. Click Set up using SMS.
  2. Save your recovery codes
    1. To save the recovery codes on your computer, click Download.
    2. To print the recovery codes on paper, click Print.
    3. To copy the recovery codes to the clipboard, click Copy.
  3. After saving your recovery codes, click Next
  4. Select your country code and type your mobile phone number, including the area code. When your information is correct, click Send authentication code.
  5. You’ll receive a text message with a security code. Type the code on the Two-factor authentication page, and click Enable.
  6. After you’ve saved your recovery codes and enabled 2FA, we recommend you sign out and back in to your account. 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

When two-factor authentication is configured via a mobile app or via SMS, you can add your YubiKey to use for 2FA 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 the Security tab.
  5. To the right of “Security keys”, click Add.
  6. Insert your YubiKey into a USB port.
  7. In the Security keys section, 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.

Congratulations! You have now added a Security Key by Yubico to your GitHub account. Now it will be easy for you to log in to GitHub with strong second factor authentication. All you need to do is enter your username and password, touch the gold button or edge on your YubiKey, and you’re in.

What browsers versions support using YubiKey?

  • Google Chrome: starting from version 38
  • Mozilla Firefox: starting from version 60
  • Microsoft Edge: starting from build 17723
  • Opera: starting from version 40

*It is recommended to use the latest version of your browser.

We're happy to hear from you

1 + 3 =