Configuring YubiKeys for OTP use with Duo

Overview

To use a YubiKey hardware token you will need to enter its stored secret in your Duo Admin Panel. If you do not know the current stored secret you can use the YubiKey Manager to reconfigure the YubiKey.

This information applies to YubiKey tokens that support one-time password (OTP) functionality, like the YubiKey 5 series or YubiKey 4 series. Verify your YubiKey's capabilities at the Yubico site.

Generate YubiKey Configuration

Each YubiKey with OTP support has two slots. The first slot is used to generate the passcode when the YubiKey is touched for between 0.3 and 1.5 seconds and released. The second slot is used if the button is touched between 2 and 5 seconds. When the YubiKey is shipped its first configuration slot is factory programmed for the "Works with YubiKey" YubiCloud OTP service and the second configuration slot is blank.

If you are already using this YubiKey with an existing service, the following steps will overwrite the stored secret for that service. You will no longer be able to use the YubiKey to log into other services unless you also update the stored secret information there. If you are using your YubiKey with a service that integrates with Yubico's OTP service and you overwrite that factory configuration in the first slot, you cannot recover that configuration. You must upload the new credential to YubiCloud to continue using that service.

Using YubiKey Manager

First, download and install the YubiKey Manager.

When you open the Yubico OTP settings (under Applications), you may generate a new "Public ID", "Private ID", and/or "Secret Key", but these are not written to the token unless you actually click the Finish button. There is no way to read your existing "Public ID" (if you did not use the device serial), "Private ID", and "Secret Key" information off the token once it has been written.

To create or overwrite a YubiKey slot's configuration:

1. Insert the YubiKey into a USB port.
2. Start the YubiKey Manager.
3. Wait for the YubiKey Manager to recognize your YubiKey. You'll see the YubiKey model, firmware version, and serial number shown in the application.

4. Click Applications → OTP.

   

5. Determine which OTP slot you'd like to configure and click the Configure button for that slot.

6. Keep Yubico OTP selected on the "Select Credential Type" screen and click Next.
7. Check the Use serial box for "Public ID" (recommended).
8. Click the Generate buttons to create a new "Private ID" and "Secret key".
9. Click Finish to update the OTP information for the selected slot.

There is no need to check the Upload option. Enabling this uploads the new configuration to Yubico's YubiCloud OTP validation service. Duo confirms the passcodes generated independently of Yubico's service. However, you may upload the configuration if you wish to also use YubiCloud OTP to authenticate to services other than Duo.

You will need the Public ID (which is the token serial number if you checked the "Use serial" box earlier), Private ID, and Secret key to add the YubiKey to your Duo account. You may also want to save this information, along with the Public Identity, somewhere safe since you will need them if you use this YubiKey with other services in the future.

Using YubiKey Personalization Tool

The YubiKey Personalization Tool is no longer actively updated or maintained by Yubico. Consider updating to the YubiKey Manager instead and following those instructions.

Every time you open the Yubico OTP tab, it generates a new "Public Identity", "Private Identity", and "Secret Key", but these are not written to the token unless you actually click Write Configuration. There is no way to read your existing "Public Identity", "Private Identity", and "Secret Key" off the token once it has been written.

To create or overwrite a YubiKey slot's configuration:

1. Start the YubiKey Personalization Tool.
2. Insert the YubiKey into a USB port.
3. Wait for the Personalization Tool to recognize the YubiKey.

4. Click Yubico OTP Mode in the main tool window, or Yubico OTP at the top-left.

   

5. Click Quick on the "Program in Yubico OTP mode" page.

6. Select Configuration Slot 1 (or Configuration Slot 2 if Slot 1 is already being used by another service).
7. Click Regenerate.
8. Uncheck Hide Values.
9. Click Write Configuration

You will need the Serial Number (in decimal format), Private Identity, and Secret Key to add the YubiKey to your Duo account. You may also want to save this information, along with the Public Identity, somewhere safe since you will need them if you use this Yubico OTP credential with other services in the future.

There is no need to click Upload to Yubico. Enabling this uploads the new configuration to Yubico's YubiCloud OTP validation service. Duo confirms the passcodes generated independently of Yubico's service. However, you may upload the configuration if you wish to also use YubiCloud OTP to authenticate to services other than Duo.

Add Token in Duo Admin Panel

Follow the instructions for importing third-party OTP tokens, specifying the YubiKey type:

1. Log into the Duo Security Admin Panel.
2. Go to 2FA Devices → Hardware Tokens.
3. Click the Import Hardware Tokens button.
4. Set the dropdown to YubiKey AES

5. If you used the YubiKey Manager tool to set your OTP configuration, enter the YubiKey's Public ID, Private ID, and Secret key values from that tool into the CSV token data text box, separated by commas.

   If you used the YubiKey Personalization Tool to set your OTP configuration, enter the YubiKey's Serial Number, Private Identity, and Secret Key values from that tool into the CSV token data text box, separated by commas.

   The YubiKey OTP information should look something like this after you paste it into the text box (spaces are ignored):

   01231337, 0c 87 99 55 78 ee, a4 d0 93 a9 bd 09 e1 24 e9 17 b6 72 03 56 a1 3b
   

   If you wish to import multiple YubiKey OTP tokens, enter each token's information on a new line.

6. Click Import Hardware Tokens to create the YubiKey tokens in Duo.

Assign the YubiKey Token to a User

After importing your YubiKey OTP tokens into Duo you can assign them to users for Duo-protected application logins, or to Duo administrators for use when logging into the Duo Admin Panel.

Troubleshooting

Need some help? Take a look at our Yubikey Knowledge Base articles or Community discussions. For further assistance, contact Support.