Accounts: OATH

Important

The Accounts feature is available for Yubico Authenticator for Desktop and Mobile (all platforms) and OATH-compatible YubiKeys. This includes the YubiKey 5 Series (standard, FIPS, and CSPN), YubiKey 4 Series, and YubiKey NEO. For a complete breakdown of Yubico Authenticator functionality by platform and connection type for each YubiKey model, see the Yubico Authenticator Functionality table.

The Accounts feature of Yubico Authenticator allows you to:

• Configure a YubiKey with OATH credentials linked to a specific account.
• Generate and display OTPs for two-factor authentication using those OATH credentials.
• Protect the OATH application of a YubiKey with a password.
• Pin OATH accounts to the top of the Accounts screen for easier access.
• Rename OATH accounts on a YubiKey.
• Delete OATH account credentials from a YubiKey.
• Configure the Yubico Authenticator application with custom OATH account icons.

What is OATH authentication?

OATH (Initiative for Open Authentication) is an organization that specifies two open authentication standards: time-based one-time passwords (TOTPs) and HMAC-based one-time passwords (HOTPs). The term “OTP” encompasses both TOTPs and HOTPs.

HOTPs are generated by hashing a secret key, counter, and length (6 or 8 digits) with a hashing algorithm (such as SHA-1). TOTPs are generated by hashing a secret key, current time, period, and length (6 or 8 digits) with a hashing algorithm. The resulting HOTPs and TOTPs are codes of 6 or 8 digits in length, such as 076 838.

Once generated, HOTPs are valid until an HOTP generated with a subsequent counter is used for authentication. TOTPs are only valid for the length of the period, which is often 30 seconds.

HOTPs and TOTPs cannot be decrypted. Therefore, OATH authentication works by comparing the OTP generated and submitted by a user with the OTP generated by the relying party (the site/service you are authenticating to) using the same credentials. If the OTPs match, the user is authenticated.

When using OATH for two-factor authentication with a YubiKey and Yubico Authenticator, the OATH credentials (including the secret key) are stored in the OATH application in the key’s secure element. During authentication, Yubico Authenticator is used to trigger OTP generation within the YubiKey and to display the OTP code. This OTP can then be copied and pasted onto a login screen. This has two major advantages over storing secrets on a phone:

• Security: The secrets always stay within the YubiKey. A phone can get stolen, sold, infected by malware, have its storage read by a connected computer, etc. Furthermore, the OATH application itself can be protected by a password.
• Accessibility: Once a YubiKey is configured with an OATH account, OTPs can be generated by Yubico Authenticator on any device. For example, if your phone dies, you could still generate OTPs via Yubico Authenticator on a friend’s phone.

Adding a new account

Adding a new account for OATH authentication requires a YubiKey, Yubico Authenticator, and the secret key information provided by the site/account/service you are registering the YubiKey with.

Note

Sites and services typically describe OATH authentication as “two-factor authentication using an authenticator app”.

During registration, the YubiKey stores the secret key and associated account information. For information on how to access the secret key credentials with a particular site/account/service, see the Works with YubiKey catalog.

Once an account is registered with a YubiKey, the OTPs for that account can be generated via Yubico Authenticator on ANY device. For example, suppose you have Yubico Authenticator on both your desktop and mobile devices. If you register an account with a YubiKey on your mobile device, you can still generate OTPs with that key on your desktop and vice versa.

With Yubico Authenticator, OATH accounts can be added via QR code or by entering the secret key (among other fields) manually. Both methods give you the option to “require touch” as a means of user verification. If you do not enable the touch requirement, the YubiKey will begin generating TOTPs once it is connected to your device, and these TOTPs will be visible next to the account name in Yubico Authenticator. Counter-based HOTPs must be generated manually regardless of the touch requirement.

If you require touch, you must manually initiate the OTP calculation in Yubico Authenticator for each OTP you wish to generate.

Note

HOTP generation must be initiated manually regardless of whether touch is required.

To add an account, do the following:

1. Plug your YubiKey into your device, click the menu icon in the upper left corner of the app (desktop and Android only), and select Accounts.

   To connect via NFC on desktop, click the NFC icon in Yubico Authenticator and place your YubiKey on top of a desktop NFC reader. The key must maintain constant contact with the reader throughout the operation.

   To connect via NFC on Android, tap your YubiKey on the back of your device to scan.

   To connect via NFC on iOS/iPadOS, swipe down on the screen and tap your YubiKey on the back of your device to scan.

