Updating a PingID SDK app’s configuration
About this task
The following steps describe all the configurable options available for a PingID SDK app.
Steps
-
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.
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.
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.
-
-
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
-
-
-
-
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.
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.
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.
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.
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
-
-
-
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.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.
-
-
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
-
-
-
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.
-
-
-
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:
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.
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.
-
-
-
-
-
ALTERNATE AUTHENTICATION METHODS:
-
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.PingID SDK supports use of your organization’s own trusted email domains and email addresses, using the PingID SDK APIs. This reinforces trust from the customer and also from the receiving servers. The APIs provide a further option to configure DKIM and SPF verification for outbound emails. In the PingID SDK developer’s guide, see:
-
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. -
SMS and VOICE daily limits:
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
-
-
-
-
PASSCODE FAILURE LIMIT, BLOCK DURATION and PASSCODE LIFETIME IN MINUTES for EMAIL, SMS and VOICE:
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.
Customized parameter values such as PASSCODE FAILURE LIMIT, BLOCK DURATION and PASSCODE LIFETIME IN MINUTES are not saved for the specific EMAIL, SMS or VOICE feature, if that feature is set to Disable. The next time it is enabled, these configurable settings initial values will be reset to the system default.
Dedicated SMS and VOICE subaccounts:
PingID SDK supports a dedicated subaccount for pairing and authentication with SMS and VOICE one time passcodes (OTPs). You can determine the amount of dedicated phone numbers and the country-code from which the SMS and VOICE messages will be sent to the users.
For further details and to activate subaccounts, contact Ping Support.
-
Note that if you wish to delete a subaccount’s dedicated number, users associated with the deleted number will receive their OTP messages from one of the PingID primary account’s assigned numbers for 2 minutes until completion of the deletion process. Once the deletion process is complete, they will receive their OTP messages from one of the subaccount’s remaining numbers.
-
-
-
-
-
-
Select Save to save your changes.
-
In the Applications → PingID SDK Applications list, select the gray/green toggle to the right of your app to Enable or Disable it.