About FIDO Pre-reg with Microsoft

The Yubico FIDO Pre-reg integration streamlines the deployment process with improved ease of use and enhanced security. End users receive a YubiKey, already pre-registered in the customer’s Entra ID tenant, directly from Yubico, ready to be used. All use cases such as new and existing employees as well as replacements are supported.

The image below provides an example of a customer environment setup based on Microsoft components.

_images/ms-architecture.png

Process Flow

The following steps illustrate the end-to-end YubiKey delivery flow:

  1. An authorized user (or process) triggers a YubiKey request for a user in Microsoft Entra ID via a front-end or IT Service Management (ITSM) orchestration platform.
  2. The YubiKey request is received by the Yubico FIDO Connector App which is deployed on the customer infrastructure. The connector then makes a request over Microsoft Graph API to retrieve the necessary parameters required to create a device-bound passkey credential.
  3. Microsoft Entra ID returns the passkey credential creation parameters for the target user to the Yubico FIDO Connector App which then encrypts the information as a credential request.
  4. The Yubico FIDO Connector App creates a shipment request to the YubiEnterprise Delivery service including the form factor and shipping information, and attaches the encrypted credential request.
  5. After passing through the YubiEnterprise Delivery service, Yubico decrypts the credential request and creates the credential (user private key) for the specified YubiKey form factor. The attestation response from the credential creation is then encrypted.
  6. Yubico ships the YubiKey to the intended end user.
  7. The Yubico FIDO Connector App continuously checks the YubiEnterprise Delivery service for updated shipment status.
  8. When the shipment reaches status “Shipped” in the YubiEnterprise Delivery service, the Yubico FIDO Connector App captures the shipping information including tracking number, serial number, firmware version, and encrypted credential response and PIN.
  9. The shipment status is updated in the customer’s front-end system of choice.
  10. The credential response is decrypted by the Yubico FIDO Connector app.
  11. The YubiKey device-bound passkey credential (user public key) is registered in Microsoft Entra ID through the Microsoft Graph API.
  12. The PIN is decrypted and provided to the customer’s delivery system of choice.
  13. The PIN is communicated to the targeted end user.
  14. The end user authenticates to Microsoft Entra ID using their YubiKey and 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 Orchestration

The custom-developed Customer Orchestration connects the various solution components and drives the interaction between them:

  • Interacts with an HR system or other sources to get user addresses for shipments.
  • Interacts with Microsoft Entra ID to initiate the registration of YubiKeys on behalf of end users.
  • Interacts with Yubico APIs to request shipment of YubiKeys to end users.
  • Communicates with end users to provide the PIN, separate from the YubiKey delivery.

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

Yubico provides the FIDO Connector App that can be deployed to Microsoft Azure to perform the most complex orchestration parts. For more information, see Yubico FIDO Connector App.

Different components and orchestrations can be used for different use cases. Some onboarding YubiKey issuing workflows 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.

The Customer Orchestration implements the client-side of the encryption/decryption scheme. It supports the encryption/decryption of individual elements in the credential request and response messages so that the PIN and other passkey (FIDO2) credential information remains accessible only to the Customer Orchestration. For more information, see Security Features.

The Customer Orchestration components can be configured, customized, and deployed by an IT administrator or a Customer Orchestration developer.

Yubico FIDO Connector App

The Yubico-developed FIDO Connector App is easily deployed to a Microsoft Azure subscription and handles most of the Customer Orchestration complexities:

  • Exposes an API that can be easily called from forms, processes, workflows.
  • Performs all interactions with the Microsoft Graph API for registering YubiKeys in a Microsoft Entra ID tenant.
  • Performs all transport encryption before securely transmitting the credential information from the Customer Orchestration to the Yubico FIDO Pre-reg service.
  • Keeps track of pending shipments and actively polls the Yubico FIDO Pre-reg service to check on status and updates to pending Yubico FIDO Pre-reg requests.
  • Once the shipment request is ready, the app decrypts and verifies the authenticity of the response from the Yubico FIDO Pre-reg service.
  • Completes the registration of the YubiKey by calling the Microsoft Graph API.
  • Emails the PIN to the correct contact (end user’s manager by default).

Yubico FIDO Pre-reg API

The Yubico FIDO Pre-reg API provides a shipping request API to the Customer Orchestration and generates fulfillment requests to Yubico. The API supports the communication of encrypted credential registration data between the Customer Orchestration and Yubico.

The Yubico FIDO Pre-reg API is an extension of the YubiEnterprise API which is a cloud-based service facilitating the global distribution of YubiKeys. For more information, see YubiEnterprise API.

Security Features

The following provides an overview of security features of an implementation of FIDO Pre-reg with Microsoft.

Microsoft Entra ID Access

Yubico has no access to enroll and/or activate user passkey (FIDO2) credentials directly into a customer’s Entra ID tenant. Instead, all interactions with Microsoft Entra ID are handled by the Customer Orchestration.

Pre-Registered Credentials

Since Yubico has no access to the customer’s Microsoft Entra ID 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 Microsoft Entra ID.

PIN Provisioning

Yubico generates a PIN for a given YubiKey and returns it to the YubiEnterprise 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 YubiEnterprise 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.