2. Enter your OATH password if prompted and click Unlock (on desktop and Android) or Ok (on iOS/iPadOS). For NFC connections on Android or iOS/iPadOS, scan your YubiKey again when prompted.

3. Click Add account.

   On desktop and Android, this is located under Setup. To find the Setup menu in a narrow app window, click the three dots in the upper right corner of the app.

   

   On iOS/iPadOS, click the three dots in the upper right corner of the app to find Add account.

   

4. Locate the QR code or secret key information in the site/account/service you wish to register with.

   This typically requires logging into your account and going to “settings” or “security” > “two-factor authentication” or “two-step verification” > “register an authenticator application” (or similar). See the Works with YubiKey catalog for information on where to find these settings on a particular site you wish to register with.

   

   Important

   Yubico recommends registering at least one backup key for each account to preserve access in the event of a loss of your primary YubiKey. Make a copy of the QR code or secret key information; you will need it when registering a second YubiKey.

5. To add an account via QR code on desktop, ensure the QR code (provided by the site/account/service you are registering with) is completely visible on your screen (no obstructions) and click Scan QR code.

   For Android and iOS/iPadOS, point your camera at the QR code to scan (if the QR code is on a separate screen/device). Alternatively, on Android, take a screenshot of the QR code on your Android device, click Read from file, and select the screenshot.

   

   On the Add account screen, make edits to the Issuer (site/service) and/or Account name (your username) if needed, click Require touch (optional), and then click Save. For NFC connections on Android and iOS/iPadOS, tap your key to complete the operation.

   Note

   macOS requires permission to record your screen in order to scan the QR code. You will likely be prompted to set up these permissions the first time you attempt the QR scan, but you can also toggle them in System Settings at any time.

6. To add an account manually, click Add manually (desktop and Android) or Enter manually (iOS/iPadOS).

   On the Add account screen, enter an Issuer (the site/service), Account name (your username), and Secret key. Underneath these fields, select the appropriate OATH options for type of OTP, algorithm, period, and OTP length. These settings must match those specified by the site/account/service. If they do not, authentication will fail (because the OTPs generated by the YubiKey will not match those generated by the relying party).

   Click or toggle Require touch (optional) and then Save. For NFC connections on Android and iOS/iPadOS, tap your key to complete the operation.

   

7. The account or service you are registering the YubiKey with will likely ask for an OTP code to complete the registration. If you did not check “require touch” during setup and the OTP type was TOTP, enter the OTP listed next to the account in Yubico Authenticator. If you did require touch or the OTP type was HOTP, click on the account name (on desktop and Android, this opens the Actions section), select Calculate, and touch or scan the YubiKey when prompted. Enter the OTP that is generated.

8. Your YubiKey is now registered for OATH authentication. To register a backup YubiKey with your account, repeat this process using the same QR code/secret key and a different account name (for example, “account-name-backup”).

   Tip

   Pin frequently used OATH accounts to the top of the screen for easier access. Desktop and Android tablet devices can also use their wider screens to display more OATH accounts by changing the screen layout.

Authenticating with OATH and Yubico Authenticator

Once an OATH account has been registered with a YubiKey, that key in conjunction with Yubico Authenticator can be used to log in to that account.

To log into an account with OATH, do the following:

1. Begin the login process for your account. This typically requires entering a username and password.

2. Launch Yubico Authenticator, plug your YubiKey into your device, click the menu icon in the upper left corner of the app (desktop and Android only), and select Accounts.

   To connect via NFC on desktop, click the NFC icon in Yubico Authenticator and place your YubiKey on top of a desktop NFC reader. The key must maintain constant contact with the reader throughout the operation.

   To connect via NFC on Android, tap your YubiKey on the back of your device to scan.

   To connect via NFC on iOS/iPadOS, swipe down on the screen and tap your YubiKey on the back of your device to scan.

3. Enter your OATH password if prompted and click Unlock (on desktop and Android) or Ok (on iOS/iPadOS). For NFC connections on Android or iOS/iPadOS, scan your YubiKey again when prompted.

