---
locale: "en"
updated_at: "2025-10-27T13:30:38.386Z"
canonical: "https://www.isdecisions.com/en/userlock/docs/guides/end-users-mfa-enrollment/yubikey-hotp-programmable-token"
---

# Enroll users with YubiKeys (HOTP)

Use and configure a YubiKey as an MFA token.

## Introduction

YubiKeys are programmable hardware tokens by [Yubico](https://www.yubico.com/). 

UserLock supports HOTP-based YubiKeys, allowing MFA without any client-side setup.
At logon, users simply **touch the YubiKey** — it automatically enters the one-time password, minimizing input errors.

This guide explains how to help end users **enroll a YubiKey** as their second factor of authentication with UserLock.
It covers the setup process, usage at login, and troubleshooting basics.

> **Note**
>
> 🚩 **Before following this guide:**
> We recommend reading [How to implement MFA](/userlock/docs/guides/mfa-implementation/how-to-implement-mfa) for general recommendations, communication tips, and preparation steps to ensure a smooth rollout.

## Requirements

- A YubiKey model with HOTP support (for example: [YubiKey 5 NFC](https://www.yubico.com/product/yubikey-5-nfc) or any [ YubiKey 5 Series](https://www.yubico.com/store/#yubikey-5-series).).
- The YubiKey must be plugged into the USB port of the user’s computer.
- Enrollment must be performed in a **local desktop session** (not via RDP), unless USB redirection is supported.
- After enrollment, RDP logins with the YubiKey plugged into the client computer are supported.

> **Note**
>
> - If users already use YubiKeys for other purposes (e.g., web logins), ensure a free slot is available for MFA with UserLock.
> - YubiKeys can store multiple credentials in two programmable slots (short touch = slot 1, long touch = slot 2).

## Step 1. Enable MFA for the user

Before enrolling, make sure that **MFA is enabled** for the user account in UserLock.

> **Note**
>
> - See [Access policy management](/userlock/docs/reference/access-policies/access-policy-management) to learn how to apply an access policy in UserLock.
> - See [MFA policy reference](/userlock/docs/reference/access-policies/mfa) for details on MFA policy rules and options.

## Step 2. Enroll the Yubikey

When MFA is enabled for a user account, follow these steps to configure YubiKey:

1. Plug the YubiKey into the computer’s USB port. **Do not connect via RDP for the first enrollment.**
2. Log in to Windows.
3. The UserLock Desktop Agent detects the YubiKey and asks whether it should be configured for MFA. Click **Yes** (if the user declines, TOTP setup is offered instead):
  ![](https://a.storyblok.com/f/122374/361x159/03447dd24d/1-mfa-yubikey-detected.png)
4. Select a YubiKey slot, then click **Link YubiKey:**
  ![How UserLock MFA detects YubiKey](https://a.storyblok.com/f/122374/525x606/2f857df29e/yubikey-detected-mfa.png)
5. The Desktop Agent programs the YubiKey automatically (the MFA secret is never displayed). Click on Success button to confirm:
  ![](https://a.storyblok.com/f/122374/426x89/0a1c5b9da4/3-press-yubikey.png)
6. Touch the YubiKey (short or long press, depending on slot). The 6-digit code is entered automatically.
7. Enrollment is complete, and the user is logged in.

## Step 3. Authenticate

Once enrolled, MFA with YubiKey works as follows:

1. Plug the YubiKey into the computer’s USB port (local or RDP client machine).
2. Log in.
3. When prompted, touch the YubiKey.
4. The 6-digit code is entered automatically.
5. Click **Verify and continue** to complete login.

## Advanced topics

### Using YubiKey with RDP

- Enrollment must be done on a **local desktop session**.
- After enrollment, users can log in through RDP with the YubiKey connected to their client computer.
- If USB redirection is enabled, remote enrollment may be possible.

### Lost or unavailable YubiKey

If a YubiKey is lost or unavailable, administrators can help using the optional **Ask for help** feature (disabled by default). Possible actions:

- Reset the MFA key.
- Temporarily disable MFA.
- Assist the user in activating a new YubiKey.

### Migrating from TOTP to YubiKey HOTP

If a user was previously using TOTP and now switches to HOTP:

- Reset the MFA key.
- Re-enroll using the First-time enrollment procedure.

## Limitations

- **Enrollment** must be done locally (desktop session only).
- Tokens cannot be enrolled via RDP, IIS, SaaS, or VPN sessions. After setup, they can be used for these connections.
- **Virtual machines**: YubiKey works with VirtualBox (setup + authentication). With Hyper-V, authentication works but setup may fail.
- **HOTP desynchronization**: If a YubiKey is used for many offline logins, its counter may desynchronize with UserLock.
  - By default, UserLock tolerates a drift of 6 codes.
  - This can be adjusted via the advanced parameter `MaxHotpCodeCount`.

## About YubiKeys

YubiKeys are programmable tokens created by Yubico.
They support multiple authentication methods including HOTP, TOTP, passwordless authentication, and smartcard logon.

- YubiKeys have been deployed at scale since 2009 (for example at Google).
- More information and case studies are available on the [Yubico website](https://www.yubico.com/).
- 🎥 [Using YubiKey with UserLock](https://www.yubico.com/works-with-yubikey/catalog/userlock/)