12.3.1. Yubikey Enrollment Tools¶
The Yubikey can be used with eduMFA in Yubico’s own AES mode (Yubico OTP), in the HOTP mode (OATH-HOTP) or the seldom used static password mode.
This section describes tools which can be used to initialize and enroll a Yubikey with eduMFA.
If not using the Yubico mode, the Yubikey has to be initialized/configured which creates a new secret on the device that has to be imported to eduMFA.
12.3.1.1. Yubikey Personalization GUI¶
You can initialize the Yubikey with the official Yubico personalization GUI [1] and use the obtained secret to enroll the Yubikey with eduMFA. For both AES (Yubico OTP) and OATH-HOTP mode, there are two possibilities to initialize the Yubikey with eduMFA.
12.3.1.1.1. Manual token enrollment¶
To initialize a single Yubikey in AES mode (Yubico OTP) use the Quick button and copy the displayed secret labeled with “Secret Key (16 bytes Hex)” to the field OTP Key on the enrollment form in the eduMFA WebUI.
Initialize a Yubikey in AES mode (Yubikey OTP)¶
Enroll a Yubikey AES mode token in eduMFA¶
In the field “Test Yubikey” touch the Yubikey button. This will determine the length of the OTP value and the field OTP length is automatically filled.
Note
The length of the unique passcode for each OTP is 32 characters at the end of the OTP value. The remaining characters at the beginning of the OTP value form the Public ID of the device. They remain constant for each OTP [2].
eduMFA takes care of separating these parts but it needs to know the complete length of the OTP value to work correctly.
The process is similar for the HOTP mode. You have to deselect OATH Token Identifier. Copy the displayed secret to the HOTP Enrollment form in eduMFA.
To initialize a single Yubikey in HOTP mode, deselect OATH Token Identifier.¶
Note
In the case of HOTP mode eduMFA can not necessarily distinguish a Yubikey in HOTP mode from a smartphone App in HOTP mode. Using the above mentioned mass-enrollment, the token serial number is used to distinguish these tokens.
12.3.1.1.2. Mass enrollment¶
To initialize one or more Yubikeys it is convenient to write the created token secrets to a file which can be imported in the eduMFA WebUI. To do this, activate Settings -> Log configuration output. We recommend to select Yubico format since here eduMFA is able to detect the Yubikey mode and sets the serial accordingly prepending UBOM or UBAM. PSKC format is also supported upon import. You may also use the Flexible format to set custom token serials upon import with OATH CSV.
To set a custom serial for Yubikey Tokens, set the Flexible format to:
YUBIAES{serial}_{configSlot},{secretKeyTxt},yubikey
For Yubikeys in HOTP mode, set the output format as:
YUBIHOTP{serial}_{configSlot},{secretKeyTxt},hotp,{hotpDigits}
Upon clicking Write Configuration for the first time, you will be prompted to select an output file name and the generated configuration is written both to the device and to the selected file. In the Advanced mode select Program Multiple Yubikeys and Automatically program Yubikeys when inserted to program each Yubikey automatically after you insert it.
Write Configuration initializes the Yubikey¶
During this process the token secrets are automatically appended to the selected export file. Note again, that for HOTP, you have to deselect OATH Token Identifier.
After mass-initialization, the token secrets have to be imported to eduMFA according to the output format (see Import).
Footnotes