4. Locate your account on the Accounts screen. Next to the account name, you will see either an OTP code or a touch icon.

   If the touch icon is present, click on the account name, select Calculate, and touch or scan the YubiKey when prompted to generate the OTP code. Time-based OTPs are only valid for a short period of time (often 30 seconds). Once this period has lapsed (in other words, the OTP has expired), the OTP code becomes greyed out. To perform authentication again, you will need to repeat this process to generate a new code.

   

   Next, click on the account in Yubico Authenticator and select Copy to clipboard (desktop and Android) or Copy (iOS/iPadOS).

   Note

   On desktop devices, you can speed up this process by double-clicking or long-clicking on the account name (to perform a long click, press and hold the mouse button for a couple of seconds). For accounts whose OTPs do not require user-initiated calculation, this action copies the OTP to the clipboard. For accounts whose OTPs do require user-initiated calculation, the double/long click will perform the calculation and the copy action. If touch is required, you will be prompted by Yuibco Authenticator after clicking. You can also perform the same operation by selecting the account and typing command+C (macOS) or Ctrl+C (Windows/Linux).

   On iOS/iPadOS devices, touch and hold (long-click) the account name to copy the OTP to clipboard (and perform the calculation if applicable). On Android devices, touch and hold the account name to copy the OTP to clipboard. If user-initiated OTP generation is required, you will have to perform the long click operation twice: first to perform the calculation and again to copy the OTP to clipboard.

5. Your account will prompt you for a code from your authenticator app. Paste (or type) the OTP from Yubico Authenticator and click Sign In (or similar).

Password protection

To further enhance the security of your YubiKey, a password can be created for its OATH application so that none of the Accounts features can be accessed (on any device) until the password is entered correctly. This means that OTP codes cannot be viewed or calculated and accounts cannot be viewed, pinned, or deleted prior to password submission.

Once created, the password can be:

• remembered/forgotten on a particular device
• changed
• removed

Important

If you have forgotten your OATH password, the only way to change it is to reset the OATH application of your YubiKey to factory default settings (which will remove the password). Note that this will delete ALL OATH account credentials stored on the YubiKey, and you will no longer be able to access those accounts with that key (we recommend registering at least one backup YubiKey with each account/service to maintain access). Once reset, you can always re-register your key with those same accounts and services.

Desktop and Android

Create an OATH password

To create an OATH password, do the following:

1. Plug your YubiKey into your device, click the menu icon in the upper left corner of the app, and select Accounts.

   To connect via NFC on desktop, click the NFC icon in Yubico Authenticator and place your YubiKey on top of a desktop NFC reader. The key must maintain constant contact with the reader throughout the operation.

   To connect via NFC on Android, tap your YubiKey on the back of your device to scan.

2. Click Set password under Manage.

   

   In a narrow app window, click the three dots in the upper right corner of the app to find the Manage menu.

3. In the Set password window, enter your new password. The password may contain letters, numbers, and special characters. Enter your password again to confirm and click Save.

   For NFC connections on Android, tap your key to complete the operation.

Remember or forget an OATH password

Once the password has been created, you must enter it every time you want to access the Accounts features in Yubico Authenticator. However, you can elect to remember the password on a particular device you trust to bypass this requirement. And once remembered, a password can also be forgotten (cleared from memory) at any time.

To remember or forget an OATH password on a particular device, do the following:

1. Plug your YubiKey into your device, click the menu icon in the upper left corner of the app, and select Accounts.

   To connect via NFC on desktop, click the NFC icon in Yubico Authenticator and place your YubiKey on top of a desktop NFC reader. The key must maintain constant contact with the reader throughout the operation.

   To connect via NFC on Android, tap your YubiKey on the back of your device to scan.

2. To remember the password on your device, enter your OATH password when prompted, click Remember password, and then click Unlock. For NFC connections on Android, tap your key to complete the operation. The next time you connect your YubiKey to your device, you will not be prompted to enter the OATH password to view and manage OATH accounts.

   

3. To forget a remembered password, click Manage password under Manage. In the Manage password window, enter your current password and click Clear saved password. For NFC connections on Android, scan your YubiKey again when prompted. The next time you connect your YubiKey to your device, you will be prompted to enter the OATH password to view and manage OATH accounts.

   In a narrow app window, click the three dots in the upper right corner of the app to find the Manage menu.

Change or remove an OATH pasword

To change or remove an OATH password, do the following:

1. Plug your YubiKey into your device, click the menu icon in the upper left corner of the app, and select Accounts.

   To connect via NFC on desktop, click the NFC icon in Yubico Authenticator and place your YubiKey on top of a desktop NFC reader. The key must maintain constant contact with the reader throughout the operation.

   To connect via NFC on Android, tap your YubiKey on the back of your device to scan.

2. Click Manage password under Manage.

   In a narrow app window, click the three dots in the upper right corner of the app to find the Manage menu.

3. In the Manage password window, enter your current password.

4. To remove the password, click Remove password. For NFC connections on Android, tap your key to complete the operation. Once removed, a new password can be set at any time.

5. To change a password, enter a new password in the box provided. Enter the new password again to confirm and click Save. For NFC connections on Android, tap your key to complete the operation.

   

iOS/iPadOS

Create an OATH password

To create an OATH password, do the following:

1. Plug your YubiKey into your device and select Accounts.

   To connect via NFC on iOS/iPadOS, swipe down on the screen and tap your YubiKey on the back of your device to scan.

   

2. Click the three dots in the upper right corner of the app and select Configuration.

3. On the Configuration screen, select Passwords and reset.

   

4. Click Set password, enter your new password. The password may contain letters, numbers, and special characters. Enter your password again to confirm and click Save.

   For NFC connections, tap your key to complete the operation.

Remember or forget an OATH password

Once the password has been created, you must enter it every time you want to access the Accounts features in Yubico Authenticator. However, you can elect to remember the password on a particular device you trust to bypass this requirement. And once remembered, a password can also be forgotten (cleared from memory) at any time.

To remember or forget an OATH password on a particular device, do the following:

1. Plug your YubiKey into your device and select Accounts.

   To connect via NFC on iOS/iPadOS, swipe down on the screen and tap your YubiKey on the back of your device to scan.

2. To remember the password on your device, enter your OATH password when prompted, scan the key again if connected via NFC, and click Save password. The next time you connect your YubiKey to your device, you will not be prompted to enter the OATH password to view and manage OATH accounts.

   

3. To forget a remembered password, click the three dots in the upper right corner of the app and select Configuration. Select Passwords and reset and then Clear saved passwords. Click Clear to confirm the operation. The next time you connect your YubiKey to your device, you will be prompted to enter the OATH password to view and manage OATH accounts.

Change or remove an OATH pasword

To change or remove an OATH password, do the following:

1. Plug your YubiKey into your device and select Accounts.

   To connect via NFC on iOS/iPadOS, swipe down on the screen and tap your YubiKey on the back of your device to scan.

2. Click the three dots in the upper right corner of the app and select Configuration. Select Passwords and reset

3. To remove the password, click Remove password and enter your current password when prompted. For NFC connections, tap your key to complete the operation. Once removed, a new password can be set at any time.

   

4. To change a password, click Set password and enter the new password. Enter the new password again to confirm, click Save, and provide your current password when prompted. For NFC connections, tap your key to complete the operation.

Pinning an account

Once an OATH account has been created, it will be listed on the Accounts screen in Yubico authenticator whenever the YubiKey is connected to the device. Once several accounts have been registered, not all of them will be visible without scrolling in the app window. If some accounts are accessed more often than others, you may wish to pin them.

Pinning an account ensures that it remains at the top of the Accounts screen. If you have more than one account pinned, they will be ordered alphabetically (first by issuer, then by account name).

Tip

Desktop and Android tablet devices can also use their wider screens to display more OATH accounts by changing the screen layout.

To pin an account, do the following:

1. Plug your YubiKey into your device, click the menu icon in the upper left corner of the app (desktop and Android only), and select Accounts.

   To connect via NFC on desktop, click the NFC icon in Yubico Authenticator and place your YubiKey on top of a desktop NFC reader. The key must maintain constant contact with the reader throughout the operation.

   To connect via NFC on Android, tap your YubiKey on the back of your device to scan.

   To connect via NFC on iOS/iPadOS, swipe down on the screen and tap your YubiKey on the back of your device to scan.

2. Enter your OATH password if prompted and click Unlock (on desktop and Android) or Ok (on iOS/iPadOS). For NFC connections on Android or iOS/iPadOS, scan your YubiKey again when prompted.

