--- title: Updating a PingID SDK app’s configuration description: The following steps describe all the configurable options available for a PingID SDK app. component: pingid page_id: pingid:pingid_sdk:pid_sdk_update_app_configuration canonical_url: http://docs.pingidentity.com/pingid/pingid_sdk/pid_sdk_update_app_configuration.html revdate: July 23, 2023 section_ids: about-this-task: About this task steps: Steps --- # 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 1. Log in to the admin web portal. 2. Select **Applications → PingID SDK Applications**. ![uay1564020819206](_images/uay1564020819206.png) If there are apps already defined for your organization, they will be listed on this page. 3. 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. ![vmn1569482218241](_images/vmn1569482218241.png) 4. 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. ![hzn1569482832354](_images/hzn1569482832354.png) Select **Save** to save your changes. 5. 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. 6. Select the **Configuration** tab to view the app's PingID configuration settings. Click the **Pencil** icon to edit the settings. ![tfp1564020822273](_images/tfp1564020822273.png) | | | | - | -------------------------------------------------------------------- | | | Changes to the configuration will only take effect for new pairings. | 1. **DEVICES**: ![kbl1564020822883](_images/kbl1564020822883.png) * **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` 2. **MOBILE APP AUTHENTICATION**: ![bgf1613036966356](_images/bgf1613036966356.png) * **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. | 3. **MOBILE APPLICATION SDK**: ![pcr1564020824117](_images/pcr1564020824117.png) * **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**: ![kdr1569394818945](_images/kdr1569394818945.png) * **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: * **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. 4. **ALTERNATE AUTHENTICATION METHODS**: ![vbl1575277889135](_images/vbl1575277889135.png) * **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:- [Trusted email domains](https://apidocs.pingidentity.com/pingid-sdk/guide/server-api/pid_c_SDKapiEmailDomains/) - [Trusted email addresses](https://apidocs.pingidentity.com/pingid-sdk/guide/server-api/pid_c_SDKapiEmailAddress/) - [Email templates](https://apidocs.pingidentity.com/pingid-sdk/guide/server-api/pid_c_SDKapiEmailTemplates/) - [Authenticate with email](https://apidocs.pingidentity.com/pingid-sdk/guide/server-api/pid_c_SDKemailDevicesAuthenticate/) | * **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. ![vbl1575277889135](_images/vbl1575277889135.png) * **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. ![gif1575278791542](_images/gif1575278791542.png) * **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. | 7. Select **Save** to save your changes. 8. In the **Applications → PingID SDK Applications** list, select the gray/green toggle to the right of your app to **Enable** or **Disable** it. ![uay1564020819206](_images/uay1564020819206.png)