YubiKey (MFA)

A YubiKey is a brand of security key used as a physical multifactor authentication device. To use it, the user inserts the YubiKey into a USB port on their computer when they're signing in and taps the YubiKey's button when prompted. The YubiKey may provide a one-time password (OTP) or perform fingerprint (biometric) verification, depending on the type of YubiKey the user presents.

This topic provides instructions for setting up and managing the YubiKey using the OTP mode. To use the YubiKey for biometric verification, see FIDO2 (WebAuthn).

To use this multifactor authentication (MFA) factor, generate a CSV file of the YubiKey that you import using a tool from YubiKey's maker, Yubico. Then activate the YubiKey factor and import the CSV file. Users activate their YubiKey the next time they sign in to Okta.

Before you begin

Before you can enable the YubiKey factor, you need to configure the YubiKey and generate a YubiKey OTP Secrets file (also known as the YubiKey Seed File) using the YubiKey Personalization Tool. The YubiKey OTP secrets file is a CSV that you upload into Okta to activate the YubiKey. See Programming the YubiKey for Okta Adaptive Multifactor Authentication. After you generate the YubiKey OTP Secrets file, save it to a secure location.

After you configure the YubiKey and upload the YubiKey OTP secrets file to Okta, distribute the YubiKey to your end users.

Create a YubiKey configuration file

Before you can enable the YubiKey integration as a multifactor authentication option, obtain and upload a Configuration Secrets file generated through the YubiKey Personalization Tool. Find details on generating this file (which might also be called a YubiKey or Okta secrets file) in Programming the YubiKey for Okta Adaptive Multi-Factor Authentication.

The Configuration Secrets file is a CSV that allows you to provide authorized YubiKey to your org's end users. Yubico sends the requested number of "clean" hard tokens that you can distribute to your end users.

Be sure to read and follow the instructions found in Programming YubiKey for Okta Adaptive Multi-Factor Authentication carefully. Once completed, follow the steps under Uploading into the Okta Platform found in Using YubiKey Authentication in Okta.

Troubleshoot the Configuration Secrets file

If you encounter problems with generating your Configuration Secrets file or in configuring your YubiKey, verify that you've completed the following tasks.

• Select Configuration Slot 1. Each YubiKey is configured for the YubiCloud in Configuration Slot 1 by default. If you plan to use your YubiKey for services other than Okta, you can use Slot 2 for Okta configuration. However, if you're experiencing errors, it's a best practice to use Configuration Slot 1 exclusively for Okta.

• Click all three Generate buttons. Verify that you've clicked all three of the Generate buttons.

• Verify that the Public Identity value is in the generated OTP file. If the Public Identity value isn't present, the YubiKey isn't configured correctly.
  1. Open the CSV file that was generated by the YubiKey Personalization Tool.
  2. Note the Public Identity value listed as the second value item in the file.
  3. Open a text editor, then tap the YubiKey that was configured for use with Okta. Allow YubiKey to generate the OTP within the text editor.
  4. Search for the Public Identity value in the generated OTP. If it isn't present in the line of text, the YubiKey hasn't been successfully configured.

Activate the YubiKey factor and add the YubiKey

1. In the Admin Console, go to SecurityMultifactor.
2. Click YubiKey.
3. Click Browse, find the YubiKey Seed File that you created using the YubiKey Personalization Tool, and click Open.
4. Click Inactive and select Activate to enable the YubiKey factor.

View a list of assigned and unassigned YubiKey

After you add the YubiKeys, check the YubiKey report to verify that they're correct and view the status of each YubiKey.

1. In the Admin Console, go to SecurityAuthenticators.

2. In the Admin Console, go to SecurityMultifactor.

3. Select the Factor Types tab.
4. Select YubiKey.
5. Click View Report.
6. Use the criteria under the Filters pane to customize your search.
7. Review the status of each YubiKey in the Status column:
   • The status appears as UNASSIGNED until the end user enrolls their YubiKey.
   • Once the end user has enrolled their YubiKey, the status changes to ACTIVE.
   • When you revoke a YubiKey, the status changes to REVOKED.

Revoke the YubiKey

Revoking a YubiKey allows you to decommission a single YubiKey, such as when it has been reported as lost or stolen. In addition, revoking a YubiKey removes its association with the user to whom it was assigned.

1. In the Admin Console, go to SecurityMultifactor.

2. Select the Factor Types tab.
3. Select YubiKey.
4. Paste the serial number into the Revoke YubiKey Seed field and click Find YubiKey. Information about the YubiKey appears.
5. Click Revoke. The confirmation message appears.
6. Click Done.

Delete the YubiKey OTP factor

1. In the Admin Console, go to SecurityMultifactor.

2. Select YubiKey.
3. Click Active, then Deactivate.
4. The Delete YubiKey factor prompt appears.
5. Click Delete.

End-User experience

Enroll a YubiKey for the first time on a desktop browser

When the end user receives their newly provisioned YubiKey, they can activate it themselves by doing the following:

1. Sign in to Okta.
2. On the Set up factors page of the Sign-In Widget, click Set up under YubiKey. The Set up YubiKey page appears.
3. Insert the YubiKey and tap its button when prompted.
4. Click Verify. The Set up security methods page appears.
5. Click Finish.

Use YubiKey in OTP mode at subsequent desktop browser sign-ons

After the end user has activated their YubiKey for one-time passwords, they can use it for multifactor authentication at subsequent sign-ons:

1. Sign in to Okta.
2. When the Verify with YubiKey page appears, insert the YubiKey and tap its button when prompted.

Enrollment failure

If an end user is unable to enroll their YubiKey successfully, ensure that the token was successfully uploaded into the Okta platform. Review the YubiKey Report and search for the YubiKey's serial number for the end user who is attempting to enroll.

• If the YubiKey appears in the YubiKey Report, and the status is Unassigned, the user may have reprogrammed their YubiKey and overwritten the secrets associated with it. The admin must create another YubiKey Configuration Secrets file and upload it to Okta.
• If the YubiKey doesn't appear in the YubiKey Report, then you didn't properly upload the YubiKey secrets value. Upload it again into Okta.

Ensure that you've configured the appropriate YubiKey slot for the Okta configuration, and the end user is using the same slot to enroll their key in Okta.

Okta uses session counters with the YubiKey. Your current OTP invalidates all previous ones. However, these OTPs may still be valid for use on other websites.

Supported protocols and communication channels

Okta supports the following token modes:

• TOTP
• WebAuthn (FIDO2)