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+

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

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.

Email authentication flow example

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

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.

PingID SDK state models

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

Status Response Model Action Description
AUTHENTICATION_REQUIRED Indicates that authentication is required.
This state is the first state returned from the adapter. If authentication is impossible for the user, the MFA_COMPLETED or MFA_FAILED states are returned with a corresponding code.
DEVICE_SELECTION_REQUIRED Indicates that device selection is required.
This state is returned if no device was provided in the authenticate action, and device selection is required.
Device selection is required when BOTH the following conditions occur:
  • The user has more than one device.
  • The configuration is “Prompt user to select” OR
    the user has no primary device, but only trusted devices.
OTP_REQUIRED Indicates that OTP is required.
This state is returned when the user is prompted to provide an OTP. The OTP is one of the following:
  • Sent to the user in an email, SMS or voice message.
  • The OTP that is displayed in the mobile application.
PUSH_CONFIRMATION_WAITING Indicates that a push was sent to the user.
Note:
To get the final push confirmation state, the API client can either call the poll, or call GET .
PUSH_CONFIRMATION_TIMED_OUT Indicates a push timeout state.
PUSH_CONFIRMATION_REJECTED
  • selectedDeviceRef: ResourceRef
  • devices: List <Device>
  • user: User
  • Reason: String.
    Possible values:
    • DENIED_BY_USER
    • BLOCKED_BY_USER
Indicates that the user has rejected the push.
MFA_COMPLETED Indicates a successful MFA.
The API client must call continueAuthentication in order to progress in the OIDC flow, and to complete it.
MFA_FAILED
  • code: String.
  • message: String.
  • userMessage: String.
See possible MFA_FAILED codes.
Indicates a dead end.
The API client can proceed in the OIDC flow by calling cancelAuthentication. The adapter will return a FAILURE status.

PingID SDK action models

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

Action Request Model Errors Description
authenticate Starts an authentication flow.
selectDevice Starts an authentication with the specific deviceId. For example:
{
"deviceRef":
{
"id": "5728da66-24f5-4a80-5728-da6624f54a80"
}
}

If there is already an authentication in progress, this authentication will be canceled.
This action is available only when the user has at least one device, and can also be used as an authentication retry.
checkOtp
  • otp: String.
Validates the provided OTP.
poll This action has no model. This action has no errors. This action gets the status of the mobile push.
An alternative is to call GET .
cancelAuthentication This action has no model. This action has no errors. This action cancels the current authentication step.
continueAuthentication This action has no model. This action has no errors. This action continues the current authentication flow.

Models inner objects

Device object

Representation of a device:

Parameter name Type Description
id String Unique identifier of a trusted device in the PingID SDK server.
type String Device platform.
Valid values:
  • Android
  • iPhone
  • SMS
  • Voice
  • Email
name String Model of the device, for example, iPhone 5S.
This parameter is empty for OTP devices (SMS, voice, email).
nickname String The device’s nickname.
role String Role of the device in the user’s network:
Valid values:
  • Primary
  • Trusted
enrollmentTime Date The date and time of the first registration of the device, in the context of the application.
applicationId String The ID of the PingID SDK customer mobile application.
bypassExpiration Date The date and time when the user’s device enabled bypass mode will expire.
bypassed boolean Indicates whether the user’s device is in bypass mode.
pushEnabled boolean Indicates whether the device can receive a push notification.
osVersion String The device’s operating system and version.
applicationVersion String The device’s application version.
target String The device’s masked email address/phone number.
usable boolean Indicates whether the device is usable. For example, if the device is locked, it is not usable.

User object

Representation of a user:

Parameter name Type Description
id String The user’s id.
firstName String The user’s first name.
lastName String The user’s last name.
status String The user’s status in PingID SDK.
Possible values:
  • NOT_ACTIVE
  • ACTIVE
  • SUSPENDED
lastLogin Date The last date and time the user authenticated successfully.

ResourceRef object

Representation of a resource reference:

Parameter name Type Description
id String The resource’s identifier.

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

Error code Message HTTP status
VALIDATION_ERROR One or more validation errors occurred. 400
UNEXPECTED_ERROR An unexpected error occurred while processing the request. 400
REQUEST_FAILED The request could not be completed. There was an issue processing the request. 400

Detail level error codes

Error code Message userMessageKey Parent code
INVALID_OTP An invalid or expired passcode was provided. authn.api.invalid.otp VALIDATION_ERROR
OTP_EXPIRED The passcode has expired. authn.api.otp.expired REQUEST_FAILED
INVALID_DEVICE
Note: This code is returned if the device is not one of the user’s devices, or if the device is unusable.
An invalid device was provided. VALIDATION_ERROR
DEVICE_LOCKED The device is locked. authn.api.device.locked REQUEST_FAILED
DEVICE_ROOTED The user’s device is detected as having been rooted or jailbroken. authn.api.device.rooted REQUEST_FAILED
OTP_ATTEMPTS_LIMIT The user performed too many unsuccessful passcode attempts. authn.api.otp.attempts.limit REQUEST_FAILED
OTP_RESEND_LIMIT The user has resent the passcode the maximum number of times. See SMS and VOICE daily limits in Update a PingID SDK app’s configuration, in the admin guide. authn.api.otp.resend.limit REQUEST_FAILED
PUSH_FAILED Failed to send the push message. authn.api.push.failed REQUEST_FAILED

MFA_FAILED codes

Error code Message userMessageKey
SERVER_ERROR Server error. authn.api.server.error
SESSION_EXPIRED Session expired. authn.api.session.expired
SERVICE_UNAVAILABLE Service unavailable. authn.api.service.unavailable
USER_SUSPENDED The user is suspended. authn.api.user.suspended
INACTIVE_USER
This error code indicates the user is inactive and the adapter does not support registration on the fly (“automatic pairing”).
The user is inactive. authn.api.inactive.user
UNABLE_TO_PAIR
This error indicates that the user is inactive and the adapter cannot start the pairing process since the user must login from the mobile device application in order to register.
Unable to pair. authn.api.unable.to.pair
DEVICE_LOCKED
This error code can also be returned if this is not a dead end.
The device is locked. authn.api.device.locked
OTP_RESEND_LIMIT
This error code can also be returned if this is not a dead end.
The user has re-sent the passcode the maximum number of times. authn.api.otp.resend.limit
DEVICE_ROOTED
This code can also be returned if this is not a dead end.
The user’s device is detected as having been rooted or jailbroken. authn.api.device.rooted
PUSH_FAILED Failed to send the push message. authn.api.push.failed