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.

EMAIL:
The default setting is Disable.
Select Enable to permit users to authenticate via email. When EMAIL is selected, a one time passcode will be sent to the user’s email address.

SMS:
The default setting is Disable.
Select Enable to permit users to authenticate via SMS. The SMS & VOICE daily limits configuration options appear.

VOICE:
The default setting is Disable.
Select Enable to permit users to authenticate via VOICE. The SMS & VOICE daily limits configuration options appear.

When SMS or VOICE are selected, admins have the option to configure the daily limit for users’ SMS and VOICE authentications:

• DAILY USED SMS/VOICE LIMIT: 1-50: (default = 15).

  Configure the maximum combined number of SMS and VOICE authentication requests a user may receive and respond to each day.

  • Possible status or error returned:
    • Top level error code: INVALID_REQUEST
    • Detailed error code: SMS_QUOTA_EXCEEDED
• DAILY UNUSED SMS/VOICE LIMIT: 1-50: (default = 10).

  Configure the maximum combined number of SMS and VOICE authentication requests a user may receive and not respond to each day.

  • Possible error codes returned:
    • Top level error code: REQUEST_FAILED
    • Detailed error code: SMS_QUOTA_EXCEEDED

When at least one of EMAIL, SMS or VOICE is enabled, admins have the option to configure the permitted number of OTP attempt failures before a user is blocked, the duration of the block, or the duration of an OTP.

• PASSCODE SETTINGS:

  • General:
    Admins can configure a single PASSCODE FAILURE LIMIT, BLOCK DURATION and PASSCODE LIFETIME IN MINUTES, which will apply equally to all of the enabled EMAIL, SMS and VOICE options.

    

  • Advanced:
    Admins can configure a separate individual PASSCODE FAILURE LIMIT, BLOCK DURATION and PASSCODE LIFETIME IN MINUTES for each of the enabled EMAIL, SMS and VOICE options.

    

  • 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
    After reaching the maximum number of failure attempts, the flow ends and the exits the OTP entry screen.

  • 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: 0 minutes (not blocked)
    Minimum: 0 minutes
    Maximum: 30 minutes

  • PASSCODE LIFETIME IN MINUTES:
    The amount of time an OTP is valid before it expires.
    The duration may be set in units of minutes.
    Default: 30 minutes
    Minimum: 1 minute
    Maximum: 30 minutes

  • Authentication scenarios:
    All of the PASSCODE FAILURE LIMIT, PASSCODE LIFETIME IN MINUTES and BLOCK DURATION settings apply for authentication attempts.

  • Pairing scenarios:
    Only the PASSCODE FAILURE LIMIT and the PASSCODE LIFETIME IN MINUTES apply for pairing attempts, whereas BLOCK DURATION does not apply.

  • When switching configurations between the General and Advanced modes, only the current mode's PASSCODE FAILURE LIMIT, BLOCK DURATION and PASSCODE LIFETIME IN MINUTES settings are saved. Switching back to the other mode will not reinstate its previously saved configuration, but rather, it will reset back to its default values.