Updating a PingID SDK app's configuration - PingID

• Default to Primary is the default option for users to be automatically authenticated with their primary device.
  Note:

  If the user doesn’t have a primary device, they will automatically be prompted with the first best fitting trusted device:

  • If the first device is a mobile phone, it will be regarded as the primary device.
  • If the first paired device is not a mobile phone (for example an iPad), and there is another paired device which is a mobile phone, then the mobile phone will be regarded as the primary device.

• Prompt User to Select for users to receive a prompt on each authentication to choose the device to use.

• You may determine the MAXIMUM ALLOWED DEVICES that each user can have. The default value is 5, the minimum is 1, and the maximum value is 15. The user will not be able to add more devices for authentication than the maximum number that was configured. Assuming that Prompt user to select was chosen, this is the maximum number of devices the user will see listed, and be able to choose from, for authentication.
• Possible error codes returned:
  • Top level error code: REQUEST_FAILED
  • Detailed error code: SIZE_LIMIT_EXCEEDED

You can configure the amount of time that an authentication request lasts before timing out. Use this feature to customize the authentication experience to your user's needs, and reduce the number of users that experience a push notification timeout on authentication attempts.

• Select Default to use the system's default timeout values:
  • Device timeout default: 20 seconds
  • Total timeout default: 40 seconds.
• Select Global to apply a custom Device Timeout value and a custom Total Timeout value globally to all mobile application authentication requests, irrespective of where the request originated.
  Note: The value in the Total Timeout field must be at least 15 seconds greater than the value in the Device Timeout field.

  Timeout setting	Device Timeout	Total Timeout
  Minimum	15 seconds	40 seconds
  Maximum	40 seconds	150 seconds
  Default	20 seconds	40 seconds

• Select Advanced to apply individual custom Device Timeout and Total Timeout values to each origin of mobile application authentication requests.
  Note: The valid values range appears in parentheses for each origin's timeout. The value in the Total Timeout field must be at least 15 seconds greater than the value in its corresponding Device Timeout field.

  Configure timeout values of mobile application authentication requests according to their origins:

  • API

    The amount of time in seconds for a new authentication request notification before timing out, for any API request that does not originate from either the CIBA Authenticator (version 1.1.2 and later) or from the PingID SDK Adapter (version 1.8.2 and later).

    Timeout setting	Device Timeout	Total Timeout
    Minimum	15 seconds	40 seconds
    Maximum	40 seconds	150 seconds
    Default	20 seconds	40 seconds

  • CIBA

    The amount of time in seconds for a new authentication request notification before timing out, for any API request that originates from the CIBA Authenticator.

    Note:

    Relevant from CIBA Authenticator 1.1.2.

    If the CIBA Authenticator version is earlier than 1.1.2, the API timeout configuration is applied.

    Timeout setting	Device Timeout	Total Timeout
    Minimum	15 seconds	40 seconds
    Maximum	40 seconds	150 seconds
    Default	20 seconds	40 seconds

  • SDK Adapter

    The amount of time in seconds for a new authentication request notification before timing out, for any API request that originates from the PingID SDK Adapter for PingFederate.

    Note:

    Relevant from SDK Adapter 1.8.2.

    If the SDK Adapter version is earlier than 1.8.2, the API timeout configuration is applied.

    Timeout setting	Device Timeout	Total Timeout
    Minimum	15 seconds	40 seconds
    Maximum	40 seconds	150 seconds
    Default	20 seconds	40 seconds

  • Extra verification silent push

    If Verify Devices is enabled, you can configure the duration of the Device Timeout of the additional silent verification notification.

    Timeout setting	Device Timeout
    Minimum	3 seconds
    Maximum	15 seconds
    Default	7 seconds

  • QR code

    If Verify QR Code Authentication is enabled, you can configure the duration of the Device Timeout of the QR code's additional silent verification notification.

    Timeout setting	Device Timeout
    Minimum	1 second
    Maximum	15 seconds
    Default	7 seconds

• Enable (default):
  Upon mobile app response timeout, or if the device is pushless, the user will be presented with the OTP input screen, and may use OTP to authenticate.

  • PASSCODE FAILURE LIMIT:
    The maximum number of times that the OTP entry can fail for a user, before they are blocked.
    Default: 3
    Minimum: 1
    Maximum: 7
    

  • BLOCK DURATION:
    The amount of time a user's device will be blocked if they exceed the maximum number of passcode failures. The duration may be set in units of minutes or seconds.
    Default: 2 minutes
    Minimum: 2 minutes
    Maximum: 30 minutes

