YubiKey (MFA)

Using their USB connector, end users press on the YubiKey hard token to emit a new, one-time password to securely log into their accounts. Security is assured, as all YubiKey validation occurs within the Okta Cloud.

About YubiKey

Produced by Yubico, a YubiKey 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.

Info

Note

The steps in this section pertain to YubiKey in OTP mode. YubiKey also supports U2F and depending on the key series, WebAuthn (MFA).

To specify YubiKey for authentication, the only task is to upload the YubiKey seed file, also known as the Configuration Secrets file. To create this file, follow the instructions below. Once uploaded, the screen verifies the number of successfully uploaded YubiKeys, and lists any errors that occurred in the process.

Create a YubiKey configuration file

Before you can enable the YubiKey integration as a multifactor authentication option, you need to 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) from Programming YubiKeys for Okta Adaptive Multi-Factor Authentication.

The Configuration Secrets file is a .csv that allows you to provide authorized YubiKeys to your org's end users. Yubico sends the requested number of "clean" hard tokens which, once setup is complete, you can distribute to your end users.

Be sure to read and follow the instructions found in Programming YubiKeys for Okta document very carefully. Once completed, follow the steps under Uploading into the Okta Platform found in Using YubiKey Authentication in Okta.

With purchase of the YubiKeys, Yubico offers an additional premium service to create a secrets file on your behalf. Contact Yubico for details on this option.

Troubleshooting

If you encounter problems with generating your Configuration Secrets file or in configuring your YubiKeys, verify that you've satisfied the following questions and steps below.

Did you select Configuration Slot 1?

  • Each YubiKey is configured for the YubiCloud in Configuration Slot 1 by default. If you plan to use your YubiKeys 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.

Did you click the three Generate buttons?

  • When going through the steps for configuring your YubiKeys, verify that you have clicked all three of the Generate buttons.

Did you check your Generated OTP?

  • An important step in checking your work is noting that the Public Identity value exists in your generated OTP. If it is not present, your YubiKey is not correctly configured.

  • To check the file, do the following:

    1. Open the .csv file 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 on the YubiKey that was configured for use with Okta. Allow YubiKey to generate the OTP within the text editor.
    4. Search for the aforementioned Public Identity value in the generated OTP. If it is not present in the line of text, the YubiKey has not been successfully configured.

Using a YubiKey

Token management

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.

View a list of assigned and unassigned YubiKeys

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

A report can be run at any time to view:

  • Active tokens (YubiKeys which are associated with users.)
  • Blocked tokens (YubiKeys which were once active, but are now either reset by the end user or the Okta admin.)
  • Unassigned tokens (An unassigned YubiKey has secret values uploaded and is ready to be self enrolled by an end user.)
  • Names of assigned end users

Remove a lost, stolen, or invalid YubiKey

  • A user can be unauthorized from a YubiKey hard token if the token is lost or stolen.
  • A token is non-transferable and may be replaced. If an end user reports a lost or stolen YubiKey, unassign the token based on its unique serial number by using the same method to remove an unassigned YubiKey.
  • For auditing purposes, a YubiKey cannot be deleted once assigned to a user. Even if it has been revoked or reassigned, it will remain in the report when generated.
  • A YubiKey must be deleted and re-uploaded to be reassigned to a user.

  • A YubiKey that has not been assigned to a user may be deleted.
  • A YubiKey serial cannot 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.
  3. A Delete YubiKey modal appears to verify that you wish to permanently delete the YubiKey.
  4. 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.

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.

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

Enrollment failure

If an end user is unable to enroll their YubiKey successfully, ensure that the token was successfully uploaded into the Okta platform. Navigate to the YubiKey Report found on the Reports page. 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 and must be uploaded again into the Okta platform.

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

Supported protocols and communication channels

For successful YubiKey authentication, the following token modes are supported:

  • TOTP
  • U2F (Requires Chrome or Firefox web browsers)
  • FIDO2
Info

Note

Some YubiKey models may support protocols such as NFC. Okta Mobile and web browsers running on iOS do not currently support NFC. Please refer to the YubiKey device specifications to confirm the level of support.