Onboarding for End Users – with YubiKey (HOTP programmable token)
YubiKey are programmable tokens, powered by Yubico, which can be configured to use HMAC-based One-time Passwords (HOTP) for multi-factor authentication.
HOTP is an alternative to Time-based One-time Passwords (TOTP). Note that the most used TOTP solutions are authentication applications (for example Google Authenticator) or programmable tokens (for example, Token2).
UserLock configures YubiKey in an efficient manner uniquely on the server side thus avoiding any client based configuration.
To authenticate with YubiKey, users simply tap their security key. This touch activated YubiKey automatically enters a pre-determined authentication code; thus avoiding the possibility of the end user entering an invalid code.
Since end users may already use YubiKey for other purposes (web authentication, personal use, etc.) adding MFA functionality requires the configuration of an available slot for the device.
Pressing the device with a short touch, or a longer touch of 3 seconds, will determine which of the two programmable slots will be activated. In such cases, the user is already familiar with the operational features of the YubiKey device.
A video presenting YubiKey and UserLock is available here.
For more details and references on YubiKey, see the “About YubiKey” section at the end of this document.
Requirements
Users require a YubiKey with HOTP support such as YubiKey 5 NFC or the whole YubiKey 5 Series. This device must be inserted into a USB port of their computer during the connection.
To enroll in MFA with YubiKey, users will have to connect directly (and not via RDP) to a computer for the Desktop UserLock agent to detect the YubiKey (unless USB redirection is supported in which case it is possible to remotely configure your YubiKey). Subsequent connections will allow RDP connections with the YubiKey plugged into the USB port of the client computer.
To enable two-factor authentication with UserLock and YubiKey
Once MFA is activated for a user account (configure the MFA frequency you need), this user may need help logging in for the first time with UserLock and YubiKey:
-
The user plugs the YubiKey into the USB port of their computer (do not connect via RDP for this first connection as explained in the "Requirements" section).
-
The user logs in.
-
The UserLock desktop agent automatically detects that a YubiKey is connected and therefore asks the user if it is the preferred method to configure multi-factor authentication (otherwise the TOTP dialog box will be displayed):
-
If the user chooses "Yes", a dialog box appears, showing the available YubiKey slot. Choose the slot, then click "Link Yubikey":
-
Next, the Desktop UserLock agent programs the YubiKey using the MFA secret (without displaying it), then updates the Link YubiKey button to confirm that the operation succeeded:
-
The cursor appears in the edit box of the authentication code and the user can touch the YubiKey depending on the selected slot: Generally, a short touch will activate Slot 1 or a long touch will activate Slot 2.
As a result, the edit box will display the associated 6-digit code and automatically close the dialog box indicating that the verification operation succeeded.
Subsequent connections for two-factor authentication with UserLock and YubiKey
Following the initial connection in which the YubiKey configuration is included, subsequent connections where MFA is requested will occur as follows:
-
The user plugs the YubiKey into a USB port of their computer (the client computer if they are using RDP).
-
The user logs in.
-
The UserLock desktop agent requests the authentication code:
-
The user touches the YubiKey button depending on the slot chosen: Generally, a short touch will activate Slot 1 or a long touch will activate Slot 2.
The edit box will display the associated 6-digit code. In order to logon, The user clicks "Verify and continue".
Advanced
YubiKey and RDP
As explained in the “Requirements” section, To enroll in MFA with YubiKey, users will have to connect directly (and not via RDP) to a computer for the Desktop UserLock agent to detect the YubiKey (unless USB redirection is supported in which case it is possible to remotely configure your YubiKey). Subsequent connections will allow RDP connections with the YubiKey plugged into the USB port of the client computer.
Use case: What to do if YubiKey is lost, forgotten...
The optional Ask for help UserLock MFA feature (disabled by default) is designed to alert UserLock administrators in such cases: actions include resetting the MFA key, temporarily disabling MFA, assistance activating the Yubikey...
Use case: What to do if I used TOTP before and now I use HOTP YubiKey?
For such users, reset the MFA key, then configure YubiKey as explained in the section "To enable two-factor authentication with UserLock and YubiKey".
TOTP and / or HOTP
The choice between TOTP and HOTP depends on several arguments. For example, HOTP is a preferred choice if the UserLock server is installed on a virtual machine on which the clock is not synchronized as often as TOTP MFA requires. (If your VM is installed as part of a Hyper-V platform there is also a risk of time synchronization issues).
Limitations
Configuration of YubiKey is not possible with an RDP session
Unable to configure YubiKey with an RDP session, a physical connection to a computer is required.
Use with virtual machines may be limited
It is possible to mount YubiKey in Virtual Box Virtual Machines: using YubiKey on such machines is possible for both configuration and authentication. However, there are issues when trying to configure them with Hyper-V virtual machines, although authentication is possible.
Risk of HOTP desynchronization if there is a high number of logins without network connection
If there is a high number of logons without network connection, the token's HOTP counter may be out of sync with the UserLock server side. If so, the MFA code will not be accepted. By default, an offset of 6 codes between the 2 counters is authorized, you can modify this number via the advanced parameter "MaxHotpCodeCount".
About YubiKey
YubiKey are programmable tokens powered by Yubico.
Getting started with your YubiKey
The YubiKey supports multiple protocols and offers expanded authentication options such as passwordless, strong two-factor authentication (2FA) and strong multi-factor authentication (MFA), and also enables encryption. It also supports Windows/Mac computer logon.
YubiKey protect Google employees since 2009. See the case study on the Yubico website (video).