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.

Yubico provides multiple tools to configure devices:

YubiKey Manager

The YubiKey Manager writes a base32-encoded seed string for use in for device enrollment on the Identity Platform.

Prerequisites

Programming YubiKeys in OATH HOTP mode

  1. Launch YubiKey Manager. The software detects and displays the connected key.

    yubikey_manager_001.png

  2. Click Applications, then select OTP.

    yubikey_manager_002.png

  3. Click Configure for the slot you want to set up for HOTP.

    yubikey_manager_003.png

  4. Select OATH-HOTP as the credential type, then click Next.

    yubikey_manager_004.png

  5. Select the Digit length based on your multi-factor (MFA) settings in the Identity Platform. Enter a base32-encoded seed. Generate this locally using a PowerShell script (see later section) or an online generator like TOKEN2.

    yubikey_manager_005.png

  6. Click Finish to save the configuration to the device.

Use YubiKey Manager programmatically

You can configure YubiKey Manager via the command line for faster setup. Use PowerShell to generate a random base32 seed and pass it to the YubiKey command-line utility.

Note

Yubico does not support the utility directly through PowerShell.

Generate a base32 seed with PowerShell

Use the following script from Yubico to create a base32 seed. Adjust the -lt value to change the length.

## Generate a Base32 String for HOTP Devices ##
$RNG = [Security.Cryptography.RNGCryptoServiceProvider]::Create()
[Byte[]]$x=1
for($b32string=''; $b32string.length -lt 32){$RNG.GetBytes($x); if([char]$x[0] -clike '[2-7A-Z]'){$b32string+=[char]$x[0]}}
Write-Output $b32string

Use the seed in a batch script

This script:

  • Runs the PowerShell script base32.ps1 from C:\OTP

  • Programs the HOTP configuration to slot 1

@echo off
setlocal
:: Generate a base32 seed and store it in a variable 
for /f "delims=" %%A in ('powershell -ExecutionPolicy Bypass -File "C:\OTP\base32.ps1"') do set "output=%%A"
:: Configure YubiKey slot 1 with the seed
"C:\Program Files\Yubico\YubiKey Manager\ykman.exe" otp hotp 1 %output%
:: Display the configured key
echo Yubikey slot 1 has been programed with key: %output%
endlocal

Use the generated base32 seed to register the YubiKey in your Identity Platform via Self-Service, Account Management, or bulk import.

YubiKey Personalization Tool

Use 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: