Platform APIs
More PingIdentity APIs

Rooted and jailbroken device detection

PingID SDK has an integrated mobile device integrity check in its MFA flows, which allows customer mobile applications to provide reduced permissions, or totally deny access when a mobile device is suspected to be rooted or jailbroken. On iOS, the PingID SDK proprietary algorithm is used to determine if a mobile device is jailbroken. Android, on the other hand, takes advantage of Google’s SafetyNet service to determine two levels of integrity: Basic Integrity and the more stringent Compatibility Test Suite (CTS).

Admins and developers implementing the root detection capabilities are provided with a set of configuration options to allow flexibility that will meet their needs.

Implement rooted or jailbroken device detection in apps

Prerequisites

The following minimum software versions are required for implementing device integrity checks and detection of rooted and jailbroken devices:

  • PingID Mobile SDK for iOS version 1.4
  • PingID Mobile SDK for Android version 1.4
  • Android 5.0+ on end user Android devices

In addition, implementations using PingFederate also require the following minimum software versions to support device integrity checks and detection of rooted and jailbroken devices:

  • PingFederate version 8.2+ (all versions supporting the PingID SDK Adapter)
  • PingID SDK Adapter version 1.5
  • PingID SDK Selector version 1.1. If PF v9.2 or higher is used, the PingID SDK Selector is optional, and root detection can work with or without it.

Admin console configuration

Each application must be set up and configured in the organization’s PingOne account, via the web admin console. The development team provides the admin with the application name and details.

The admin’s configuration of rooted and jailbroken device detection is detailed in the PingID admin guide: Update a PingID SDK app’s configuration.

Android implementation

PingID SDK root detection solution utilizes Google’s SafetyNet attestation API to determine the integrity of the mobile device it is running on. See Google’s documentation for a better understanding of SafetyNet’s capabilities: https://developer.android.com/training/safetynet/attestation.html

The customer mobile app developers are responsible for enabling and monitoring SafetyNet’s usage.

The following steps are required:

  1. Create a SafetyNet API key:

    See https://developer.android.com/training/safetynet/attestation.html#obtain-api-key. The SafetyNet API key must be provided to the PingID SDK mobile component as described in PingID SDK Mobile API - Android.

  2. Request a quota increase:

    See https://support.google.com/googleplay/android-developer/contact/safetynetqr. SafetyNet’s quota increase form contains questions that are application dependent, and should be answered by PingID SDK customers. The implementation-related settings should be answered in the SafetyNet quota request as follows:

    The requested estimated quota should take into account your app’s expected traffic, and should also consider the SDK mobile component’s retry and caching policy:

    • The mobile component will not initiate more than one SafetyNet request during the SafetyNet Cached Duration period (as defined in the application’s configuration in the PingID Admin Console), if there was a successful response from SafetyNet which did not fail the integrity test.
    • If a SafetyNet request fails with an error, the mobile component will perform one retry for the user action that triggered the SafetyNet request (for example, a login or request for an OTP).

  1. Monitor SafetyNet:

    To ensure SafetyNet resources are not exhausted, you are recommended to monitor SafetyNet usage. See Google’s instructions: https://developer.android.com/training/safetynet/attestation.html#quota-monitoring. If your quota has reached its limit, users may be blocked, according to the SAFETYNET FALLBACK RESPONSE configuration setting in the PingID Admin Console.

PingID SDK mobile component

App developers must implement the following PingID SDK Mobile APIs. See PingID SDK Mobile API for details:

  • setRootDetection
  • getRestrictiveOneTimePasscode
  • generatePayload

Business logic

The PingID SDK server detects rooted or jailbroken devices and responds accordingly upon an authentication or pairing request. You may choose to add business logic to your flow.

PingFederate

If your implementation of PingFederate uses the PingID SDK Adapter, see Configure the PingID SDK adapter for PingFederate in the PingID Admin Guide for the following options:

  • The adapter’s ROOTED/JAILBROKEN DEVICE configuration setting will Allow the authentication flow to continue to the next adapter in the flow chain, or will Block the continuation of the flow.
  • The following Core Contract attributes are populated with information pertaining to the integrity of devices during the pairing or authentication flow. See PingID SDK adapter core contract attributes for their full descriptions. You can use these attributes to modify the access token and provide desired permissions:
    • accessing.device.rooted
    • authenticating.device.rooted
    • pingid.sdk.status
    • pingid.sdk.status.reason
  • Data extracted from the adapter is passed to the HTML login template’s velocity parameters, allowing your app to present information to the user. See Configure HTML login template: Velocity parameters.

Customer server

If you are implementing PingID SDK server endpoints from your custom server (and not via PingFederate), you may parse the responses from PingID, and add the desired business logic. The following endpoints include information regarding the device’s integrity:

  • Authentication GET and POST endpoints: See Authentication API.
    • If the PingID SDK server detected that a device is rooted or jailbroken according to the PingID Admin Console configuration settings, the authentication request will return with the DENIED status, and DEVICE_ROOTED as the status reason.
    • The rooted field in the device object residing in the authentication response will be populated with value “true”, if the authenticating device (“device”) or accessing device (“accessingDevice”) has been detected as rooted or jailbroken according to the PingID Admin Console configuration settings.
  • Registration token POST endpoint:
    • If PingID Server has detected that the device requesting a registration token is rooted or jailbroken according to the PingID Admin Console configuration settings, a REQUEST_FAILED (400) error will return, with the detailed error code DEVICE_ROOTED. See Error handling in PingID SDK.
  • User devices POST endpoint: