.. about-fpr-okta.rst ===================================== About Yubico FIDO Pre-reg with Okta ===================================== The Yubico FIDO Pre-reg integration streamlines the deployment process with improved ease of use and enhanced security. The diagram below illustrates the process. The Yubico FIDO Pre-reg template developed specifically for Okta Workflows in this case, helps orchestrate the process steps. The Yubico Connector and the Yubico FIDO Pre-reg Workflow templates are both integrated with the Okta Workflows console. Process Flow ================ The workflows are designed to ensure each request via Okta to Yubico contains all information needed to have the keys shipped to the end user. A secure and encrypted transfer process mitigates any risk of exposing sensitive information. .. image:: /graphics/workflow-okta-enduser1.png :width: 800 **Workflow: IT Admin and End User** 1. The IT admin initiates a shipment request for a pre-registered key from the IDP (Okta) tenant. This triggers the Yubico FIDO Pre-reg Okta Workflows template. All information needed to program and ship a key for an individual user is sent to Yubico through a YubiEnterprise Delivery API request. Note that only one key per shipment can be requested. 2. The IT admin receives updates based on the shipping status, and can monitor shipments of pre-registered keys using the YubiEnterprise Console. 3. The end user receives an email containing their YubiKey PIN and their FIDO Pre-reg YubiKey is shipped to them directly. No IDP password or IDP registration is required. The YubiKey PIN is only communicated to the end user and is encrypted and obscured from Okta, the IT admin, and Yubico. 4. The end user can immediately use the YubiKey and PIN to authenticate into Okta where they have Single Sign-On (SSO) access to applications to which they have access provided through the Okta. **Workflow: Credential and PIN Provisioning** 1. The IT admin initiates a shipment request for a pre-registered YubiKey from the Okta tenant. 2. Yubico receives the shipment request from Okta through the YubiEnterprise API. Yubico programs a YubiKey with the information provided in the request. The information contains the credential and PIN requests, end user shipping information, and YubiKey form factor. 3. After the YubiKey is programmed, a response is sent back to the YubiEnterprise API including the randomly generated PIN, serial number, and firmware version. This response is retrieved by the Okta workflows. 4. When the Okta workflows receive the response from the YubiEnterprise API, the YubiKey is enabled for usage. This triggers an email to the end user containing the PIN for the YubiKey. 5. After the programming of the YubiKey the credential data, including the PIN, is purged from Yubico systems. Additionally, the YubiKey can be used as a recovery tool for the IDP’s complementary passwordless feature such as Okta FastPass. For example, if an end user loses their phone and gets a replacement one, they can re-enroll in the IDP service using the YubiKey without needing to call their support services. .. _workflow-integration: Workflow integration ====================== The following describes the integration between the Yubico Connector in Okta and the Okta Workflows. The integration provides the Yubico action cards used to set up the workflows in Okta for requesting shipments and retrieving shipment information. The Yubico workflow integration includes the action cards described below. .. table:: +----------------------------+----------------------------------------------+ | Action | Description | +============================+==============================================+ | Create Shipment Request || Create a new shipment request to provision | | || a YubiKey that will contain a pre-registered| | || WebAuthn credential. | +----------------------------+----------------------------------------------+ | Get Shipment Details || Get details about a specific shipment | | || request, including the shipment state, and | | || shipment items used for the pre-registration| | || of a WebAuthn credential. | +----------------------------+----------------------------------------------+ | Build Shipment Item || Helper action card that builds a “shipment | | || item” used in the “Create shipment request” | | || action card. | +----------------------------+----------------------------------------------+ || Get Public Transport Keys || Pull the current public Yubico transport | || and Signing Certificate  || and signing keys used to encrypt the PIN | || || and credential request payloads. | +----------------------------+----------------------------------------------+ The input and output parameters for each action card are described in more detail in the following. For more information, see :ref:`configure-workflow-connect`. When you add a Yubico card to a flow for the first time, you will be prompted to authorize the connection. This requires an API token generated from the YubiEnterprise Console. Once you have configured this connection and saved the API token information to it, you can reuse the connection for other YubiEnterprise-related actions. For more information, see :ref:`connection-authorize`. Action: Create Shipment Request ---------------------------------- Action card to create a new shipment request to provision a YubiKey that contains a pre-registered WebAuthn credential. .. note:: Product ID and Inventory Product list can be found in the `Product inventory type mapping table `_. **Input - Create Shipment Request** .. table:: +----------------+-----------------------------------------+---------+-------+ | Field | Definition | Type | Req'd | +================+=========================================+=========+=======+ | Company | Company name of shipment recipient | Text | TRUE | +----------------+-----------------------------------------+---------+-------+ | Email | Email address of shipment recipient | Text | FALSE | +----------------+-----------------------------------------+---------+-------+ | First Name | First name of shipment recipient | Text | FALSE | +----------------+-----------------------------------------+---------+-------+ | Last Name | Last name of shipment recipient | Text | FALSE | +----------------+-----------------------------------------+---------+-------+ | Phone Number || Telephone number of shipment recipient | Text | TRUE | | || | | | | || The limit is 40 of the alphanumeric | | | | || characters “0-9+-( )” unless the | | | | || country code is IN, in which case | | | | || the limit is 255. | | | | || | | | | || Any format is acceptable, with or | | | | || without spaces. | | | +----------------+-----------------------------------------+---------+-------+ | Address || Street address of shipment recipient | Text | TRUE | | || | | | | || Note: This field can also include the | | | | || apartment or unit number. | | | +----------------+-----------------------------------------+---------+-------+ || Apt or Unit || The apartment or suite or unit number | Text | FALSE | || Number || or designation of shipment recipient. | | | +----------------+-----------------------------------------+---------+-------+ | City | City of shipment recipient | Text | TRUE | +----------------+-----------------------------------------+---------+-------+ | Region || 2-letter region or state code of | Text | FALSE | | || shipment recipient. Mandatory for | | | | || recipients in the US or Canada. | | | +----------------+-----------------------------------------+---------+-------+ | Postal Code || Zip code or postal code of shipment | Text | TRUE | | || recipient. | | | +----------------+-----------------------------------------+---------+-------+ | Country Code || 2-letter ISO country code of shipment | Text | TRUE | | || recipient. | | | +----------------+-----------------------------------------+---------+-------+ || List of || List of items and their configuration || List of|| TRUE | || Shipment || details, to be included in this || objects|| | || Items || shipment.   || || | || || Note: Use the Get Shipment Details || || | || || action card to construct this object. || || | +----------------+-----------------------------------------+---------+-------+ || Customization || ID associated with | Text | TRUE | || ID || the specific Yubico customization | | | || || assigned to an organization. | | | +----------------+-----------------------------------------+---------+-------+ || Product ID || ID for the YubiKey model. | Number | TRUE | +----------------+-----------------------------------------+---------+-------+ || Inventory || ID for the "bucket" | Number | TRUE | || Product ID || containing credits for YubiKey | | | | || ordering. | | | | || Note: This is not to be confused with | | | | || the serial number on each YubiKey. | | | +----------------+-----------------------------------------+---------+-------+ || Quantity || Number of keys to include in | Number | TRUE | | || this shipment (current limit is 1). | | | +----------------+-----------------------------------------+---------+-------+ || PIN Request - || Customization options for YubiKey | Text | TRUE | || Encrypted || PIN generation, wrapped as | | | | || a JWE string. | | | | || | | | | || This string is the output provided by | | | | || Okta’s WebAuthn pre-registration | | | | || enroll endpoint. | | | +----------------+-----------------------------------------+---------+-------+ || Credential || PublicKeyCredentialCreationOptions for || List of| TRUE | || Requests || WebAuthn credential creation, wrapped || strings| | | || as a JWE string. || | | | || || | | | || This string is the output provided by || | | | || Okta’s WebAuthn pre-registration || | | | || enroll endpoint. || | | | || || | | | || Note: This input item is noted as a || | | | || list. This is due to || | | | || YubiEnterprise’s API schema, which can || | | | || accept a list of credential requests || | | | || for provisioning multiple pre- || | | | || registered WebAuthn credentials. || | | +----------------+-----------------------------------------+---------+-------+ || Delivery || Type of delivery to be used for the | Number | FALSE | || Type || request. If unspecified, its default | | | || || is standard. | | | || || | | | || || - 1 (Standard) | | | || || - 2 (Expedited) | | | +----------------+-----------------------------------------+---------+-------+ **Output - Create Shipment Request** .. table:: +-------------------+---------------------------------------------+--------+ | Field | Definition | Type | +===================+=============================================+========+ | Shipment ID || The shipment ID of the newly created | Text | | || shipment. | | | || | | | || Value is null for non-successful API | | | || response. | | +-------------------+---------------------------------------------+--------+ | Shipment State ID || The shipment state of the newly created | Number | | || shipment. For values, see Shipment State | | | || Codes. | | | || | | | || Value is null for non-successful API | | | || responses. | | +-------------------+---------------------------------------------+--------+ Action: Get Shipment Details ---------------------------------- Action card to get details about a specific shipment including the shipment state and the shipment items used for the pre-registration of a WebAuthn credential. **Input - Get Shipment Details** .. table:: +--------------+-----------------------------------------+---------+-------+ | Field | Definition | Type | Req'd | +==============+=========================================+=========+=======+ | Shipment ID |ID for a specific shipment. | Text | TRUE | +--------------+-----------------------------------------+---------+-------+ **Output - Getting Shipment Details** .. table:: +-------------------+---------------------------------------------+---------+ | Field | Definition | Type | +===================+=============================================+=========+ | Shipment State ID || The shipment state of the newly created | Number | | || shipment. For values, see Shipment Status | | | || Codes in the YubiEnterprise Services | | | || User Guide. | | | || Value is null for non-successful API | | | || responses | | +-------------------+---------------------------------------------+---------+ | Shipment Items || List of items included in the shipment. || List of| | || Underlying objects include details for || objects| | || each item. || | +-------------------+---------------------------------------------+---------+ | || product_data: Details about a shipment || List of| | || item. Includes: || objects| | || - serial || | | || - version || | | || - fido_pin_response || | | || - fido_credential_response || | +-------------------+---------------------------------------------+---------+ | || serial: Serial number of the item | Text | +-------------------+---------------------------------------------+---------+ | || version: Firmware version of the item | Text | +-------------------+---------------------------------------------+---------+ | || fido_pin_response: PIN for the item. Is | Text | | || encrypted as a JWE string. | | | || | | | || This string should be provided to Okta’s | | | || WebAuthn pre-registration activate | | | || endpoint. | | +-------------------+---------------------------------------------+---------+ | || fido_credential_response: List of FIDO || List of| | || credentials for the item. Is encrypted as || strings| | || a JWE string. || | | || || | | || This string should be provided to Okta’s || | | || WebAuthn pre-registration activate || | | || endpoint. || | +-------------------+---------------------------------------------+---------+ | || product_id: ID for the YubiKey model. | Number | +-------------------+---------------------------------------------+---------+ | || inventory_product_id: ID for the "bucket" | Number | | || containing credits for YubiKey ordering. | | | || Note: This is not to be confused with the | | | || serial number on each YubiKey. | | +-------------------+---------------------------------------------+---------+ | || product_quantity: Number of YubiKeys to | Number | | || include in this shipment | | | || (current limit is 1). | | +-------------------+---------------------------------------------+---------+ Action: Build Shipment Item ---------------------------------- Action card that builds a ``shipment item`` used in the ``Create shipment request`` action card.  **Input - Build Shipment Item** .. table:: +--------------+-----------------------------------------+---------+-------+ | Field | Definition | Type | Req'd | +==============+=========================================+=========+=======+ | Customization|| ID associated with the specific | Text | TRUE | | ID || Yubico customization assigned to an | | | | || organization. | | | +--------------+-----------------------------------------+---------+-------+ | Product ID || ID associated with the specific | Number | TRUE | | || YubiKey format. | | | +--------------+-----------------------------------------+---------+-------+ || Inventory || ID for the “bucket” containing credits | Number | TRUE | || Product ID || for YubiKey ordering. | | | +--------------+-----------------------------------------+---------+-------+ | Quantity || Number of keys to include in this | Number | TRUE | | || shipment (current limitation is 1). | | | +--------------+-----------------------------------------+---------+-------+ || PIN Request || Customization options for YubiKey PIN | Text | TRUE | || - Encrypted || generation, wrapped as a JWE string. | | | || || This string is the output provided by | | | || || Okta’s WebAuthn pre-registration enroll| | | || || endpoint. | | | +--------------+-----------------------------------------+---------+-------+ || Credential || PublicKeyCredentialCreationOptions for || List of| TRUE | || Requests - || WebAuthn credential creation, wrapped || strings| | || Encrypted || as a JWE string. || | | || || || | | || || This string is the output provided by || | | || || Okta’s WebAuthn pre-registration enroll|| | | || || endpoint. || | | || || || | | || || Note: This input item is noted as a || | | || || as list. This is due to || | | || || YubiEnterprise’s API schema, which can || | | || || accept a list of credential requests || | | || || for provisioning multiple || | | || || pre-registered WebAuthn credentials. || | | +--------------+-----------------------------------------+---------+-------+ **Output - Build Shipment Items** .. table:: +-------------------+---------------------------------------------+--------+ | Field | Definition | Type | +===================+=============================================+========+ | Shipment Item || Object that contains configuration details | | | || for an item to include in a shipment. | Object | +-------------------+---------------------------------------------+--------+ Action: Get Public Transport Keys and Signing Certificate ------------------------------------------------------------ Action card to pull the current public Yubico transport and signing keys used to encrypt the PIN and credential request payloads. **Input - Get Public Transport Keys and Signing Certificate** No input required. **Output - Get Public Transport Keys and Signing Certificate** .. table:: +-------------------+---------------------------------------------+--------+ | Field | Definition | Type | +===================+=============================================+========+ || Transport Keys - || Yubico JWKS (JSON Web Key Set) used for | Object | || JWKS || deriving an ECDH shared secret. | | || || Primarily used for encrypting the PIN and | | || || credential requests for the | | || || YubiEnterprise API.  | | +-------------------+---------------------------------------------+--------+ || Signing Public || Yubico JWKS (JSON Web Key Set) containing | Object | || Keys - JWKS || signing certificates used for signing PIN | | || || and credential responses from the | | || || YubiEnterprise API. | | +-------------------+---------------------------------------------+--------+