.. create-shipment.rst


.. _create-shipment:

=====================================
Creating Shipment Requests
=====================================

In this step you will add new users for shipments and create a shipment request. In order to make a shipment request, the following information is required for the user, either from the Okta Universal Directory (UD) or from your organization's HRIS (Human Resources Information System):

* First Name
* Last Name
* Street Address
* City
* State/Province/Territory (`2-letter format codes <https://docs.yubico.com/cloud-services/yubienterprise/delivery/Shipments.html#usps-codes-label>`_)
* Postal Code
* Country Code
* Primary email
* Secondary email (for onboarding *new* users to receive a PIN)
* Primary phone number
* Organization



.. _add-users:

Adding New Users to Directory
================================

The following describes how to add a *new* user with status “Staged” in Okta. For more information, see `Create staged user (Okta documentation) <https://help.okta.com/oie/en-us/content/topics/identity-engine/authenticators/pr-order-yubikeys.htm>`_.

To add a new user, do the following:

1. In the **Okta Admin** console, go to **Directory** > **People** and click **Add person**.

2. In the **Add Person** dialog, enter information as follows:

   * **First name**, **Last name**, and **Username**.

   * **Primary email** (work email) for active users.

   * **Secondary email** (personal email used prior to activation for new users). 
     
   * Do not assign the user to any YubiKey groups, this is done later. 
       
   * Set **Activation** to "Activate later". This creates the user in status "Staged".

3. Click **Save**.

4. On the **People** page, go to **Staged** > **User** > **Profile** > **Edit**.

5. Enter the following information required for key shipment: **Primary phone**, **Street address**, **City**, **State**, **Zip code**, **Country code**, and **Organization**.

6. Click **Save**.


Creating the Shipment Request
================================

You can create shipment requests either through the Okta Admin console using Okta Groups, or using the API for batch shipment requests, see :ref:`Integration Procedure <integration-steps>`. 

In this example we will use the **Pre-enrolled authenticators** option in the **Okta Workflows** console to create a shipment request.

.. note:: Only one FIDO Pre-reg YubiKey at a time can be requested for an Okta tenant. 

To create a shipment request, do the following:

1. In the **Okta Workflows** console, ensure the **Create shipment trigger - MFA initiated** flow is *enabled*. 

   .. note::  It is recommended that only one flow at a time be enabled: either the **Group Add** or the **MFA Initiated** flow. 

   .. image:: graphics/okta-mfa-trigger-2.png
      :width: 800

2. In the **Okta Admin** console, ensure the user to whom you want to ship the key has a profile in the user directory. If not, create a new user as described in :ref:`add-users`.

3. Click the profile of the desired user and do the following:

   * If using the Okta Universal Directory (UD) to source the shipping information, ensure this is populated in the user profile.
   * Alternatively, confirm the user's shipping information is being sourced from an HRIS or other source of truth.

4. In the user profile, click **Pre-enrolled authenticators** and then click **+ Add**.

   .. image:: graphics/okta-add-enroll.png
      :width: 600

5. On the **YubiKey enrollment and delivery** page, enter the **Product ID**, **Inventory ID**, and **Customization ID** provided by Yubico during onboarding. See :ref:`prerequisites`.

   .. image:: graphics/okta-enroll-ids.png
      :width: 600

6. On the **Yubikey enrollment and delivery** page, ensure all required fields are populated: Primary and secondary **Email address** (PIN will be sent to both), primary **Phone number**, **Organization**, and **Shipping address**.

   .. image:: graphics/okta-enroll-info.png
      :width: 800

7. If the user's shipping information is being sourced elsewhere, you will receive a message stating that it is missing. Ensure that the information is retrieved from another endpoint or update the profile values before continuing.

   .. image:: graphics/okta-details-missing.png
      :width: 400

8. Click **Continue**.

9. The Yubico FIDO Pre-reg workflow is triggered and the fulfillment starts. 

   .. image:: graphics/okta-fulfillment.png
      :width: 600

Yubico receives a request for a pre-registered YubiKey. The request contains all information needed to program and ship the key. When the request is fulfilled and the credential is activated by Okta, the randomly generated PIN associated with the YubiKey is emailed to the user’s secondary email address (new user). For existing users, it will be sent to their primary email address.

.. _activate-users:

.. note:: Once the credential is programmed onto the YubiKey, the challenge and credential data, including PIN, is purged from Yubico systems.