--- title: Device pairing flows description: When using the PingOne MFA IdP Adapter through the PingFederate authentication application programming interface (API), the following flows are used for device pairing. These are initiated in the mobile app. component: pingone page_id: pingone:pingone_mfa_integration_kit:pf_p1_mfa_ik_device_pairing_flows canonical_url: https://docs.pingidentity.com/integrations/pingone/pingone_mfa_integration_kit/pf_p1_mfa_ik_device_pairing_flows.html revdate: June 15, 2024 section_ids: pairing-an-initial-device-using-automatic-pairing: Pairing an initial device using automatic pairing pairing-an-additional-device-using-automatic-pairing: Pairing an additional device using automatic pairing --- # Device pairing flows When using the PingOne MFA IdP Adapter through the PingFederate authentication application programming interface (API) *(tooltip: \
\

A specification of interactions available for building software to access an application or service.\

\
)*, the following flows are used for device pairing. These are initiated in the mobile app. ## Pairing an initial device using automatic pairing ![A flow diagram that shows the initial device pairing](_images/arv1611698447117.png) 1. The user completes first-factor authentication. Completion of first-factor authentication is a prerequisite before progressing to multi-factor authentication (MFA) *(tooltip: \
\

An electronic authentication method where a user is granted access only after presenting two or more verification factors for authentication.\

\
)*, when using the PingOne MFA IdP Adapter with the PingFederate Authentication API flow. 2. The status of `AUTHENTICATION_REQUIRED` is returned in the response to the Mobile app (API client). 3. The Mobile app (API client) gets a mobile payload from the mobile SDK. 4. The Mobile app (API client) invokes the `authenticate` action, using the mobile payload. 5. The status of `MOBILE_PAIRING_REQUIRED` together with the `serverPayload` are returned in the response to the Mobile app (API client). 6. The Mobile app (API client) passes the `serverPayload` to the mobile SDK, in order to continue with the pairing process. 7. Once pairing is done, the Mobile app (API client) invokes the `continueAuthentication` action. The Mobile app (API client) must call `continueAuthentication` in order to progress in the OpenID Connect (OIDC) *(tooltip: \
\

An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management.\

\
)* flow, and to complete it. 8. PingFederate returns an access token to the Mobile app (API client). * Even if the pairing is not successful, it is possible for the Mobile app (API client) to send the `continueAuthentication` action. In this case, the contract attribute `pingone.mfa.status` will have the value `com.pingidentity.pingone.device_not_paired`, rather than the value `com.pingidentity.pingone.device_paired`. * In the event of an error occuring during device pairing, the adapter will return a success status, and `pingone.mfa.status` will have the value `com.pingidentity.pingone.pairing_error`. ## Pairing an additional device using automatic pairing ![A flow diagram that shows the device pairing process for users who already have a paired device](_images/lbz1611964632010.png) 1. The user completes first-factor authentication. Completion of first-factor authentication is a prerequisite before progressing to MFA, when using the PingOne MFA IdP Adapter with the PingFederate Authentication API flow. 2. The status of `AUTHENTICATION_REQUIRED` is returned in the response to the Mobile app (API client). The returned device is the user's primary device. 3. The Mobile app (API client) gets a mobile payload from the mobile SDK. 4. The Mobile app (API client) invokes the `authenticate` action, using the mobile payload. 5. The response status would be different since users may have one or more devices already paired: 1. The status of `PUSH_CONFIRMATION_WAITING` is returned if the mobile device is the only device that is paired. Push notification is sent to the paired mobile. The Mobile app (API client) invokes the `poll` action, so that PingFederate gets the status of the mobile push. This is repeated until the user approves or denies the push authentication request. 2. The status of `OTP_REQUIRED` is returned if the only device that is paired is SMS or Time-based One-Time Password (TOTP) *(tooltip: \
\

A temporary passcode generated by an algorithm that uses the current time of day as one of its authentication factors. Typically, an app or hardware token generates a 6-digit passcode that is valid for less than 1 minute.\

\
)* authenticator or email. The Mobile app (API client) invokes the `checkOtp` action submitting the OTP value to PingFederate. 3. The status of `DEVICE_SELECTION_REQUIRED` is returned with the `devices` object in the response to the API client if the user has more than one device paired. The Mobile app (API client) invokes the `selectDevice` action with the `deviceRef` object. This in turn can get the `PUSH_CONFIRMATION_WAITING` or `DEVICE_SELECTION_REQUIRED` status as mentioned above. Even if the pairing is not successful, it is possible for the Mobile app (API client) to send the `continueAuthentication` action. In this case, the contract attribute `pingone.mfa.status` will have the value `com.pingidentity.pingone.device_not_paired`, rather than the value `com.pingidentity.pingone.device_paired`. In the event of an error occurring during device pairing, the adapter will return a success status, and `com.pingidentity.pingone.status `will have the value` com.pingidentity.pingone.pairing_error`.