Platform APIs
More PingIdentity APIs

PingID SDK adapter core contract attributes

The PingID SDK adapter for PingFederate contains several attributes in its core contract:

pingid.sdk.status

The PingID SDK adapter for PingFederate contains the pingid.sdk.status attribute in its core contract. The pingid.sdk.status attribute is populated only if the PingID SDK adapter returns a SUCCESS status.

As an example, the admin can map the pingid.sdk.status attribute to any access token attribute. Once the pingid.sdk.status attribute is mapped, it is added to the access token.

pingid.sdk.status contains the following data:

  • The authenticating device type (SMS, voice, email, mobile etc.).

  • Whether the end user accessed via the web or the mobile application.

  • Status information which may result in reduced permission for the user.

    Examples:

    • The user has no trusted devices. In this case, the adapter may create a registration token for the user and return a success status. The actual pairing is done afterwards within the mobile application. Since the user has not actually completed MFA yet, there may be considerations to reduce the user permissions.
    • The user has a trusted device. However, in a case where this device is marked as "bypassed", MFA will be skipped and the adapter is still going to return the success status. Once again, the user has not actually passed MFA.

pingid.sdk.status values

The status information is returned as a string in the following format:

com.pingidentity.pingidsdk.<status>

Where <status> is one of the following string values:

Pairing statuses:

<status> Description
device_not_paired This status is returned in the following scenarios:
  • On a user’s first login, and before pairing is completed.
  • When the system is configured to pair each device individually and a user logs in from a new unpaired device.
  • When the system is configured to pair each device individually, and a user attempts to authenticate using a new device after already having reached the maximum allowed paired devices, the user will be able to login without the option to pair afterwards.
  • A user logs in, and the system is configured for manual pairing, and also to bypass untrusted users for manual pairing.
device_paired This status is returned on successful pairing, when using the PingFederate Authentication API (PingFederate PingID SDK IDP Adapter 1.8+).
device_access_allowed This status is returned if the untrusted mobile is allowed a one-time access, when using the PingFederate Authentication API (PingFederate PingID SDK IDP Adapter 1.8+).
device_ignored This status is returned in the following scenarios:
  • A user logs in from an ignored device.
  • A user’s untrusted device was set to be ignored by the user’s other trusted device during authentication, when using the PingFederate Authentication API (PingFederate PingID SDK IDP Adapter 1.8+).
web_login_no_devices
  • A user without any trusted devices logs in from the web and the system is configured to bypass authentication for users without a trusted device.
pairing_error
  • A user who is not active (does not have any trusted devices) attempts to log in, and registration token creation fails. Regardless of the reason for the registration token creation failure, the user is authenticated successfully but cannot complete the pairing process.
  • When the system is configured to pair each device individually, and an active user (who has at least one trusted device) tries to pair another device, but the registration token process fails. Regardless of the reason for the registration token process failure, the user logs in but cannot complete the pairing process.

Authentication statuses:

<status> Description
device_authorized This status is returned on successful authentication of a login from a trusted mobile device.
web_login_sms This status is returned on successful SMS authentication from a web login.
web_login_voice This status is returned on successful voice authentication from a web login.
web_login_email This status is returned on successful email authentication from a web login.
web_login_mobile This status is returned on successful SDK mobile app authentication from a web login.
web_login_qr_code This status is returned on successful SDK QR code authentication from a web login.
mobile_login_sms This status is returned on successful SMS authentication when the user login is from an untrusted mobile.
In the PingFederate Authentication API flow, this value is returned in pingid.sdk.status.reason.
pingid.sdk.status may be one the following:
  • device_paired
  • device_ignored
  • device_access_allowed
mobile_login_voice This status is returned on successful voice authentication when the user login is from an untrusted mobile.
In the PingFederate Authentication API flow, this value is returned in pingid.sdk.status.reason.
pingid.sdk.status may be one the following:
  • device_paired
  • device_ignored
  • device_access_allowed
mobile_login_email This status is returned when a user logs in to an untrusted mobile app and is authenticated using their trusted email device.
In the PingFederate Authentication API flow, this value is returned in pingid.sdk.status.reason.
pingid.sdk.status may be one the following:
  • device_paired
  • device_ignored
  • device_access_allowed
mobile_login_mobile This status is returned on successful mobile authentication when the user login is from an untrusted mobile, or when a deep link exists for QR code authentication.
In the PingFederate Authentication API flow, this value is returned in pingid.sdk.status.reason.
pingid.sdk.status may be one the following:
  • device_paired
  • device_ignored
  • device_access_allowed
device_bypassed A user logs in from their trusted yet bypassed mobile device.
device_authorized_no_response_passive_push When the system is configured to regard no response for extra verification as success, and a user logs in but the extra verification does not arrive.
device_rooted_or_jailbroken The user has attempted to authenticate with a device that has been detected as rooted or jailbroken.
MFA_bypassed_during_errors A user logs in when the system is configured to bypass authentication if there are network problems or the PingID SDK service is unreachable.

pingid.sdk.status.reason

The PingFederate core contract attribute pingid.sdk.status.reason is populated with the value device_rooted_or_jailbroken when both of the following apply:

  • The device has been detected as rooted or jailbroken.
  • pingid.sdk.status has the value com.pingidentity.pingidsdk.pairing_error.

authenticating.device.rooted

The PingFederate core contract attribute authenticating.device.rooted is populated with the value true when the following applies:

  • The device has been detected as rooted or jailbroken.
  • pingid.sdk.status has the value com.pingidentity.pingidsdk.device_rooted_or_jailbroken.

accessing.device.rooted

The PingFederate core contract attribute accessing.device.rooted is populated with the value true when the following applies:

  • The device has been detected as rooted or jailbroken.
  • pingid.sdk.status has the value com.pingidentity.pingidsdk.device_rooted_or_jailbroken.