PingID Administration Guide

PingID SDK Package 1.8 (September 25, 2019)

The PingID SDK 1.8 package is released with the following components:

PingID SDK component Module Submodule Version Status

PingID Mobile SDK

PingID Mobile SDK for Android

1.4

Updated

PingID Mobile SDK for iOS

1.4

Updated

PingID SDK Server sample code

1.4

Updated

PingFederate PingID SDK Integration Kit 1.6

PingFederate PingID SDK IDP Adapter 1.5

PingFederate PingID SDK IDP Adapter

1.5

Updated

PingFederate PingID SDK IDP Selector

1.1

Updated

PingFederate PingID SDK Connector

1.2.1

Updated

Enhancements

PingID SDK has been extended with the following features:

PingID SDK support for custom Twilio account

PingID SDK has been extended to allow customers to use a custom Twilio account instead of Ping Identity’s account, providing the following benefits:

  • Avoid manual back-to-back billing (Ping-Customer)

  • Cost leverage over Twilio for customers with massive SMS and Voice usage

  • Consolidate customer’s usage from helpdesk and audit perspective

A new PingID SDK Twilio configuration section was added in the Administration Guide. See Using a custom Twilio account with PingID SDK.

Rooted and jailbroken device detection support

PingID SDK has an integrated mobile device integrity check in its MFA flows, which allows customer mobile applications to provide reduced permissions, or deny access when a mobile device is detected as 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 whether the device is rooted.
A new configuration section was added in the Administration Guide . See Update a PingID SDK app’s configuration.

Minimum software version requirements

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 devicesImplementations using PingFederate require the following additional minimum software versions:

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

Server APIs

The following PingID SDK Server APIs were extended to support rooted and jailbroken devices:

  • User devices API: A new rooted (true/false) parameter has been added to the device object.
    The filter option on the GET operation is now deprecated, and is supported for backward compatibility. The new POST operation should be used instead of the filter option on GET.

  • Authentication API: A new possible value of DEVICE_ROOTED has been added to the reason parameter.
    The new rooted (true/false) parameter in the device object is returned in the GET and POST response bodies.

  • Registration Token A new DEVICE_ROOTED code is returned when a rooted or jailbroken device is detected in the POST operation. See Error handling in PingID SDK.

Mobile APIs

PingID mobile SDK for iOS and Android was extended with the following new mobile APIs:

Mobile API Description

setRootDetection

Activates device integrity check flow.

getRestrictiveOneTimePasscode

Returns an OTP and the status of the response.

generatePayload(final PayloadCallback callback)

*This change affects Android only.
For iOS, generatePayload remains unchanged. generatePayload returns the current mobile payload in a callback parameter, in a different thread (asynchronously).

The previous Android version of generatePayload is deprecated (PingID Mobile SDK for Android v1.3 and earlier). The new generatePayload(final PayloadCallback callback) method should be used instead.

The following mobile APIs are deprecated:

Mobile API Description

getOneTimePasscode

If the root detection feature is disabled in the admin console, an OTP is returned.
If the root detection feature is enabled in the admin console, an empty string is returned.

  • The getOneTimePasscode method is deprecated, and supported for backward compatibility. The getRestrictiveOneTimePasscode method should be used instead.

  • The getOneTimePasscode previously returned an 8-digit OTP for iOS and a 6-digit OTP for Android devices. It now returns a 6-digit OTP for both iOS and Android devices. Developers who implemented their application code according to the earlier version of the Moderno sample app (which truncated the last 2 digits of the 8-digit OTP for iOS), should adjust their application code.

generatePayload

*This change affects Android only.
For iOS, generatePayload remains unchanged. generatePayload returns the current mobile payload in a callback parameter.

The previous Android version of generatePayload is deprecated (PingID Mobile SDK for Android v1.3 and earlier). The new generatePayload(final PayloadCallback callback) method should be used instead.

Refer to PingID SDK Mobile API for further information.

Moderno sample app

The new version of the Moderno sample app has been extended to include support for rooted and jailbroken device detection.

Developer IDE

  • iOS: Project build settings require the target configuration of Always Embed Swift Standard Libraries to be set to YES. See iOS implementation.

  • Android: PingID SDK component dependencies in build.gradle

    This version includes new SDK component dependencies for Android. These should be entered in the application’s gradle.build file under dependencies. Developers must manually add these dependencies to their project, in order for the SDK to work, as the lib is distributed as a file and not via a repository.

    The full list of dependencies is as follows (new or changed dependency versions are highlighted in bold):

        //LOGGING FACADE AND IMPLEMENTATION
     implementation 'org.slf4j:slf4j-api:1.7.26'
    implementation 'com.github.tony19:logback-android-core:1.1.1-6'
    implementation('com.github.tony19:logback-android-classic:1.1.1-6')
     \{ exclude group: 'com.google.android', module: 'android' }

    // JWT, JWE and JOSE tokens libraries
     implementation 'org.bitbucket.b_c:jose4j:0.6.5'

    //Google's gSon library to build and parse JSON format
    implementation 'com.google.code.gson:gson:2.8.5'
     implementation 'commons-codec:commons-codec:1.12'

    //CRYPTO
     implementation 'com.madgag.spongycastle:prov:1.58.0.0'
     implementation 'com.google.android.gms:play-services-base:16.0.1'
     implementation 'com.google.android.gms:play-services-safetynet:16.0.0'

    //FireCloud Messaging Services
     implementation 'com.google.firebase:firebase-messaging:18.0.0'

    See Android implementation.

PingFederate PingID SDK IDP Adapter 1.5 Rooted and jailbroken device detection

The PingID SDK Adapter has been extended to support detection of rooted and jailbroken devices during pairing and authentication.

PingFederate PingID SDK Selector 1.1 Rooted and jailbroken device detection

The PingID SDK Selector has been extended to support detection of rooted and jailbroken devices.

PingFederate PingID SDK Connector 1.2.1

The PingID SDK Users API was recently improved to support usernames containing special characters such as a forward slash "/". The PingID SDK Connector has incorporated this improved username validation and encoding to support API changes.

Re-obfuscation

PingID SDK code is obfuscated for optimization. Support is now available for apps obfuscation to re-obfuscate the PingID SDK code, which previously not supported.

Validation check for payload creation without an application ID

The PingID SDK Mobile API has been extended to check that payload creation includes an application ID. If the application ID is missing, a new error code (PIDErrorMissingAppId = -10022) is returned.

Resolved issues

Ticket ID Description

PIMC-419

Due to differences between the names of the header file and framework, there was a known limitation that Swift developers were required to use a bridging file in order to import the SDK. This has been resolved, so that a bridging file is no longer necessary.

PIMC-454

PingID Mobile SDK for Android was using fixed values for title and body strings. This has been resolved so that it now uses the title and body submitted in the push.

PIMC-564

Authentications failed when "Background app refresh" was turned off on the iPhone, while both the following settings were configured:

  • PingIDadmin console: "Extra push" was activated

  • PingFederate: "User verification regard as failure"This has been resolved.

Known issues and limitations

PingFederate integration: when rooted and jailbroken devices are blocked, only the authentication flow is supported

If the PingFederate ROOTED/JAILBROKEN DEVICE configuration is set to Block, users with rooted or jailbroken devices are blocked during authentication flows, but are granted access when automatic pairing fails.

QR authentication failure for a rooted or jailbroken device

The QR authentication transaction fails for a rooted or jailbroken device, without the option to add business logic in PingFederate or in the customer server. When a user scans the QR code on a rooted device, the QR code remains unclaimed, and the accessing web page remains unchanged, and does not progress to authentication.

Rooted Android device detection from Android 5.0

The minimum operating system supported for root detection is Android 5.0. When root detection is activated, devices with Android versions earlier than 5.0 will not be able to pair or authenticate.

Using Xcode 10.2.1, simulators for iOS 9.3 and earlier might fail to launch Swift apps

Apple reported the following known issue in the Xcode 10.2.1 release notes, which may impact the PingID SDK Moderno app: Simulators for iOS 9.3 and earlier might fail to launch Swift apps with the message: “dyld: Library not loaded: /usr/lib/libauto.dylib”. Workaround: Run the following command in Terminal for the relevant version of iOS:

sudo mkdir '/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS 9.3.simruntime/Contents/Resources/RuntimeRoot/usr/lib/swift'

See https://developer.apple.com/documentation/xcode_release_notes/xcode_10_2_1_release_notes?language=objc.
Initialization of PingID SDK instance in Android apps::

An extreme case was discovered where the PingID SDK instance remained null instead of initialized after execution of PingID.init in an Android app. As a workaround, check if the instance remains null , and if so, then reinitialize it.