PingOne

Authentication flows

When using the PingOne MFA IdP Adapter through the PingFederate authentication application programming interface (API), the following flows are used for multi-factor authentication (MFA) requests. These are initiated in the web browser.

MFA using email

A flow diagram showing authentication using an email OTP

  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 API client.

  3. The API client invokes the authenticate action.

  4. The status of DEVICE_SELECTION_REQUIRED is returned with the devices object in the response to the API client.

  5. The API client invokes selectDevice action and specifies the device ID of the device to use for MFA.

  6. The status of OTP_REQUIRED, together with the devices and selectedDeviceRef object, are returned in the response to the API client. In parallel, the user receives an email containing the one-time passcode (OTP) for authentication.

  7. After the user has entered the OTP, the API client invokes the checkOtp action, submitting the OTP value to PingFederate.

  8. On successful completion of MFA, PingFederate returns the status of MFA_COMPLETED to the API client.

  9. The API client invokes the continueAuthentication action. The API client must call continueAuthentication in order to progress in the OIDC flow, and to complete it.

  10. PingFederate returns a single sign-on (SSO) ID token and access token to the API client.

MFA using the mobile app

A flow diagram showing authentication using a mobile application

  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 API client.

  3. The API client invokes the authenticate action.

  4. The status of DEVICE_SELECTION_REQUIRED is returned with the devices object in the response to the API client.

  5. The API client invokes selectDevice action and specifies the device ID of device to use for multi-factor authentication.

  6. The status of PUSH_CONFIRMATION_WAITING, together with the devices and selectedDeviceRef object, are returned in the response to the API client.

  7. The API client invokes the poll action, so that PingFederate gets the status of the mobile push. This is repeated until either a successful status is received or a timeout is reached.

  8. One of the following alternative statuses is reached:

    • MFA_COMPLETED:

      • The user receives a push notification and approves the authentication.

      • The API client invokes the continueAuthentication action. The API client must call continueAuthentication in order to progress in the OIDC flow, and to complete it.

      • PingFederate returns an access token for SSO, to the API client.

    • PUSH_CONFIRMATION_TIMED_OUT:

      • The device was not reachable.

      • The following options are available through the API client:

        • Retry by calling selectDevice with the deviceRef object.

        • Select a different device by calling selectDevice with a different deviceRef object.

        • Cancel the authentication request by calling cancelAuthentication.

    • PUSH_CONFIRMATION_REJECTED:

      • The user receives a push notification, but denies it.

      • The following options are available through the API client:

        • Retry by calling selectDevice with the deviceRef object.

        • Select a different device by calling selectDevice with a different deviceRef object.

        • Cancel the authentication request by calling cancelAuthentication.

    • PUSH_CONFIRMATION_TIMED_OUT:

      • When Show Timeout Screens is enabled in the adapter configuration, the API client can invoke checkOtp directly from this state to allow the user to authenticate with an OTP instead of retrying the push.

MFA using the PingID Desktop App

  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_SELECTION_REQUIRED is returned with the devices object in the response to the API client.

  5. The API client invokes the selectDevice action and specifies the device ID of the PingID Desktop App device.

  6. The status of PINGID_DESKTOP_GEN2_ASSERTION_REQUIRED is returned. The user approves the authentication request in the PingID Desktop App.

  7. The API client invokes the pingIdDesktopGen2CheckAssertion action.

  8. On successful completion of MFA, PingFederate returns the status of MFA_COMPLETED to the API client.

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

  10. PingFederate returns an SSO ID token and access token to the API client.

MFA using YubiKey or the PingID Desktop App (Legacy)

YubiKey and PingID Desktop App (Legacy) both use OTP-based authentication. The flow is the same as for email or SMS: DEVICE_SELECTION_REQUIRED → selectDevice → OTP_REQUIRED → checkOtp → MFA_COMPLETED.