Order pre-enrolled YubiKeys

Early Access release. See Enable self-service features.

This procedure explains how to order pre-enrolled YubiKeys for new and existing users either individually or in a batch.

The information required for the YubiKey shipment is either sourced from Okta Universal Directory or an external HRIS (Human Resource Information System) app such as ServiceNow or Workday. Update the user's shipment information in the source and then order a YubiKey for them.

Before you begin

The final part of the journey to Require phishing-resistant authentication with pre-enrolled YubiKey contains tasks that you complete in the Admin Console. Complete each of the following task in order, and then go to the next step.

  1. Set up FIDO2 (WebAuthn) authenticator and phishing-resistant policies
  2. Set up Okta Workflows for YubiKey shipment

Have the Product IDs, Inventory Product IDs, and Customization IDs for YubiKeys handy. See YubiKey documentation for Product and Inventory Product IDs and YubiKey documentation for Customization IDs.

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 required user details:
    • User type
    • First name
    • Last name
    • Username
    • Primary email
    • Secondary email: Enter the user's secondary email where you want to send the YubiKey PIN.
    • Groups: Assign the user to the new 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.

Update group assignment for Active user

If the user is already Active in Okta, assign them to the existing users group you created in Set up FIDO2 (WebAuthn) authenticator and phishing-resistant policies.

  1. In the Admin Console, go to DirectoryPeople.

  2. Go to User Groups.
  3. Add the user to the existing users group.

Update the user's shipping information

If the Staged or Active user is sourced from Universal Directory, update their shipping information.

  1. On the People page, go to the User Profile Edit.
  2. Ensure the user profile has the following the user details required for shipping the YubiKey:
    • Secondary email: Required for all Staged users and the Active users who have never signed into their account.
    • Primary phone
    • Street address
    • City
    • State
    • Zip code
    • Country code
    • Organization
  3. Click Save.

If the user is sourced from an HRIS, update the shipping information there.

Order a YubiKey for an individual user

Complete this task for individual Staged or Active users.

  1. Go to People User Pre-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, confirm 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 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

You can use the Okta API to order YubiKeys for a batch of users.

  1. Import users in Okta.
  2. Update their user profiles in Universal Directory to include the information required for the YubiKey shipment.
  3. If this information is sourced from the HRIS, update it there. Ensure it's mapped correctly to the users' profiles in Okta. See Manage profiles.
  4. The following the user details required for shipping the YubiKey:
    • Secondary email: Required for all Staged users and the Active users who have never signed into their account.
    • Primary phone
    • Street address
    • City
    • State
    • Zip code
    • Country code
    • Organization
  5. Get Product IDs and Inventory Product IDs for YubiKeys. See YubiKey documentation.
  6. Get the Customization IDs for YubiKeys. See YubiKey documentation.
  7. Use the following endpoint and request to create a batch of shipment. You need to make a call to this API 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. Based on the parameters you've specified for each user ID in the request, the user is assigned the appropriate YubiKey. 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

User's ID in Okta

Body

String

TRUE

fulfillmentProvider

Name of the shipment fulfillment provider. It's yubico in this case.

Body

String

TRUE

fulfillmentData

List of details of the YubiKey to be assigned to the user

Body

Array

TRUE

productId

Product ID of the YubiKey to be assigned to the user

Body

String

TRUE

customizationId

Customization ID of the YubiKey to be assigned to the user

Body

String

TRUE

inventoryProductId

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 once the key is activated. You can also resend the PIN by clicking Send PIN next to the key.

You can't enroll a new security key for the user until the existing key shipment is fulfilled. If you want to add a new 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 the YubiKey, the key enrollment and credentials for the user are also deleted permanently.

The YubiKey can have one of the following statuses.

  • Fulfillment started: Okta has initiated the enrollment and the fulfillment flow with Yubico is triggered.
  • 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: Okta received information from Yubico that the key is set up and shipped. The key hasn't been used yet. At this point, the PIN is available and can be resent to the user.
  • Active: The key has been used to sign in to Okta. The PIN stored in Okta is wiped.

Next step

User experience