Device authentication policies (identified in the PingOne UI as “MFA Policies”) enable you to configure different settings per MFA authentication method, according to your security policies.

Device authentication policy data model

Property Type Required? Mutable? Description
authentication.deviceSelection String Optional Mutable The default method that should be used for authentication. Can take one of the following values:
  • DEFAULT_TO_FIRST - use the method that the user set as their default
  • PROMPT_TO_SELECT - always have the user select the method to use if there is more than one method available
  • ALWAYS_DISPLAY_DEVICES - always have the user select the method to use even if there is only one method available
If this parameter is not provided, the DEFAULT_TO_FIRST option is used.
default Boolean Required Mutable Whether this is the default policy for Flow Manager.
email Object Required Mutable Email device authentication policy settings. Offline device (SMS, voice, email) authentication policy data model
environment String N/A Read-only The environment ID.
fido2 Object Required Mutable FIDO device authentication policy settings. FIDO device authentication policy data model
forSignOnPolicy Boolean Optional Immutable Deprecated.
id String N/A Read-only The ID of the device authentication policy.
mobile Object Required Mutable Mobile device authentication policy settings. Mobile authentication policy data model
name String Required Immutable The device authentication policy’s name.
newDeviceNotification String Optional Mutable Use newDeviceNotification to control whether a user should be notified if a new authentication method has been added to their account. Can take one of the following values:
  • NONE - don’t notify the user when a new authentication method is added.
  • EMAIL_THEN_SMS - notify the user by email. If there is no email address in the user profile, notify the user by SMS. If there is no phone number either, don’t notify the user.
  • SMS_THEN_EMAIL - notify the user by SMS. If there is no phone number in the user profile, notify the user by email. If there is no email address either, don’t notify the user.
If the parameter is not provided, the default value is EMAIL_THEN_SMS.
sms Object Required Mutable SMS device authentication policy settings. Offline device (SMS, voice, email) authentication policy data model
totp Object Required Mutable TOTP device authentication policy settings. TOTP authentication policy data model
updatedAt Date N/A Read-only When the resource was last updated.
voice Object Required Mutable Voice device authentication policy settings. Offline device (SMS, voice, email) authentication policy data model

FIDO device authentication policy data model

All of the fields in the table below should be enclosed in the fido2 object, for example:

"fido2" : {
    "enabled" : true,
    "pairingDisabled" : false
}
Property Type Required? Mutable? Description
enabled Boolean Required Mutable Whether the authentication method is enabled or disabled in the policy.
fido2PolicyId String Optional Mutable The ID of the specific FIDO policy that should be used. If this parameter is not provided, the default FIDO policy is used.
pairingDisabled Boolean Optional Mutable You can set pairingDisabled to true to prevent users from pairing new devices with the relevant method. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices.

Offline device (SMS, voice, email) authentication policy data model

Property Type Required? Mutable? Description
enabled Boolean Required Mutable Whether the device is enabled or disabled in the policy.
otp.failure.coolDown.duration Integer Required Mutable The duration (number of time units) the user is blocked after reaching the maximum number of passcode failures. The minimum value is 0, maximum is 30, and the default is 0. Note that when using the “onetime authentication” feature, the user is not blocked after the maximum number of failures even if you specified a block duration.
otp.failure.coolDown.timeUnit String Required Mutable The type of time unit for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.
otp.failure.count Integer Required Mutable The maximum number of times that the OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7, and the default is 3.
otp.lifetime.duration Integer Required Mutable The duration (number of time units) that the passcode is valid before it expires. The minimum value is 1, maximum is 7, and the default is 3.
otp.lifetime.timeUnit String Required Mutable The type of time unit for otp.lifetime.duration. Valid values are MINUTES and SECONDS.
pairingDisabled Boolean Optional Mutable You can set pairingDisabled to true to prevent users from pairing new devices with the relevant method. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices.

Mobile device authentication policy data model

All of the fields in the table below should be enclosed in the mobile object, for example:

"mobile": {
    "enabled": true,
    "otp": {
        "failure": {
            "count": 3,
            "coolDown": {
                "duration": 2,
                "timeUnit": "MINUTES"
            }
        }
    },
    "applications": [
        {
            "id": "{{appID}}",
            "push": {
                "enabled": true
            },
            "otp": {
                "enabled": true
            },
            "pushTimeout": {
                "duration" : 120,
                "timeUnit" : "SECONDS"
            },
            "pushLimit": {
                "count": 4,
                "timePeriod": {
                    "duration": 10,
                    "timeUnit": "MINUTES"
                },
                "lockDuration": {
                    "duration": 30,
                    "timeUnit": "MINUTES"
                }
            },
            "deviceAuthorization": {
                "enabled": true,
                "extraVerification": "permissive"
            },
            "autoEnrollment": {
                "enabled": true
            },
            "pairingKeyLifetime": {
                "duration": 40,
                "timeUnit": "HOURS"
            },
            "integrityDetection": "permissive"
        }
    ]
}
Property Type Required? Mutable? Description
applications[].autoEnrollment.enabled Boolean Required Mutable Set to true if you want the application to allow Auto Enrollment. Auto Enrollment means that the user can authenticate for the first time from an unpaired device, and the successful authentication will result in the pairing of the device for MFA.
applications[].deviceAuthorization.enabled Boolean Required Mutable Specifies the enabled or disabled state of automatic MFA for native devices paired with the user, for the specified application.
applications[].deviceAuthorization.extraVerification String Required Mutable Specifies the level of further verification when deviceAuthorization is enabled. The PingOne platform performs an extra verification check by sending a “silent” push notification to the customer native application, and receives a confirmation in return.
extraVerification can be one of the following levels:
  • disabled (default): The PingOne platform does not perform the extra verification check.
  • permissive: The PingOne platform performs the extra verification check. Upon timeout or failure to get a response from the native app, the MFA step is treated as successfully completed.
  • restrictive: The PingOne platform performs the extra verification check.The PingOne platform performs the extra verification check. Upon timeout or failure to get a response from the native app, the MFA step is treated as failed.