3. Select the account you wish to pin and click Pin (iOS/iPadOS) or Pin account (on desktop and Android, this is located under Actions). Once pinned, you can unpin the account at any time by clicking Unpin (iOS/iPadOS) or Unpin account (desktop and Android).

   

Renaming an account

Note

The OATH account renaming feature is only available for YubiKeys with firmware version 5.3.1 or later.

Once an OATH account has been registered with your YubiKey, both the issuer and account name can be edited. To renamed an OATH account, do the following:

1. Plug your YubiKey into your device, click the menu icon in the upper left corner of the app (desktop and Android only), and select Accounts.

   To connect via NFC on desktop, click the NFC icon in Yubico Authenticator and place your YubiKey on top of a desktop NFC reader. The key must maintain constant contact with the reader throughout the operation.

   To connect via NFC on Android, tap your YubiKey on the back of your device to scan.

   To connect via NFC on iOS/iPadOS, swipe down on the screen and tap your YubiKey on the back of your device to scan.

2. Enter your OATH password if prompted and click Unlock (on desktop and Android) or Ok (on iOS/iPadOS). For NFC connections on Android or iOS/iPadOS, scan your YubiKey again when prompted.

3. Select the account you wish to rename and click Rename (iOS/iPadOS) or Rename account (on desktop and Android, this is located under Actions). Edit the Issuer and/or Account name as desired. Click Save to confirm the operation.

   For NFC connections on Android or iOS/iPadOS, tap your key to complete the operation.

Deleting an account

OATH accounts can be deleted from your YubiKey. Before deleting an account from a YubiKey, make sure you have either disabled two-factor authentication within your account or registered a backup YubiKey with the same account to maintain access.

To delete an account, do the following:

1. Plug your YubiKey into your device, click the menu icon in the upper left corner of the app (desktop and Android only), and select Accounts.

   To connect via NFC on desktop, click the NFC icon in Yubico Authenticator and place your YubiKey on top of a desktop NFC reader. The key must maintain constant contact with the reader throughout the operation.

   To connect via NFC on Android, tap your YubiKey on the back of your device to scan.

   To connect via NFC on iOS/iPadOS, swipe down on the screen and tap your YubiKey on the back of your device to scan.

2. Enter your OATH password if prompted and click Unlock (on desktop and Android) or Ok (on iOS/iPadOS). For NFC connections on Android or iOS/iPadOS, scan your YubiKey again when prompted.

3. Select the account you wish to delete and click Delete (iOS/iPadOS) or Delete account (on desktop and Android, this is located under Actions). Click Delete to confirm the operation.

   For NFC connections on Android or iOS/iPadOS, tap your key to complete the operation.

Custom icons

Note

Custom icons are only available for Yubico Authenticator for Desktop and Android.

When viewing OATH accounts on a YubiKey within Yubico Authenticator, each account is listed with a colored icon that contains the first letter of the issuer by default.

To make accounts more easily distinguishable from one another, custom icons can be uploaded and used in Yubico Authenticator. For example, with custom icons, instead of seeing the default “D” icon next to an OATH account for Docker, an icon containing the Docker logo and colors would be shown.

Icon packs must be in the Aegis Icon Pack format. Feel free to use a pre-built icon pack from Aegis or create your own.

To upload a custom icon pack to Yubico Authenticator on desktop or Android, do the following:

1. Download a pre-built icon pack from Aegis or create your own.

2. Plug your YubiKey into your device, click the menu icon in the upper left corner of the app, and select Accounts.

   To connect via NFC on desktop, click the NFC icon in Yubico Authenticator and place your YubiKey on top of a desktop NFC reader. The key must maintain constant contact with the reader throughout the operation.

   To connect via NFC on Android, tap your YubiKey on the back of your device to scan.

3. Select Custom icons under Manage.

   In a narrow app window, click the three dots in the upper right corner of the app to find the Manage menu.

4. In the Custom icons window, click Load icon pack. Select the file containing the icons (for example, aegis-icons.zip).

5. Once loaded, any OATH account with an issuer that is supported by the icon pack will display the custom icon. To delete the icon pack, click the trash can icon in the Custom icons window. Similarly, to update the icon pack, click Replace icon pack and select the new file.