Integration with the PingFederate Authentication API

Overview

The PingFederate PingID SDK IDP Adapter enables integration with the PingFederate Authentication API for end-user interactions, for step-up authentication and transaction approval. The PingFederate Authentication API provides access to the current state of the flow as an end user steps through a PingFederate authentication policy. For more information on the PingFederate Authentication API, see Authentication API in the PingFederate documentation.

Prerequisites

The PingFederate PingID SDK IDP Adapter supports integration with PingFederate Authentication API from the following software versions:

• PingFederate 9.3+
• PingFederate PingID SDK IDP Adapter 1.7+ for web authentication
• PingFederate PingID SDK IDP Adapter 1.8+ for web authentication and mobile pairing and authentication

Admins must follow the installation and configuration steps in the PingID admin guide:

• Install the PingID SDK Integration Kit for PingFederate

• Configure the PingID SDK adapter for PingFederate

  Important: When using the PingFederate Authentication API flow, you must process first-factor authentication before invoking the PingID SDK adapter for PingFederate.

PingFederate includes an API Explorer, which allows you to view the states, actions, and models available for the various API-capable adapters and selectors included in your PingFederate environment. For more details, see Exploring the authentication API in the PingFederate documentation.

Flow logic

The following examples illustrate the implementation of typical authentication flows with the PingID SDK adapter and the PingFederate Authentication API.

Web authentication flows

• Email authentication flow example

  This flow depicts an access request via a web browser, and MFA via an email OTP:

  

  MFA for an OTP via email as depicted in the diagram above, and using the PingFederate Authentication API, follows the following logic flow:

  1. The user completes first-factor authentication. Completion of first-factor authentication is a prerequisite before progressing to MFA, when using the PingFederate PingID SDK IDP Adapter with the PingFederate Authentication API flow.
  2. The status of AUTHENTICATION_REQUIRED together with the devices object are returned in the response to the API client.
  3. The API client invokes the authenticate action.
  4. The status of OTP_REQUIRED together with the selectedDeviceRef object are returned in the response to the API client. In parallel, the user receives an email containing the OTP for authentication.
  5. After the user has entered the OTP, the API client invokes the checkOtp action, submitting the OTP value to PingFederate.
  6. On successful completion of MFA, PingFederate returns the status of MFA_COMPLETED to the API client.
  7. 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.
  8. PingFederate returns an access token for SSO, to the API client.

• Mobile application authentication flow example

  This flow depicts an access request via a web browser, and MFA via mobile application:

  

  MFA for a mobile application as depicted in the diagram above, and using the PingFederate Authentication API, follows the following logic flow:

  1. The user completes first-factor authentication. Completion of first-factor authentication is a prerequisite before progressing to MFA, when using the PingFederate PingID SDK IDP Adapter with the PingFederate Authentication API flow.

  2. The status of AUTHENTICATION_REQUIRED together with the devices object are returned in the response to the API client.

  3. The API client invokes the authenticate action.

  4. The status of PUSH_CONFIRMATION_WAITING together with the selectedDeviceRef object are returned in the response to the API client.

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

  6. 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.
       • There are two options available via the API client:
         • Retry by calling selectDevicewith the deviceRef object.
         • Cancel the authentication request by calling cancelAuthentication.
     • PUSH_CONFIRMATION_REJECTED:
       • The user receives a push notification, but denies or blocks it.
       • There are two options available via the API client:
         • Retry by calling selectDevicewith the deviceRef object.
         • Cancel the authentication request by calling cancelAuthentication.

Mobile authentication flows