applications[].id String Required Immutable The application’s UUID.
applications[].integrityDetection String Required Mutable Controls how authentication or registration attempts should proceed if a device integrity check does not receive a response. Set the value to permissive if you want to allow the process to continue. Set the value to restrictive if you want to block the user in such situations.
applications[].otp.enabled Boolean Required Mutable Specifies whether OTP authentication is enabled or disabled for the policy.
applications[].pairingDisabled Boolean Optional Mutable You can set pairingDisabled to true to prevent users from pairing new devices with the relevant application. You can use this option if you want to phase out an existing mobile application but want to allow users to continue using the application for authentication for existing devices.
applications[].pairingKeyLifetime.duration Integer Optional Mutable The amount of time an issued pairing key can be used until it expires. Minimum is 1 minute and maximum is 48 hours. If this parameter is not provided, the duration is set to 10 minutes.
applications[].pairingKeyLifetime.timeUnit String Optional Mutable The time unit for the pairingKeyLifetime.duration parameter. The possible values are MINUTES and HOURS.
applications[].push.enabled Boolean Required Mutable Specifies whether push notification is enabled or disabled for the policy.
applications[].pushLimit.count Integer Optional Mutable The number of consecutive push notifications that can be ignored or rejected by a user within a defined period before push notifications are blocked for the application. The minimum value is 1 and the maximum value is 50. If this parameter is not provided, the default value is 5.
applications[].pushLimit.lockDuration.duration Integer Optional Mutable The length of time that push notifications should be blocked for the application if the defined limit has been reached. The minimum value is 1 minute and the maximum value is 120 minutes. If this parameter is not provided, the default value is 30 minutes.
applications[].pushLimit.lockDuration.timeUnit String Optional Mutable The time unit for the pushLimit.lockDuration.duration parameter. The valid values are MINUTES and SECONDS.
applications[].pushLimit.timePeriod.duration Integer Optional Mutable The time period in which the push notifications are counted towards the defined limit. The minimum value is 1 minute and the maximum value is 120 minutes. If this parameter is not provided, the default value is 10 minutes.
applications[].pushLimit.timePeriod.timeUnit String Optional Mutable The time unit for the pushLimit.timePeriod.duration parameter. The valid values are MINUTES and SECONDS.
applications[].pushTimeout.duration Integer Optional Mutable The amount of time a user has to respond to a push notification before it expires. Minimum is 40 seconds and maximum is 150 seconds. If this parameter is not provided, the duration is set to 40 seconds.
applications[].pushTimeout.timeUnit String Optional Mutable The time unit for the pushTimeout.duration parameter. Currently, the only permitted value is SECONDS.
enabled Boolean Required Mutable Whether the device is enabled or disabled in the policy.
otp.failure.coolDown.duration Integer Required Mutable The duration (number of time units) the user is blocked after reaching the maximum number of passcode failures. The minimum value is 2, maximum is 30, and the default is 2. Note that when using the “onetime authentication” feature, the user is not blocked after the maximum number of failures even if you specified a block duration.
otp.failure.coolDown.timeUnit String Required Mutable The type of time unit for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.
otp.failure.count Integer Required Mutable The maximum number of times that the OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7, and the default is 3.

TOTP device authentication policy data model

Property Type Required? Mutable? Description
enabled Boolean Required Mutable Whether the device is enabled or disabled in the policy.
otp.failure.coolDown.duration Integer Required Mutable The duration (number of time units) the user is blocked after reaching the maximum number of passcode failures. The minimum value is 2, maximum is 30, and the default is 2.
otp.failure.coolDown.timeUnit String Required Mutable The type of time unit for otp.failure.coolDown.duration. Valid values are MINUTES and SECONDS.
otp.failure.count Integer Required Mutable The maximum number of times that the OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7, and the default is 3.
pairingDisabled Boolean Optional Mutable You can set pairingDisabled to true to prevent users from pairing new devices with the relevant method. You can use this option if you want to phase out an existing authentication method but want to allow users to continue using the method for authentication for existing devices.

PLATFORM and SECURITY_KEY device authentication policy data model (deprecated, replaced by FIDO device)

Property Type Required? Mutable? Description
enabled Boolean N/A Read-only Whether the device is enabled or disabled in the policy.
fidoPolicyId String N/A Read-only The FIDO policy UUID. This property can be null. When null, the environment’s default FIDO Policy is used.

Policy migration data model

Used with the deviceAuthenticationPolicies endpoint and content type: application/vnd.pingidentity.deviceAuthenticationPolicy.fido2.migrate+json for batch conversion of device authentication policies associated with the previous FIDO policy format (device authentication policies that have FIDO Biometrics or Security Key enabled).

Property Type Required? Mutable? Description
migrationData Array Optional Immutable List of the objects that must be migrated.
migrationData[].deviceAuthenticationPolicyId String Required Immutable The UUID of the device authentication policy to migrate. Required if you are providing the migrationData object.
migrationData[].fido2PolicyId String Optional Immutable The UUID of the enhanced FIDO policy to associate with the device authentication policy. If this parameter is not provided, the default FIDO policy is used.