Skip to main content

Program YubiKeys to generate OATH HOTP passcodes

As an administrator, you must program YubiKey devices to generate HMAC-based one-time passcodes (HOTP) before you can provision them for your end users in the Identity Platform.

You'll need the YubiKey Personalization Tool to program YubiKeys and create the Portable Symmetric Key Container (PSKC) file that contains secret keys in plain value format, to provision the YubiKey devices.

For more information from Yubico, see How to: Programming the YubiKey with an OATH-HOTP credential and OATH-HOTP: Yubico Best Practices Guide.

Prerequisites

  • Download and install the YubiKey Personalization Tool from Yubico

  • Supported YubiKey devices. See the SecureAuth compatibility guide.

    Important

    If an end user has a YubiKey device enrolled in the Identity Platform for multi-factor authentication (MFA) on a resource, you must remove the OATH seed and associated YubiKey device from their account. This is to prevent a conflict when the end user attempts to use a YubiKey device to authenticate using HOTP.

    When using a YubiKey on a macOS, the Keyboard Setup Assistant wizard or the message, "Your keyboard cannot be identified" might appear. You can disregard these scenarios. For more information, see the Yubico article Getting Started with the YubiKey on macOS.

Programming YubiKeys in OATH HOTP mode

  1. Open the YubiKey Personalization Tool, insert the YubiKey in your machine, and click Settings.

    yubikey_program_001.png

  2. In the Logging Settings section, select the Log configuration output check box and choose PSKC format.

    yubikey_program_002.png

  3. Select the OATH-HOTP tab and click Quick mode.

    yubikey_program_003.png

  4. In the Configuration Slot section, select the method end users can use to generate a YubiKey HOTP passcode:

    Configuration Slot 1

    With this method, a passcode is generated with a quick touch of the YubiKey.

    Configuratrion Slot 2

    With this method, a passcode is generated with longer, multi-second touch of the YubiKey.

    yubikey_program_004.png

  5. In the OATH-HOTP (auto generated) section, select the passcode length as 6 Digits or 8 Digits.

    Note

    The passcode length must match the configured YubiKey passcode length set in the Identity Platform Multi-Factor Methods configuration.

    yubikey_hotp_settings.png

  6. Clear the check boxes for OATH Token Identifier and Hide Secret.

  7. To populate the the Secret Key field with a new auto-generated secret key in hexadecimal format, click Regenerate.

  8. To program the selected configuration slot for the YubiKey, click Write Configuration.

    • If you selected Configuration Slot 1, and you do not want to overwrite this configuration slot, click No.

      yubikey_program_005.png

    • If you selected Configuration Slot 2, save the configuration log file.

      yubikey_program_006.png

Notes about the configuration log file

The configuration log (PSKC) file contains the device serial number in the <SerialNo> field. The corresponding secret key is converted to a plain value in the <Secret><PlainValue> field. You enter this information when provisioning the YubiKey OATH HOTP in the Identity Platform.

Important

Each time you program a YubiKey, its serial number and secret key are stored in the same configuration log file, regardless of the session in which the device was configured. If you re-program a YubiKey, a new entry for the device is entered at the end of the configuration log file.

It is important when provisioning a YubiKey HOTP device in the Identity Platform to use the latest entry from the configuration log file.

In this section: