.. about-fpr-pingone.rst ================================== About FIDO Pre-reg with PingOne ================================== The FIDO Pre-reg integration streamlines the deployment process with improved ease of use and enhanced security. End users receive a YubiKey, already pre-enrolled 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 using Microsoft Azure components and **PingOne PingID** or **PingOne AIC** as IdP. .. image:: graphics/ping-architecture.png :width: 800 .. _process-flow: Process Flow =============== The following steps illustrate the end-to-end pre-enrolled YubiKey delivery flow: 1. An authorized user (or process) triggers a request for shipment of a pre-enrolled 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. 2. The YubiKey request is received by the FIDO Connector deployed in the customer environment. 3. 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. 4. 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. 5. 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. 6. After passing through the Delivery service, Yubico 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. 7. The attestation response from the credential creation along with the PIN are then encrypted. 8. 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. 9. The FIDO Connector continuously checks the Delivery service for updated shipment status. 10. 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. 11. The credentials and the PIN are decrypted by the FIDO Connector, and registered in PingOne PingID, or with PingOne AIC using the Journey API. 12. 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. 13. 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 Orchestration ======================== The *custom-developed orchestration component* in the customer environment 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 PingOne PingID/AIC to initiate the registration of YubiKeys on behalf of end users. * Interacts with Yubico APIs to request shipment of YubiKeys to end users. * Might communicate 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 Azure customers, the orchestration requirements can be fulfilled using services like Azure Logic App, Azure Function App, 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 :ref:`fido-conn-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 :ref:`security-features`. The customer orchestration components can be configured, customized, and deployed by an IT administrator or a customer orchestration developer. .. _fido-conn-app: 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 called from forms, processes, and workflows. * 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. .. note:: Currently an instance of the FIDO Connector can only be configured for *one IdP at a time*, either Microsoft Entra ID or PingOne PingID. As default, the FIDO Connector is configured to be used with Microsoft Entra ID. To change this, see :ref:`config-container-app`. Multiple FIDO Connectors can be deployed and call the same Delivery service for FIDO Pre-reg requests. 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 APIs ========================== The `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, and is an extension of the `YubiEnterprise API `_ for the Delivery service facilitating the global distribution of YubiKeys. The FIDO Connector also has an API that is deployed and used in the customers Azure environment to orchestrate shipment and credential requests. For more information, see `API Reference `_. .. _security-features: 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.