Device pairing flows
When using the PingOne MFA IdP Adapter through the PingFederate authentication API, the following flows are used for device pairing. These are initiated in the mobile app.
Pairing an initial device using automatic pairing
-
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.
-
The status of
AUTHENTICATION_REQUIRED
is returned in the response to the Mobile app (API client). -
The Mobile app (API client) gets a mobile payload from the mobile SDK.
-
The Mobile app (API client) invokes the
authenticate
action, using the mobile payload. -
The status of
MOBILE_PAIRING_REQUIRED
together with theserverPayload
are returned in the response to the Mobile app (API client). -
The Mobile app (API client) passes the
serverPayload
to the mobile SDK, in order to continue with the pairing process. -
Once pairing is done, the Mobile app (API client) invokes the
continueAuthentication
action. The Mobile app (API client) must callcontinueAuthentication
in order to progress in the OIDC flow, and to complete it. -
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 attributepingone.mfa.status
will have the valuecom.pingidentity.pingone.device_not_paired
, rather than the valuecom.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 valuecom.pingidentity.pingone.pairing_error
.
-
Pairing an additional device using automatic pairing
-
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.
-
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. -
The Mobile app (API client) gets a mobile payload from the mobile SDK.
-
The Mobile app (API client) invokes the
authenticate
action, using the mobile payload. -
The response status would be different since users may have one or more devices already paired:
-
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. -
The status of
OTP_REQUIRED
is returned if the only device that is paired is SMS or TOTP authenticator or email.The Mobile app (API client) invokes the
checkOtp
action submitting the OTP value to PingFederate. -
The status of
DEVICE_SELECTION_REQUIRED
is returned with thedevices
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 thedeviceRef
object. This in turn can get thePUSH_CONFIRMATION_WAITING
orDEVICE_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
.