Order pre-enrolled YubiKey security keys

This procedure explains how to order pre-enrolled YubiKey security keys for your users.

You can use Okta Universal Directory or an external human resource information system (HRIS) app like ServiceNow or Workday as the source of the shipment information for your order. Update the user's shipping address in the source system, and then order a YubiKey for them.

Before you begin

Verify that you've completed these tasks before you perform this procedure:

  1. Set up FIDO2 (WebAuthn) authenticator and phishing-resistant policies.
  2. Set up Okta Workflows for YubiKey shipment.
  3. Gather the following YubiKey information:
    • Product IDs
    • Inventory product IDs
    • Customization IDs

    See Product and Inventory Identifiers and YubiKey documentation for Customization IDs.

See Require phishing-resistant authentication with pre-enrolled YubiKey.

Create a staged user

If the user doesn't exist in Okta, create them in the Staged status.

  1. Add users manually.
  2. Enter the following user details:
    • User type
    • First name
    • Last name
    • Username
    • Primary email
    • Secondary email: Enter the user's secondary email. This is where you send the YubiKey PIN.
    • Groups: Assign the user to the users group that you created in Set up FIDO2 (WebAuthn) authenticator and phishing-resistant policies.
    • Activation: Select Activate later. This creates the user in the Staged status.

Assign an active user to a group

If the user's status is Active in Okta, assign them to the group that you created in Set up FIDO2 (WebAuthn) authenticator and phishing-resistant policies.

  1. In the Admin Console, go to DirectoryPeople.

  2. Go to UserGroups.
  3. Add the user to the group.

Update the user's shipping information

If you source users with a Staged or Active status from Universal Directory, update their shipping address in Okta. Otherwise, update it in your HRIS.

  1. On the People page, go to User Profile Edit.
  2. Ensure that the following details appear in the user profile. These details are required for shipping the YubiKey:
    • Secondary email: This email address is required for all users with a Staged or Active status who have never signed in to their account.
    • Primary phone
    • Street address
    • City
    • State
    • Zip code
    • Country code
    • Organization
  3. Click Save.

Order a YubiKey for an individual user

Complete this task for individual users with a Staged or Active status.

  1. Go to PeopleUserPre-enrolled authenticators.
  2. In the Security Key section, click Add a pre-enrolled security key.
  3. On the YubiKey enrollment and delivery page, enter the following security key details:
    • Product ID
    • Inventory Product ID
    • Customization ID
  4. In the Security key delivery section, verify that the user's information is correct. If you need to change this information, update it in the user's profile in either Universal Directory or the HRIS.
  5. Click Submit. The pre-enrolled YubiKey appears under the user's Security Key section along with its shipment status.

This event triggers the Okta Workflows template that you set up in Set up Okta Workflows for YubiKey shipment to initiate the YubiKey shipment.

Order pre-enrolled YubiKeys in a batch

Use the Okta API to order YubiKeys for a batch of users.

  1. Import users into Okta.
  2. Update their user profiles in Universal Directory to include the information required for the YubiKey shipment. If this information is sourced from an HRIS, update it there. Ensure that it's mapped correctly to the users' profiles in Okta. See Manage profiles.
  3. The following is a list of the user details required for shipping the YubiKey:
    • Secondary email: This email address is required for all users with a Staged or Active status who have never signed in to their account.
    • Primary phone
    • Street address
    • City
    • State
    • Zip code
    • Country code
    • Organization
  4. Get the product IDs and inventory product IDs for the YubiKey types that you want to order. See Product and Inventory Identifiers.
  5. Get the customization IDs for the YubiKey types that you want to order. See YubiKey documentation.
  6. Use the following endpoint and request to create a shipment batch. Call this endpoint for each Okta user ID.
    • Endpoint: POST /webauthn-registration/api/v1/initiate-fulfillment-request

    • Request:

      Copy
      {
        "userId": "${oktaUserId}",
        "fulfillmentProvider": "yubico",
        "fulfillmentData": [
          {
            "productId": "${productId}",
            "customizationId": "${customizationId}",
            "inventoryProductId": "${inventoryProductId}"
          }
        ]
      }

    This event triggers the Create shipment trigger- MFA Initiated app event in Okta Workflows and assigns the YubiKey to the user. It uses the parameters that you specified for each user ID in the request. This flow generates a list of fulfillment data and sends it to Yubico for shipments through the Create Shipment flow.

Request parameters

The API Endpoint request uses the following parameters.

Parameter

Description

Param Type

Data Type

Required

userId

The user ID in Okta.

Body

String

TRUE

fulfillmentProvider

The name of the shipment fulfillment provider (yubico).

Body

String

TRUE

fulfillmentData

The details of the YubiKey to be assigned to the user.

Body

Array

TRUE

productId

The product ID of the YubiKey to be assigned to the user.

Body

String

TRUE

customizationId

The customization ID of the YubiKey to be assigned to the user.

Body

String

TRUE

inventoryProductId

The inventory Product ID of the YubiKey to be assigned to the user.

Body

String

TRUE

Admin experience after the shipment is triggered

Whenever a shipment event is triggered in Okta Workflows, an event is also registered in your Yubico console. The YubiKey PIN is sent to the user when the key is activated. Resend the PIN by clicking Send PIN next to the key number.

You can't enroll a new security key for a user until the existing key shipment is fulfilled. If you want to enroll another security key at this stage, first delete the existing security key shipment and cancel the key fulfillment process in the Yubico console. When you delete this YubiKey, the key enrollment and user credentials are deleted permanently.

The YubiKey can have one of the following statuses:

  • Fulfillment started: Okta has started the enrollment and fulfillment flow with Yubico.
  • Fulfillment errored: An error occurred during the fulfillment process. Check the Okta Workflows flowpack execution history for details. This could be a temporary error. Revising the existing fulfillment flow and retrying the process at the point of failure may resolve the issue.
  • Shipped: Yubico notified Okta that the key is set up and has shipped. The key hasn't been used yet. The PIN is available and can be sent to the user.
  • Active: The key has been used to sign in to Okta. The PIN stored in Okta has been cleared.

Next step

User experience