Using your YubiKey with authenticator codes

This article covers how to set up your YubiKey so that you can use two-factor authentication to sign in to any account supports authenticator codes. For a comprehensive list of sites known to support authenticator codes for two-factor authentication, refer to the Works with YubiKey catalog (link filtered for one-time password - TOTP).

 Tip: For enhanced security, consider confirming if the service also supports FIDO2 or FIDO U2F, which adds additional protection against phishing. Many services that support one also support the other, so you can potentially register your YubiKey using both methods.

To use a code at one of these sites, you would typically 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, and generated based on the current time. You can use Yubico Authenticator, which is similar to Google Authenticator, in conjunction with your YubiKey. Yubico Authenticator is available for Desktop, iOS, and Android.

 Note: Once an account is added, codes can be generated for that account from any device running Yubico Authenticator, in conjunction with your YubiKey. For an additional layer of protection, you can set a password to protect access to these stored credentials.

To see a comprehensive guide for the Yubico Authenticator application, which also covers managing other YubiKey applications such as FIDO and PIV, refer to the Yubico Authenticator user guide.

Setting up your YubiKey in Yubico Authenticator for Desktop

Requirements

• Yubico Authenticator

Instructions

1. 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 an authenticator app (authentication app), or Google Authenticator. A QR code should appear.
      

       Tip: If you are planning to register more than one YubiKey with this service, best practice is either to have all YubiKeys immediate available to register all at the same time, or securely save a copy of the QR account, allowing you to add the account to additional YubiKeys in the future. Password managers, for example, typically offer an option to securely store QR codes.

   3. Open Yubico Authenticator for Desktop and plug in your YubiKey
   4. Tap the hamburger menu () at the top left and select Accounts () 
   5. Select Add account
      
   6. You are presented an option to either scan a QR code or add an account manually. If you have a QR code, make sure the QR code is visible on the screen, and then select the Scan QR Code button.
      
      
      
   7. A successful QR scan will automatically fill the Issuer, Account name, and Secret key
      
      
   8. Before adding the credential, you have the option to adjust the following settings:
      
      

       Note: These settings cannot be adjusted after saving the credential, so be sure to choose carefully:
      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). This is set on a per credential basis; in other words, each credential can have this set differently.

   9. Click Save
   10. In order to complete the setup for your service provider, click the code for the account to copy it, and then paste it into the service provider's setup page to confirm the new credential.
   11. 
       

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

You have successfully configured your YubiKey for authenticator codes!

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. 1. Open 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
   3. When prompted by the service, find the authenticator code you need in Yubico Authenticator:
      • • Desktop: Insert your YubiKey. The code is shown next to the service's credential. You can click on the code to copy it to the clipboard. It can then be pasted into any text field.
        • Mobile:
          • iOS: Insert your YubiKey, 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 plugged in YubiKey), 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 against the back of your phone.
            

             Tip: 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).
      
      

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 the current 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. Even a 1 minute different between the service's time server and the device time, depending on the service provider's settings, can result in rejected codes. Typical the concept of a lookahead count is adopted by the service provider to mitigate small differences in time, but this increase in usability also decreases security, so these windows are generally set very tightly.

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 follow these instructions.

Backing up accounts

Specific to this specific use case (authenticator apps / time-based one-time password), 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 onto each spare YubiKey.

Reviewing Yubico Authenticator logs in Desktop and Android (not supported in iOS)

For Flutter-based Yubico Authenticator (all versions except iOS), if the above guidance does not resolve your issue, you may find additional help by capturing a log.

1. Navigate to the home section of Yubico Authenticator
2. Open the kebab menu () at the top right
   
3. Select Help and about
   
4. Change the log level to DEBUG (you may need to scroll down to see these options, depending on your screen resolution and application settings) and reproduce your issue. Once the issue is reproduced, return to this menu and click Copy log. 
   
   

The log levels are ERROR, WARNING, INFO, DEBUG, and TRAFFIC, in order of increasing verbosity. The default level is INFO, which is the log level the app is started with. In general, the following are logged:

• 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. This information should be useful for figuring out specifically what happened in the 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. You should never set this option if you're planning to perform sensitive actions and sending the log to a third party (including Yubico). If you need access to a fake account to reproduce an issue with, you can create an account on the Yubico demo website (accounts are wiped every 24 hours), login, and then scroll down to and expand Authenticator application.

DEBUG and TRAFFIC levels will show a red warning in the app when active, and you should generally refrain from sharing logs of DEBUG and TRAFFIC levels with anyone, as they may contain sensitive information.

Once the log level has been set and the issue has been reproduced, you can copy the log to the clipboard via Help and about > Copy log, and then paste it into a text editor, etc. for review.