The following steps describe all the configurable options available for a PingID SDK app.
- Log in to the admin web portal.
-
Select Applications > PingID SDK Applications.
If there are apps already defined for your organization, they will be listed on this page.
-
Select the Down arrow icon to the right of the app you want
to configure, to expand the view. Click the Pencil icon in the
right margin to edit the app’s settings.
-
Click the Pencil icon to the right of the app name, to
change the name that appears in the application list.
The system checks that there are no other apps registered for this organization with the identical name.
Select Save to save your changes.
-
Select the Integration tab to view the iOS and Android
connection settings for the app. Click the Pencil icon in the
right margin, to edit the settings.
- iOS: You can upload and associate separate certificate files, for the SANDBOX and for PRODUCTION. When uploading a certificate file, a prompt appears for the CERTIFICATE PASSWORD. By selecting the Eye icon toggle, you can choose whether the password will be displayed on the screen, or masked.
- Android: Both of the connection details fields, SENDER ID and SERVER KEY, may either be left blank, or both must be filled. Select Save to save your changes.
-
Select the Configuration tab to view the app’s PingID
configuration settings. Click the Pencil icon to edit the
settings.
Important: Changes to the configuration will only take effect for new pairings.
-
DEVICES:
-
DEVICE SELECTION:
-
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.
-
Default to Primary is the default option for
users to be automatically authenticated with their primary
device.
-
MAXIMUM ALLOWED DEVICES:
- 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
-
DEVICE SELECTION:
-
MOBILE APP AUTHENTICATION:
- NEW REQUEST DURATION:
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.
An authentication request's duration is determined by two configurable measurements:- Device Timeout: The amount of time in seconds that a new authentication request notification must reach a user's mobile device, before timing out.
- Total Timeout: The total amount of time in seconds that a new authentication request will last, before timing out. This includes the time for Device Timeout, plus the time that the user has to respond to the authentication request.
- 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
- API
-
ONE-TIME PASSCODE FALLBACK:
-
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.
Important: Customized PASSCODE FAILURE LIMIT and BLOCK DURATION values are not saved when ONE-TIME PASSCODE FALLBACK is set to Disable. The next time it is enabled, these configurable settings initial values will be reset to the system default. -
- NEW REQUEST DURATION:
-
MOBILE APPLICATION SDK:
-
PAIRING KEY LIFETIME: Set the duration of validity
in minutes, hours or days for a manual pairing key, before it expires.
The default is 48 hours, and the maximum is 31 days.
- Possible status or error returned:
- Top level error code: NOT_FOUND
- Possible status or error returned:
-
QR CODE AUTHENTICATION:
-
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.
- The URL PREFIX must conform to the
following requirements:
-
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.
-
USE PUSH NOTIFICATIONS:
- 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.
- DEVICE REQUIREMENTS:
- 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.
- CACHE
DURATION:
- 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.
- ROOTED OR JAILBROKEN DEVICES:
-
PAIRING KEY LIFETIME: Set the duration of validity
in minutes, hours or days for a manual pairing key, before it expires.
The default is 48 hours, and the maximum is 31 days.
-
ALTERNATE AUTHENTICATION METHODS:
-
DEVICES: