1. Yubico
  2. Business
  3. Guides

Using Your YubiKey with Authenticator Codes

Avatar
Michael
Created - Updated

These instructions show you how to set up your YubiKey so that you can use two-factor authentication to sign in to any account that requires authenticator codes. Example sites where you can use codes to authenticate include Amazon, Dropbox (if you aren't using U2F), Evernote, Facebook, and many others. To use a code at one of these sites, you use an application, such as Google Authenticator, to generate the codes. The codes generated are OATH-TOTP codes, a type of one-time password, that are usually six-digits. You can use Yubico Authenticator, which is similar to Google Authenticator. We have created both a desktop and mobile version of this app for you to use so you can use it on a Windows, Mac, Linux, or Android.

 

Setting Up Your YubiKey in Yubico Authenticator 6.0+ for Desktop

Requirements

Instructions

  1. Enable two-factor authentication for your service. Usually, you will do this by selecting Settings or Security, and then selecting the option to Enable two-factor authentication. Tip: Some services call this "two-step verification."
  2. Select the option to use a mobile app, or Google Authenticator. A QR code should appear.
    • If you are planning to register more than one YubiKey with this service, please save a copy of the QR code, or secret key as you will need it when registering more keys.
  3. Open Yubico Authenticator for Desktop and plug in your YubiKey.
  4. Select the Yubikey picture on the top right
  5. Select Add Account
  6. You will be presented with a form to fill in the information into the application. If you have a QR code, make sure the QR code is visible on the screen and select the Scan QR Code  button. A successful QR Code scan will auto-fill Issuer, Account name, and Secret key.
    mceclip4.png
  7. Before adding the credential, you have the option to adjust the following settings.
    mceclip5.png
    Note:     these cannot be adjusted after saving the credential.
    • Issuer - Defines the service name
    • Account name - Defines the account holder name
    • Require touch - Toggles the requirement to touch the YubiKey in order to display the OATH code on (checked) or off (unchecked). Note that this is set on a per-credential basis; in other words, each credential can have this set differently.
  8. Once you have all the options as you desire, select Save on the upper right
  9. It should now go back to the main screen and you should see the entry.
    • Note: to copy the code, hold click on the code, until you see it say you have copied the code at the bottom
      mceclip6.png
  10. Complete the setup process on the website. This typically involves entering a one-time password from Yubico Authenticator, and potentially re-entering your login password.

You can repeat the process for other YubiKeys for backup using the same account.

You have successfully configured your YubiKey for authenticator codes!

Setting Up Your YubiKey in Legacy Yubico Authenticator for Desktop

Requirements

Instructions

  1. Enable two-factor authentication for your service. Usually, you will do this by selecting Settings or Security, and then selecting the option to Enable two-factor authentication. Tip: Some services call this "two-step verification."
  2. Select the option to use a mobile app, or Google Authenticator. A QR code should appear.
    • If you are planning to register more than one YubiKey with this service, please save a copy of the QR code, or secret key as you will need it when registering more keys.
  3. Open Yubico Authenticator for Desktop and plug in your YubiKey.
  4. Click the YubiKey icon at the top right and select Add account.
  5. Click Scan QR code. If the scan attempt fails, ensure the QR code is visible on the same screen as Yubico Authenticator. A successful QR Code scan will auto-fill Issuer, Account name, and Secret key.
  6. Before adding the credential, you have the option to adjust the following settings. Note: these cannot be adjusted after saving the credential.
    • Issuer - Defines the service name
    • Account name - Defines the account holder name
    • Require touch - Toggles the requirement to touch the YubiKey in order to display the OATH code on (checked) or off (unchecked). Note that this is set on a per-credential basis; in other words, each credential can have this set differently.
  7. Once you are satisfied with the configuration, click Save.
  8. If you have one or more backup YubiKeys, unplug the YubiKey that is currently plugged in, insert one of your backup keys, and follow through steps 4-7 again. Consider saving a copy of the QR code (or secret key) somewhere safe so you have the ability to program the credential into future backup YubiKeys, etc.
  9. Complete the setup process on the website. This typically involves entering a one-time password from Yubico Authenticator, and potentially re-entering your login password.

You have successfully configured your YubiKey for authenticator codes!

Setting Up Your NFC-enabled YubiKey with the Yubico Authenticator 6.0+ for Android App

Requirements

Instructions

  1. Enable two-factor authentication for your service. Usually, you will do this by selecting Settings or Security, and then selecting the option to Enable two-factor authentication. Tip: Some services call this "two-step verification."
  2. Select the option to use a mobile app, or Google Authenticator.
  3. You will need to copy the text string as well as scan the QR code. Click enter your secret key manually and copy the text of the code and paste it into a text file now.
    • Be sure to save a copy of the secret key. You can use this to create a backup copy of your YubiKey configured to use authenticator codes. It is always best security practices to ensure you have a backup YubiKey.
  4. Open the Yubico Authenticator app.
  5. Tap the control icon to open the menu.
  6. Select Scan account QR-code, and then scan the QR code from the web page.
    • Be sure to save a copy of the QR code in a safe place. You can use this to create a backup YubiKey configured to use authenticator codes. It is always best security practices to ensure you have a backup YubiKey.
    • Note: To manually add the secret key, select Add account manually, then enter the credential name, and type the secret key that you previously saved as a backup.
  7. On the web page, click Next. You have successfully configured your YubiKey for authenticator codes!
  8. To view the credential, tap and hold your YubiKey on the back of your phone where the NFC antenna is located. Yubico Authenticator displays the six digit code associated with this credential. This is the code you need to enter to authenticate when using two-factor authentication.

Setting Up Your NFC-enabled YubiKey or YubiKey 5Ci with the Yubico Authenticator for iOS App

Requirements

  • YubiKey 5 NFC, YubiKey 5C NFC, YubiKey NEO or YubiKey 5Ci
  • Yubico Authenticator for iOS app from the App Store
  • (For NFC) an iPhone 7 or newer, running iOS 13 or newer
  • (For Lightning connectivity) an iPhone, iPod Touch, or iPad with a Lightning connector, running iOS/iPadOS 11.2 or newer. Note: Yubico Authenticator is not supported on iPads with USB-C ports due to limitations in the Apple ecosystem. However in version 1.7.0 of the Yubico Authenticator USB-C support was added to iPads running iPadOS 16.1

Instructions

  1. Download and install Yubico Authenticator for iOS, available in the App Store for any iPhone/iPad with a Lightning port.
  2. Open Yubico Authenticator for iOS.

  3. If you are using a YubiKey 5Ci over Lightning, plug it in.

  4. On another device (such as a laptop), launch the service you want to use with an authenticator app. Follow the on-screen prompts for securing the service with an authenticator app until the point when a QR code is displayed. (If you need assistance with the authenticator app setup process for a service, please refer to the service's setup instructions or contact their support team).

  5. In Yubico Authenticator for iOS on your iPhone/iPad, tap on the circle in the top right corner.

  6. Select the Add Account option. If a pop-up appears requesting permission to access the camera, tap Allow.

  7. Point the iPhone/iPad's camera at the QR code on the other device until the QR code is read. This is signaled by a "New Account" screen appearing in Yubico Authenticator for iOS.

  8. Before saving the credential, you have the option to adjust the following settings. Note that the require touch option cannot be changed after saving the credential..

    • Issuer - defines the service name

    • Account name - Defines the account holder name

    • Require touch - Toggles on or off the requirement to touch the YubiKey (or scan again in the case of NFC) in order to display the OATH code. Note that this is set on a per-credential basis. In other words, each credential can have this set differently.

  9. Tap Save. If you are using a YubiKey over NFC, when the Ready to Scan pop-up appears, bring your key next to your phone's NFC reader (typically located on the rear of the phone near the top) and hold it there until a checkmark appears on-screen, indicating the credential has been securely added to the YubiKey.

    • At this point, if you wish to store the same account on a second YubiKey, simply repeat steps 3 and 5-9 for each additional YubiKey. Alternatively, if you wish to add this account to another YubiKey but don't have one currently, you can save a copy of the QR code (or secret key) in a safe place to scan and add later.

  10. Use the current code displayed in Yubico Authenticator for iOS for this account to complete setup of the account on the other device.

Logging on to Your Account

Once you have configured your account with a service for authenticator app two-factor authentication, you must use a code generated by Yubico Authenticator when logging in to that service.

  1. Launch Yubico Authenticator.
  2. On the device you want to sign in to your account with, begin logging in by entering your user name and password as normal.
  3. Find the authenticator code you need in Yubico Authenticator:
    • Desktop: Insert your YubiKey. The code is shown next to the service's credential.
    • Mobile:
      • iOS: Insert your YubiKey 5Ci into your device's Lightning port, or "pull down" to activate NFC, if connecting your YubiKey over NFC. When prompted, scan your key if you are using NFC. The code should be displayed in the app. If the credential in question is set to require touch, you will need to touch your YubiKey's sensor (in the case of a YubiKey 5Ci), or scan your key again (if using NFC).
      • Android: Launch Yubico Authenticator for Android, and tap and hold your NFC-enabled YubiKey against the NFC antenna on the back of your phone. The code is shown next to the service's credential. Note: For generating codes set to require touch, you will need to tap the "refresh" icon next to the credential, and then scan the YubiKey a second time when prompted. Touch credentials work this way over NFC because NFC does not provide enough power for the capacitive touch sensor on the YubiKey to function.
  4. Enter the code on the website and click Sign In (or similar). Tip: In Yubico Authenticator for Desktop, you can double-click the code, and then paste it into the field for the authenticator code.

Troubleshooting and Additional Topics

Codes generated by Yubico Authenticator are wrong

Yubico Authenticator implements the OATH-TOTP standard, which specifies a standard for one-time passwords that are based on time. If Yubico Authenticator is generating codes that are being rejected as incorrect, the most likely cause is an incorrectly-set clock on whichever device is running Yubico Authenticator.

 

Password-protecting the YubiKey's OATH application

To further enhance the security of your YubiKey, consider adding a password to its OATH application. This will result in the password being required before codes can be generated with Yubico Authenticator. To add a password to the OATH application:

 

  • In Yubico Authenticator for desktop:
    • Click the triple-dot button to open the menu and expand the section Set password.
  • In Yubico Authenticator for iOS:
    • Tap the gear button to open the menu, and tap Set password.
  • In Yubico Authenticator for Android:
    • Scan or insert your YubiKey, tap the triple-dot button, then tap Change password.

Backing up accounts

While it isn't possible to back up accounts from the YubiKey itself, it is possible to back up the piece of information provided by each service provider, and then use that to program the same account (or credential) onto multiple YubiKeys.

In order to do this, when first setting up a service with Yubico Authenticator, take a screenshot of the QR code (or make a copy of the secret key) provided by the service. After setting up your primary YubiKey using this QR code or secret key, re-use it to program the same credential into each spare YubiKey.

 

Debug

The log levels are ERROR, WARNING, INFO, DEBUG, and TRAFFIC, in order of increasing verbosity. The default level is INFO, which is what the app is started with (you can however start with a different level by using--log-level LEVEL). In general what gets logged is:

 

ERROR - Any error that occurs. Usually when an action cannot be performed.
WARNING - Something failed, but the app is able to recover and complete the action, or the failure doesn't impact the action.


INFO - Usually what the app is doing without specific details. Like a credential was added/removed/renamed, etc.


DEBUG - More detailed information than INFO, also containing specifics about the action performed. This can include things like the name of the added account, along with more information on how something was done instead of just what. This information should be useful for figuring out more specifically what happened in case of a failure. While some info at this level might be considered sensitive, it won't have actual secret keys.


TRAFFIC - Even more detailed info, including ALL raw traffic to/from the YubiKey. This includes the actual SECRETS when adding a credential, PIN codes that are being set, etc.

Note that the DEBUG and TRAFFIC levels will show a red warning in the app when active.