Using YubiKey Authentication in Okta Skip to main content
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Using YubiKey Authentication in Okta
Published: Mar 5, 2016   -   Updated: Jun 22, 2018
A YubiKey, produced by Yubico, is a multifactor authentication device that delivers a unique password every time it's activated by an end-user. Using their USB connector, end-users simply press on the YubiKey hard token to emit a new, one-time password (OTP) to securely log into their accounts. Security is assured, as all YubiKey validation occurs within the Okta Cloud. As such, Okta guarantees Okta-level quality of service and uptime for YubiKey authentication.

Obtaining Your Configuration Secrets file

Before you can enable the YubiKey integration as a multifactor authentication option, you need to obtain and upload the Configuration Secrets file, a .csv file generated through Yubikey software. For detailed instructions on how to do this, see Configuring Yubikey Tokens.

Uploading into the Okta Platform

Once you've generated your Configuration Secrets file or obtained and unencrypted one provided by Yubikey, you'll need to upload it into the Okta framework. To do so,

  1. From the Dashboard, click the Security drop-down menu.
  2. From this menu, scroll down to Authentication.
  3. On the Authentication page, click the Yubikey tab.
  4. Click the Browse button to find and upload your Configuration Secrets file.

Once uploaded, the screen verifies the number of successfully uploaded YubiKeys, and lists any errors that occurred in the process.

User-added image

You can also upload multiple Configuration Secrets files into the Okta framework.

If Errors Occur

If any errors are reported, access the YubiKey .csv file to correct them. For details on how to troubleshoot this process, reference the Configuring Yubikey Tokens document and refer to the Troubleshooting section.

Managing Tokens

Now, with a successfully uploaded Configuration Secrets file, you can view all the unassigned YubiKeys available within your org. Your end-users should begin to enroll their individual tokens on their devices, and the assigned tokens should begin to appear in your reports. For more details about the end-user experience, see The End-User Experience.

Viewing Your YubiKeys

Click the View Yubikeys Report button to view a list containing the serial values of all your assigned and unassigned Yuibikeys. Alternatively, you can find the same information from the Reports page.

To do so,

  1. From the Dashboard, click to the Reports drop-down menu.
  2. From this menu, scroll down to Reports.
  3. On the Reports page, scroll down to the MFA Usage link.
  4. Click the Yubikey Report button.

A report can be run at any time to view:

  • Active tokens
  • Blocked tokens
  • Unassigned tokens
  • Names of assigned end-users

Active Token

A YubiKey which is associated with a user.

Blocked Token

A YubiKey which was once active, but is now either reset by the end user or the Okta admin.

Unassigned Token

An unassigned YubiKey has secret values uploaded and is ready to be self enrolled by an end-user.

Removing Lost, Stolen, or Invalid YubiKeys

Another benefit of the YubiKey hard token is the ability to easily unauthorize users if it is ever lost or stolen—it is non-transferable and easily replaced. If an end-user reports their YubiKey as lost or stolen, you can remove these individual tokens using its unique serial number. This method is also the way to remove unassigned YubiKeys. Ensure the YubiKey has already been reset by following the Resetting MFA instructions. A YubiKey serial can not be removed if it is currently active for a user.

From the Yubikey tab,

  1. Enter the serial number into the Revoke Yubikey Seed field.
  2. Click the Find Yubikey button, as shown below.
User-added image
  1. A Delete Yubikey modal appears to verify that you wish to permanently delete the YubiKey.
  2. A confirmation page appears. Click the Done button.

Best Practice: If a lost YubiKey is found, it's a best practice to simply discard the old token. An admin can also reprogram the YubiKey by following the steps within the Programming Yubikeys for Okta file, which can be found in Configuring Yubikey Tokens. This generates a new Configuration Secrets file for upload, and allows the token to be re-enrolled by any end user within the Okta framework.

Resetting MFA

There may be an instance where you require that particular end users reset their multifactor settings. Reset individual factors at the directory level to disassociate a YubiKey from an end user.

To do so,

  1. From the Dashboard, click the Directory drop-down menu.
  2. From this menu, scroll down to People.
  3. Find the end-user name and click their link.
  4. Click the More Actions button.
  5. Scroll down and click Reset Multifactor.
  6. On the following screen, choose Yubikey for reset.
  7. Click Reset Selected Factors. If you need to reset all of the user's factors, choose the Reset All button.

When you have selected end users to reset their MFA, they are prompted with a modal pointing out which factor they need to reset.

The End-User Experience

What happens for your end user? Enrollment is simple. When a user signs into Okta for the first time or after a reset, they will be prompted to choose an MFA option for their account. At this point, they can choose the Yubikey option. User-added image

Once they click the Setup button, step-by-step instructions follow for successful registration.

User-added image

Enrollment Failure

If an end user is unable to successfully enroll their YubiKey, ensure that the token was successfully uploaded into the Okta platform. Navigate to the Yubikey Report found on the Reports page.

To do so,

  1. From the Dashboard, click to the Reports drop-down menu.
  2. From this menu, scroll down to Reports.
  3. On the Reports page, scroll down to the MFA Usage link.
  4. Click on the Yubikey Report.
  5. Search (by serial number) for the end user who is attempting to enroll.

If the YubiKey is present in the YubiKey report, and the status is unassigned, the end user has potentially reprogrammed their Yubikey and overwritten the secrets associated with the Yubikey. This requires the admin to follow the instructions found in the Programming Yubikeys for Okta file, which can be found in Configuring Yubikey Tokens, and upload again into the Okta platform.

If the Yubikey is not present in YubiKey report, then the Yubikey secrets value has not been properly uploaded. The admin should follow the instructions found in Programming Yubikeys for Okta file (which can be found in Configuring Yubikey Tokens) for the device and upload again into the Okta platform.

Best Practice: If a Yubikey is decoupled from it's user, consider revoking the token from your system and reissuing the end user another unassigned Yubikey for enrollment.

Supported Yubico Devices

Okta supports the following Yubico hardware devices:

YubiKey Edge and Edge-N (Nano)

User-added image

YubiKey Edge and YubiKey Edge-N offer strong authentication using Yubico OTP with a tap of the device.


User-added image
YubiKey Neo has both contact (USB) and contact-less (NFC, MIFARE) communications. It supports OTP and smart card functionality.

Yubikey Neo-N (Nano)

User-added image

YubiKey Neo-N offers strong authentication via Yubico OTP with the touch of a button.