How it Works

With FIDO Pre-reg the IT administrator (IT admin) for an organization can use the YubiEnterprise API together with the WebAuthn API of an Identity Provider (IdP) and automated workflows to order pre-enrolled YubiKeys for end users. The YubiKeys are pre-enrolled and shipped directly to the specific end user who received a randomly generated PIN separately.

The following sections describe how to integrate FIDO Pre-reg with PingOne PingID/Ping AIC. The instructions are intended for IT admins who are setting up shipments of pre-enrolled YubiKeys for their organization’s end users in an environment using PingOne PingID/Ping AIC as IdP.

The instructions assume you have IT administration skills and knowledge of the YubiEnterprise API, Microsoft Azure, and PingOne PingID/Ping AIC. Listed tasks include steps performed both in the Customer Portal, Microsoft Azure, and PingOne PingID/Ping AIC. Refer to the PingOne PingID/Ping AIC documentation for more details.

Process Flow

The image below provides an example of a customer environment setup using Microsoft Azure components and PingOne PingID or PingOne AIC as IdP.

The following steps illustrate the pre-enrolled end-to-end credential/YubiKey delivery flow:

An authorized user (or process) triggers a request for a credential/YubiKey for a PingOne PingID/AIC end user via processes and workflows in the customer orchestration environment. The shipping address for the targeted end user is retrieved from supporting systems.
The YubiKey request is received by the FIDO Connector deployed in the customer environment.
The FIDO Connector makes a request to PingOne PingID/AIC to obtain the required credential creation parameters. When using PingOne AIC, the FIDO Connector calls the PingOne AIC Journey API to initiate the enrollment process and obtain the credential creation parameters.
PingOne PingID/AIC returns the credential creation parameters for the targeted end user to the FIDO Connector which then encrypts the information as a credential request.
If the Yubico Delivery service is used, the FIDO Connector creates a shipment request to the Delivery service, including the model and shipping information, and attaches the encrypted credential request.
After passing through the Delivery service, the FIDO Connector decrypts the credential request and creates the credential (user private key) for the specified YubiKey model. The private key is stored in Azure Key Vault.
The attestation response from the credential creation along with the PIN are then encrypted.
Yubico ships the YubiKey to the targeted end user. Once the shipment is created, the Yubico APIs return a Shipment ID which is store in the Azure Table Storage.
The FIDO Connector continuously checks the Delivery service for updated shipment status.
When the shipment reaches status “Shipped” in the Delivery service, the FIDO Connector captures the shipping information including tracking number, serial number, firmware version, and encrypted credential response which includes the PIN.
The credentials and the PIN are decrypted by the FIDO Connector, and registered in PingOne PingID, or with PingOne AIC using the Journey API.
The PIN is communicated to the targeted end user through a preferred delivery method, for example in an email triggered in the Azure Logic App.
The end user authenticates to PingOne PingID or PingOne AIC using their YubiKey and the provided PIN. If the PIN was configured for one-time use, the user will be prompted to change the PIN.

The following sections provide an overview of solution features and components.

Customer Environment

The customer environment contains the orchestration components needed to support the FIDO Pre-reg processes for requesting enrollment credentials and shipment of pre-enrolled YubiKeys.

Interaction between components in the customer environment includes the following:

Initiate the registration of credentials in the IdP, on behalf of end users.
Communicate through APIs to request enrollment credentials and shipment of keys.
Get recipient addresses from for example an HR system, for shipments of physical keys.
Communicate with end users to provide the PIN, separate from the physical key delivery.

The orchestration components can be implemented in any number of platforms, automation tools, or code. For example for Microsoft Azure customers, the orchestration requirements can be fulfilled using services like Azure Logic Apps, Azure Function Apps, or other services in their Microsoft Azure subscription.

Different components and orchestrations can be used for different use cases. An onboarding YubiKey issuing workflow can be completely automated using Identity Governance and Administration (IGA) tooling. Other self-service workflows or admin-requested YubiKeys might involve manager approvals using ITSM tooling like ServiceNow.

Yubico provides the FIDO Connector that can be deployed to Microsoft Azure to perform the most complex orchestration parts. See FIDO Connector.

The orchestration components implement the client-side of the encryption/decryption scheme. This supports the encryption/decryption of individual elements in the credential request and response messages so that the PIN and other passkey credential information remains accessible only to the orchestration components. See Security Features.

FIDO Connector

The FIDO Connector is deployed in the customer’s Azure environment, and provides APIs for interacting with the IdP. The API is called from processes and workflows to handle orchestration of credential requests and shipment requests.

Exposes an API that can be called from forms, processes, and workflows in the customer environment. See FIDO Connector API.
Performs all interactions with PingOne PingID/AIC for registering YubiKeys in a PingOne PingID tenant.
Performs all transport encryption before securely transmitting the credential information from the customer orchestration to the FIDO Pre-reg service.
Keeps track of pending shipments and actively polls the FIDO Pre-reg service to check on status and updates to pending FIDO Pre-reg requests.
Once the shipment request is ready, the app decrypts and verifies the authenticity of the response from the FIDO Pre-reg service.
Completes the registration of the YubiKey by calling the PingOne PingID API, or the PingOne AIC Journey API.
Emails the PIN to the specific contact or end user.

An instance of the FIDO Connector can be configured to run with multiple IdPs. As default, the FIDO Connector is configured to be used with Microsoft Entra ID. For more information, see Enabling Multi-IdP Support.

PingOne AIC Journeys APIs

PingOne AIC comes with pre-configured end-user journeys. A Journey is an end-to-end workflow invoked by a device or an end user. Ping One AIC provides templates for common end-user Journeys, for example to register an account and sign-in.

The Journeys APIs are a set of REST-based endpoints that allow developers to build, manage, and execute complex authentication and authorization flows programmatically.

For more information, see Journeys (PingOne AIC documentation) .

FIDO Pre-reg API

The FIDO Pre-reg API is an extension of the the YubiEnterprise API for shipments of pre-enrolled YubiKeys. The FIDO Pre-reg API supports shipment-only requests for YubiKeys pre-programmed in Yubico facilities. For more information, see FIDO Pre-reg API.

Security Features

The following provides an overview of security features in an implementation of FIDO Pre-reg with PingOne PingID or PingOne AIC.

PingOne PingID/AIC Access

Yubico has no access to enroll and/or activate user passkey (FIDO2) credentials directly into a customer’s Entra ID, or PingOne PingID/AIC tenant.

Pre-enrolled Credentials

Because Yubico has no access to the customer’s PingOne PingID/AIC tenant, Yubico registers authenticators (YubiKeys) using the passkey credential creation parameters provided in a customer-initiated shipment request. The credential responses are then returned for retrieval by the customer orchestration, and the credential details are used by the customer orchestration to register YubiKeys with PingOne PingID/AIC.

PIN Provisioning

Yubico generates a PIN for a given YubiKey and returns it to the Delivery service for retrieval by the customer orchestration, which then decides how that PIN gets communicated to the end user.

Transport Encryption

To mitigate the risk of exposing sensitive information, for example creation parameters, serial numbers, and PIN related to YubiKey assignments within the Delivery service, all data transferred from the Yubico environment to the customer orchestration system is encrypted using a secure transfer mechanism. This ensures that Yubico personnel and systems have no access to or visibility into, any credential-related data at any stage of the process.