• Disable:
  Upon mobile app response timeout, the user will not be able to authenticate using OTP as an alternative.

• Possible status or error returned:
  • Top level error code: NOT_FOUND

• URL PREFIX: Provide the application's URI prefix (URL or URI scheme), to which a user will be directed after successfully scanning the QR code or clicking the deep link.
  • The URL PREFIX must conform to the following requirements:
    • A string of up to 30 characters starting with an English character (a-z)
    • Subsequent characters may comprise only English alphanumerics (a-z, 0-9), the plus (+), minus (-) or dot(.) characters.
  • The resulting URL will have the format [URL PREFIX]://pingidsdk?authentication_token=[generated_token]. For example, if the Moderno application scheme (URL PREFIX) is "moderno", the resulting URL is: moderno://pingidsdk?authentication_token=[generated_token].
  • If the URL PREFIX is not specified, the QR code content is only the generated token, and the resulting URL has the format: pingidsdk?authentication_token=[generated_token]. In this case, the user must use the camera from within the application.
  • When using the mobile browser, it is logical that this scheme should display the resulting URL as a deep link instead of the QR code. In such a case, when the user clicks the link, they will be navigated to the app specified in the application scheme. If the application scheme is not configured, the deep link won't work.

• VERIFY DEVICES: Select Enable to use the Apple or Android push server to provide extra verification during device authorization. This is the default setting.
• VERIFY QR CODE AUTHENTICATION: Select Enable to use the Apple or Android push server to provide extra verification during QR code based authentication. This is the default setting.

• ROOTED OR JAILBROKEN DEVICES:
  Note: Root and jailbroken devices detection can be invoked for applications built with:

  • PingID Mobile SDK for Android 1.4 and later
  • PingID Mobile SDK for iOS 1.4 and later

  iOS only: We recommend using PingID Mobile SDK for iOS 1.6.1 or later. When the check for jailbroken devices is activated, applications using PingID Mobile SDK for iOS versions before 1.6.1 for authentication are regarded as missing the required data to determine whether the device is jailbroken. Those requests proceed according to the FALLBACK RESPONSE configuration.

  The default setting is Ignore.
  Select Enforce to check integrity of devices as part of the MFA flow, and detect rooted or jailbroken devices. Click Show Advanced Configuration to configure the following parameters:

  • IOS:

    The PingID SDK integrity check solution uses its proprietary algorithm to determine if an iOS mobile device is jailbroken.

    • Ignore jailbreak detection for iOS devices.
    • Select Enforce to check the integrity of iOS devices and to detect jailbroken iOS devices (default).
  • Android:

    The PingID SDK root detection solution utilizes Google’s SafetyNet attestation API to determine the integrity of Android mobile devices.
    See Google’s documentation for further information about SafetyNet integrity levels: https://developer.android.com/training/safetynet/attestation.html#potential-integrity-verdicts

    • Ignore root detection for Android devices.
    • Select Require SafetyNet Basic Integrity for the basic integrity check.
    • Select Require SafetyNet CTS to return a verdict for the more stringent Compatibility Test Suite standard (default).
  • ANDROID SETTINGS:

    Configurable when Require SafetyNet Basic Integrity or Require SafetyNet CTS are selected.

    • CACHE DURATION:

      Since SafetyNet is an external service provided by Google, every attestation request entails a certain time tradeoff. You may choose to cache successful SafetyNet calls for a predefined duration, between a minimum of 1 minute and a maximum of 48 hours.

      CAUTION: Reducing this period once it has already been set, may cause users to fail MFA authentications, forcing them to re-authenticate.
    • SAFETYNET FALLBACK RESPONSE

      Determine if PingID SDK should consider a failed SafetyNet response as a rooted or non-rooted device. Following an Android device's pairing or authentication request, determine whether the request will be granted, if SafetyNet doesn't respond in time, or if Google Play is not installed on the device:

      • Deny the Android device's pairing or authentication request. This is the default setting.
      • Approve the Android device's pairing or authentication request.
  • FALLBACK RESPONSE:

    Determine PingID SDK’s behavior when an authentication or pairing request is missing the required data to determine the requesting device’s integrity.
    This could occur in apps using old mobile SDK component versions, or in apps using a new mobile component versions that call the root detection API with a false flag. The Approve setting may assist in a gradual rollout of the integrity check to all users.
    Following an Android or iOS device's pairing or authentication request, determine whether the request will be granted, if the rooted or jailbroken status of the device can't be determined:

    • Deny the device's pairing or authentication request. This is the default setting.
    • Approve the device's pairing or authentication request.