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