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.
Workflow: IT Admin and End User
- 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.
- The IT admin receives updates based on the shipping status, and can monitor shipments of pre-registered keys using the YubiEnterprise Console.
- 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.
- 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
- The IT admin initiates a shipment request for a pre-registered YubiKey from the Okta tenant.
- 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.
- 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.
- 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.
- 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
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.
| 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
and Signing Certificate
|
Pull the current public Yubico transport
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 Configuring Workflow Connections.
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 Generating an Authorization Token.
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
| Field | Definition | Type | Req’d |
|---|---|---|---|
| Company | Company name of shipment recipient | Text | TRUE |
| 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
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.
|
Text | TRUE |
| Address | Street address of shipment recipient
Note: This field can also include the
apartment or unit number.
|
Text | TRUE |
Apt or Unit
Number
|
The apartment or suite or unit number
or designation of shipment recipient.
|
Text | FALSE |
| City | City of shipment recipient | Text | TRUE |
| Region | 2-letter region or state code of
shipment recipient. Mandatory for
recipients in the US or Canada.
|
Text | FALSE |
| Postal Code | Zip code or postal code of shipment
recipient.
|
Text | TRUE |
| Country Code | 2-letter ISO country code of shipment
recipient.
|
Text | TRUE |
List of
Shipment
Items
|
List of items and their configuration
details, to be included in this
shipment.
Note: Use the Get Shipment Details
action card to construct this object.
|
List of
objects
|
TRUE
|
Customization
ID
|
ID associated with
the specific Yubico customization
assigned to an organization.
|
Text | TRUE |
Product ID
|
ID for the YubiKey model.
|
Number | TRUE |
Inventory
Product ID
|
ID for the “bucket”
containing credits for YubiKey
ordering.
Note: This is not to be confused with
the serial number on each YubiKey.
|
Number | TRUE |
Quantity
|
Number of keys to include in
this shipment (current limit is 1).
|
Number | TRUE |
PIN Request -
Encrypted
|
Customization options for YubiKey
PIN generation, wrapped as
a JWE string.
This string is the output provided by
Okta’s WebAuthn pre-registration
enroll endpoint.
|
Text | TRUE |
Credential
Requests
|
PublicKeyCredentialCreationOptions for
WebAuthn credential creation, wrapped
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.
|
List of
strings
|
TRUE |
Delivery
Type
|
Type of delivery to be used for the
request. If unspecified, its default
is standard.
- 1 (Standard)
- 2 (Expedited)
|
Number | FALSE |
Output - Create Shipment Request
| Field | Definition | Type |
|---|---|---|
| Shipment ID | The shipment ID of the newly created
shipment.
Value is null for non-successful API
response.
|
Text |
| Shipment State ID | The shipment state of the newly created
shipment. For values, see Shipment State
Codes.
Value is null for non-successful API
responses.
|
Number |
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
| Field | Definition | Type | Req’d |
|---|---|---|---|
| Shipment ID | ID for a specific shipment. | Text | TRUE |
Output - Getting Shipment Details
| Field | Definition | Type |
|---|---|---|
| Shipment State ID | The shipment state of the newly created
shipment. For values, see Shipment Status
Codes in the YubiEnterprise Services
User Guide.
Value is null for non-successful API
responses
|
Number |
| Shipment Items | List of items included in the shipment.
Underlying objects include details for
each item.
|
List of
objects
|
product_data: Details about a shipment
item. Includes:
- serial
- version
- fido_pin_response
- fido_credential_response
|
List of
objects
|
|
serial: Serial number of the item
|
Text | |
version: Firmware version of the item
|
Text | |
fido_pin_response: PIN for the item. Is
encrypted as a JWE string.
This string should be provided to Okta’s
WebAuthn pre-registration activate
endpoint.
|
Text | |
fido_credential_response: List of FIDO
credentials for the item. Is encrypted as
a JWE string.
This string should be provided to Okta’s
WebAuthn pre-registration activate
endpoint.
|
List of
strings
|
|
product_id: ID for the YubiKey model.
|
Number | |
inventory_product_id: ID for the “bucket”
containing credits for YubiKey ordering.
Note: This is not to be confused with the
serial number on each YubiKey.
|
Number | |
product_quantity: Number of YubiKeys to
include in this shipment
(current limit is 1).
|
Number |
Action: Build Shipment Item
Action card that builds a shipment item used in the Create shipment request action card.
Input - Build Shipment Item
| Field | Definition | Type | Req’d |
|---|---|---|---|
| Customization ID | ID associated with the specific
Yubico customization assigned to an
organization.
|
Text | TRUE |
| Product ID | ID associated with the specific
YubiKey format.
|
Number | TRUE |
Inventory
Product ID
|
ID for the “bucket” containing credits
for YubiKey ordering.
|
Number | TRUE |
| Quantity | Number of keys to include in this
shipment (current limitation is 1).
|
Number | TRUE |
PIN Request
- Encrypted
|
Customization options for YubiKey PIN
generation, wrapped as a JWE string.
This string is the output provided by
Okta’s WebAuthn pre-registration enroll
endpoint.
|
Text | TRUE |
Credential
Requests -
Encrypted
|
PublicKeyCredentialCreationOptions for
WebAuthn credential creation, wrapped
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.
|
List of
strings
|
TRUE |
Output - Build Shipment Items
| 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
| Field | Definition | Type |
|---|---|---|
Transport Keys -
JWKS
|
Yubico JWKS (JSON Web Key Set) used for
deriving an ECDH shared secret.
Primarily used for encrypting the PIN and
credential requests for the
YubiEnterprise API.
|
Object |
Signing Public
Keys - JWKS
|
Yubico JWKS (JSON Web Key Set) containing
signing certificates used for signing PIN
and credential responses from the
YubiEnterprise API.
|
Object |