PingOne

Device pairing flows

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.

Pairing an initial device using automatic pairing

A flow diagram that shows the initial device pairing

  1. The user completes first-factor authentication. Completion of first-factor authentication is a prerequisite before progressing to multi-factor authentication (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).

  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 is returned along with the PingOneEnrollment object, which includes the serverPayload, pairingKey, and pairingKeyId properties.

  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) 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

  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) 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.

Pairing a PingID Desktop App device

  1. The user completes first-factor authentication.

  2. The status of AUTHENTICATION_REQUIRED is returned in the response to the API client.

  3. The API client invokes the authenticate action.

  4. The status of DEVICE_PAIRING_METHOD_REQUIRED is returned. The API client invokes the selectDevicePairingMethod action, specifying the PingID Desktop App pairing method.

  5. The status of PINGID_DESKTOP_GEN2_ACTIVATION_REQUIRED is returned. The user completes the activation in the PingID Desktop App.

  6. The API client invokes the activatePingIdDesktopGen2Device action, submitting the activation response.

  7. PingFederate returns the status of MFA_COMPLETED.

  8. The API client invokes the continueAuthentication action to complete the OIDC flow.

Pairing a PingID Desktop App (Legacy) device

  1. The user completes first-factor authentication.

  2. The status of AUTHENTICATION_REQUIRED is returned in the response to the API client.

  3. The API client invokes the authenticate action.

  4. The status of DEVICE_PAIRING_METHOD_REQUIRED is returned. The API client invokes the selectDevicePairingMethod action, specifying the PingID Desktop App (Legacy) pairing method.

  5. The status of PINGID_DESKTOP_ACTIVATION_REQUIRED is returned. The API client invokes the pingIdDesktopPoll action until the user completes activation in the PingID Desktop App (Legacy).

  6. PingFederate returns the status of MFA_COMPLETED.

  7. The API client invokes the continueAuthentication action to complete the OIDC flow.

Pairing a YubiKey device

  1. The user completes first-factor authentication.

  2. The status of AUTHENTICATION_REQUIRED is returned in the response to the API client.

  3. The API client invokes the authenticate action.

  4. The status of DEVICE_PAIRING_METHOD_REQUIRED is returned. The API client invokes the selectDevicePairingMethod action, specifying YubiKey as the pairing method.

  5. The status of YUBIKEY_ACTIVATION_REQUIRED is returned. The user inserts their YubiKey and touches it to generate the activation OTP.

  6. The API client invokes the activateYubikeyDevice action, submitting the YubiKey OTP.

  7. PingFederate returns the status of MFA_COMPLETED.

  8. The API client invokes the continueAuthentication action to complete the OIDC flow.