• Pair first device

  This flow depicts a user pairing a first device via a mobile application:

  

  Pairing a first mobile device is depicted in the diagram above. This example uses the PingFederate Authentication API, and follows the following logic flow:

  1. The user completes first-factor authentication. Completion of first-factor authentication is a prerequisite before progressing to MFA, when using the PingFederate PingID SDK IDP Adapter with the PingFederate Authentication API flow.
  2. The status of AUTHENTICATION_REQUIRED together with an empty devices object are 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 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 pingid.sdk.status will have the value com.pingidentity.pingidsdk.device_not_paired, rather than the value com.pingidentity.pingidsdk.device_paired.
  • In the event of an error occuring during device pairing, the adapter will return a success status, and pingid.sdk.status will have the value com.pingidentity.pingidsdk.pairing_error.

• Authorization with extra push verification for a paired mobile device

  This flow depicts an access request via a mobile application, and authorization with extra push verification for a paired mobile device:

  

  Authorization with extra push verification for a paired mobile device is depicted in the diagram above. This example uses the PingFederate Authentication API, and follows the following logic flow:

  1. The user completes first-factor authentication. Completion of first-factor authentication is a prerequisite before progressing to MFA, when using the PingFederate PingID SDK IDP Adapter with the PingFederate Authentication API flow.
  2. The status of AUTHENTICATION_REQUIRED together with the devices object are 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 PUSH_CONFIRMATION_WAITING together with the selectedDeviceRef object are returned in the response to the Mobile app (API client).
  6. The Mobile app (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.
  7. The status of MFA_COMPLETED together with the device_authorized code are returned in the response to the Mobile app (API client).
  8. The Mobile app (API client) invokes the continueAuthentication action. The Mobile app (API client) must call continueAuthentication in order to progress in the OIDC flow, and to complete it.
  9. PingFederate returns an access token to the Mobile app (API client).

• Login from unpaired mobile, and user has other paired mobile

  This flow depicts an access request via an unpaired mobile application, and MFA via the user’s other paired mobile device. In the flow example, the Additional Trusted Devices parameter is set to Verify New Devices with Primary Device in the PingID SDK IdP Adapter configuration in PingFederate. See Configure the PingID SDK adapter for PingFederate.

  

  This diagram depicts an example of a login from an unpaired mobile, when the user has another paired mobile device. The Additional Trusted Devices parameter is set to Verify New Devices with Primary Device in the PingID SDK IdP Adapter configuration in PingFederate. See Configure the PingID SDK adapter for PingFederate. This example uses the PingFederate Authentication API, and follows the following logic flow:

  1. The user completes first-factor authentication. Completion of first-factor authentication is a prerequisite before progressing to MFA, when using the PingFederate PingID SDK IDP Adapter with the PingFederate Authentication API flow.
  2. The status of AUTHENTICATION_REQUIRED together with the devices object are 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 status of PUSH_CONFIRMATION_WAITING together with the selectedDeviceRef object are returned in the response to the Mobile app (API client). The returned device is the user’s primary device.
  6. A push notification is sent to primary mobile device so that the user can decide whether to trust the new device and continue the pairing flow.
  7. 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 decides what to do with the unpaired device, or the user hasn’t responded.
  8. Since the user decides to trust the device, the status of MOBILE_PAIRING_REQUIRED together with the serverPayload are returned in the response to the Mobile app (API client).
  9. The Mobile app (API client) invokes the continueAuthentication action. The Mobile app (API client) must call continueAuthentication in order to progress in the OIDC flow, and to complete it.
  10. PingFederate returns an access token to the Mobile app (API client).

PingID SDK state models

This table describes the PingID SDK state objects for the PingFederate Authentication API.

PingID SDK action models

This table describes the PingID SDK action objects for the PingFederate Authentication API.

{
  "deviceRef":
  {
    "id": "5728da66-24f5-4a80-5728-da6624f54a80"
  }
}

Models inner objects

Device object

Representation of a device:

User object

Representation of a user:

ResourceRef object

Representation of a resource reference:

Error models

An error code is returned if the call flow state has not reached a dead end, and the user can still authenticate with a device. In cases where a flow reaches a dead end, the MFA_FAILED state is returned with a corresponding code.

Top level error codes

Detail level error codes

MFA_FAILED codes