Programming a Yubico Yubikey for use as a 2nd-factor Authentication token with SSProtect is simple, as the OATH mapping is almost direct. Follow the directions below to program a key and convert values to those compatible with SSProtect entries.
IMPORTANT: It's best to program your Yubikey on a host computer isolated from all networking capabilities, then associate the token with the proper Account using SSProtect on a different network-connected host computer. If you do not have the flexibility to proceed in this fashion, avoid using copy/ paste operations (ctrl-c and ctrl-v) to make sure sensitive token data isn't made available on the Clipboard.
Yubico Yubikey 2nd-Factor Authentication
Use the procedure, below, to configure your Yubikey for use with SSProtect. Examples for specific values are given at the end of this sequence.
1. Insert your Yubikey and start the Personalization Tool available from Yubico
2. Choose Configuration Slot 1 or Configuration Slot 2 for your hardware token. The 1st slot is more convenient as it will not require you to press and hold the sensor when acknowledging the SSProtect 2nd-factor authentication prompt.
4. For the OATH-HOTP Parameters, check the OATH Token Identifier checkbox
5. Set the OATH Token Identifier to All Numeric
6. Either use the Generate MUI or create a unique Token Identifier. These 12 digits will match those entered into the SSProtect 2-Factor Auth Hardware ID field. Note however that you will not include spaces in the SSProtect entry; enter all 12 digits consecutively. Also note the format of this field reserves the first 2 bytes for specific vendor information. Consult the related Yubikey documentation for more information. In most cases, you will have your own Organization ID and use this for all Yubikeys in an Organization. SSProtect however does nothing more than match this field, so you are free to choose how you use these values (though they must be unique for each SSProtect Account's 2nd-factor token identifiers).
7. Choose an HOTP Length of 6 Digits
8. For Moving Factor Seed, choose Randomize. The resulting value is the decimal equivalent of the 2-Factor Auth Moving Factor. Convert the value to Hex and be sure to include the preceding 00s when entering the Moving Factor value. See the example data, below, for more.
9. Use Generate for a random Secret Key value. Type this sequence of hex values, spaces included, directly into the SSProtect 2-Factor Auth Secret field. This value cannot be all 00s.
10. Program your Yubikey with Write Configuration. Be sure to manage your resulting configuration.csv log file appropriately. Finalize the SSProtect configuration with Add. So long as another token doesn't exist with the same Token Identifier and the software is able to communicate with KODiAC Cloud Services, SSProtect should return you to the Administer Users display. If you updated the 2nd-factor for your own Account, SSProtect will prompt you to login again.
From this point forward, when you perform an SSProtect operation that requires 2nd-factor authentication, insert your Yubikey and touch the sensor to generate the required One-Time Password. If you do this in Notepad, you'll notice the first 12 digits match the Token Identifier and the last 6 are different each time.* SSProtect uses all of the digits, thus they must be captured by the 2nd-factor prompt dialog as described in the article, Configuring a 2nd-Factor USB Token for Data Access.
NOTE: If when prompted for 2FA data, you touch the key and the prompt dialog does not change, click the dialog (or the edit field of the dialog) and try again. Though the dialog is able to capture input in most cases, some application behavior re-captures it before you touch the token.
Consult the following Personalization Tool screenshot and subsequent SSProtect 2-Factor Auth values for clarity regarding noted steps:
SSProtect 2-Factor Auth Input Values
Hardware ID: 123489377363
Moving Factor: 00 00 00 00 00 01 83 40
Secret: 84 f3 96 49 01 e1 fe 77 0c 03 99 01 20 44 27 ee b8 7b cb 20
*If you touch the Yubikey and generate a One Time Password that SSProtect doesn't pick up, KODiAC Cloud Services and the Yubkey token now have counters that are out of sync. This is OK so long as the values remain within the 20-count range of the system's processing tolerance. If however KODiAC falls behind by too many counts, use the Sync 2Factor operation in the Administer Users dialog for the target Account.
For More Information
For information regarding product features and content, consult the Document Index, or send email with specific questions to firstname.lastname@example.org.
This article was updated w/ v9.1.3 of the :Foundation Client