PingOne Platform APIs

Device Authentication Policies

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, WhatsApp) 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

N/A

Read-only

Deprecated. Can still appear in responses.

id

String

N/A

Read-only

The ID of the device authentication policy.

ignoreUserLock

Boolean

Optional

Mutable

When applying an MFA policy, PingOne ordinarily checks if a user account is locked, and if so, prevents the user from authenticating. Set ignoreUserLock to true if you want PingOne to skip this account lock check.

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.

notificationsPolicy.id

String

Optional

Mutable

If you want the MFA policy to use a specific notification policy rather than just using the default notification policy, use notificationsPolicy.id to specify the ID of the notification policy that should be used.

rememberMe

Object

Optional

Mutable

Object used to specify that the MFA policy should include a "remember me" option so that users do not have to authenticate when accessing applications from a device they have used already.

rememberMe.web

Object

Optional

Mutable

Contains the "remember me" settings for accessing applications from a browser.

rememberMe.web.enabled

Boolean

Optional

Mutable

Set to true if you want the MFA policy to include a "remember me" option.

rememberMe.web.lifeTime

Object

Optional

Mutable

Used to define the period during which users will not have to authenticate if they are accessing applications from a device they have used before. The "remember me" period can be anywhere from 1 hour to 90 days.

rememberMe.web.lifeTime.timeUnit

String

Optional

Mutable

The time unit to use for the "remember me" period. Can be HOURS or DAYS.

rememberMe.web.lifeTime.duration

Integer

Optional

Mutable

Used in conjunction with lifeTime.timeUnit to define the "remember me" period.

sms

Object

Required

Mutable

SMS device authentication policy settings. Offline device (SMS, voice, email, WhatsApp) 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, WhatsApp) authentication policy data model

whatsApp

Object

Optional

Mutable

Contains the settings for using WhatsApp as an authentication method. Offline device (SMS, voice, email, WhatsApp) 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.

failure

Object

Optional

Mutable

Contains the definitions for the maximum number of times authentication can fail before user is blocked temporarily, and how long the user should be blocked.

failure.coolDown.duration

Integer

Optional

Mutable

Used in conjunction with failure.coolDown.timeUnit to specify how long the user should be blocked after reaching the maximum number of failures, before they can try authenticating again. Minimum period is two minutes, maximum is 30 minutes.

failure.coolDown.timeUnit

String

Optional

Mutable

The units to use for failure.coolDown.duration. Can be SECONDS or MINUTES.

failure.count

Integer

Optional

Mutable

The maximum number of times that authentication can fail before user is blocked for the specified period. Minimum is 1, maximum is 7.

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.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

Offline device (SMS, voice, email, WhatsApp) 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.

otp.otpLength

Integer

Optional

Mutable

Used to specify the length of the OTP that is shown to users. Minimum length is 6 digits and maximum is 10 digits. If the parameter is not provided, the default is 6 digits.

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.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

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,
                "numberMatching": {
                    "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.

</li></ul>

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[].push.numberMatching.enabled

Boolean

Optional

Mutable

Set to true if you want the mobile push to require the user to match a number that they were shown when requesting access. To specify how the matching should be carried out, refer to the numberMatching.type parameter in the Applications OIDC settings data model.

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.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

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.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

uriParameters

Object

Optional

Mutable

Object that you can use to provide key:value pairs for otpauth URI parameters. For example, if you provide a value for the issuer parameter, then authenticators that support that parameter will display the text you specify together with the OTP (in addition to the username). This can help users recognize which application the OTP is for. If you intend on using the same MFA policy for multiple applications, choose a name that reflects the group of applications.

PingID method data model (for PingOne environments where PingID accounts have been integrated)

These fields are used for the PingID-specific authentication methods - desktop, Yubikey, and OATH token.

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 amount of time the user is blocked after reaching the maximum number of passcode failures. The minimum is one second and the maximum is 30 minutes. 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 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 OTP entry can fail for a user, before they are blocked. The minimum value is 1, maximum is 7.

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.

pairingKeyLifetime.duration

integer

Optional

Mutable

For "desktop" only. The amount of time the pairing key is valid. Can be expressed in minutes or hours. Minimum is one minute, maximum is 48 hours. If the pairingKeyLifetime object is not provided, then 48 hours is used.

pairingKeyLifetime.timeUnit

String

Optional

Mutable

The time unit for pairingKeyLifetime.duration. Can be MINUTES or HOURS.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

PingID app data model (for PingOne environments where PingID accounts have been integrated)

This table includes the properties that are used for the PingID mobile app. All of the fields in the table below should be enclosed in the mobile object, as in the example in Mobile device authentication policy data model.

Property Type Required? Mutable? Description

applications[].autoEnrollment.enabled

Boolean

N/A

Read-only

Not relevant for PingOne environments where PingID accounts have been integrated. Will always be returned as false.

applications[].biometricsEnabled

Boolean

Optional

Mutable

Set to true if you want to allow users to authenticate with the biometric methods supported by the PingID app.

applications[].id

String

Required

Immutable

The application’s UUID.

applications[].otp.enabled

Boolean

Optional

Mutable

Specifies whether the user can authenticate with a one-time passcode generated by the PingID app when push notifications are not available. If the parameter is not included, the option is disabled.

applications[].pairingKeyLifetime.duration

Integer

Optional

Mutable

The amount of time an issued pairing key can be used until it expires. Can be expressed in minutes or hours. Minimum is one minute, maximum is 48 hours. If the pairingKeyLifetime object is not provided, then 48 hours is used.

applications[].pairingKeyLifetime.timeUnit

String

Optional

Mutable

The time unit for pairingKeyLifetime.duration. Can be MINUTES or HOURS.

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 pushLimit.lockDuration.duration. 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, 10 minutes is used.

applications[].pushLimit.timePeriod.timeUnit

String

Optional

Mutable

The time unit for pushLimit.timePeriod.duration. The valid values are MINUTES and SECONDS.

applications[].newRequestDurationConfiguration.deviceTimeout.duration

Integer

Required

Mutable

The amount of time an authentication request notification has to reach the device before timing out. Minimum is 15 seconds, maximum is 75 seconds.

applications[].newRequestDurationConfiguration.deviceTimeout.timeUnit

String

Required

Immutable

The time unit to use for deviceTimeout.duration. Only valid value is SECONDS.

applications[].newRequestDurationConfiguration.totalTimeout.duration

Integer

Required

Mutable

The total amount of time an authentication request notification has to be handled by the user before timing out. This includes both the time until the notification is displayed to the user and the time the user takes to respond. Minimum is 30 seconds, maximum is 90 seconds. totalTimeout.durationmust exceed deviceTimeout.duration by at least 15 seconds.

applications[].newRequestDurationConfiguration.totalTimeout.timeUnit

String

Required

Immutable

The time unit to use for totalTimeout.duration. Only valid value is SECONDS.

applications[].push.enabled

Boolean

Required

Mutable

Specifies whether push notification is enabled or disabled for the policy.

applications[].push.numberMatching

Boolean

Optional

Mutable

Set to true if you want to require the authenticating user to select a number that was displayed to them on the accessing device.

applications[].type

String

Required

Immutable

Value must be set to pingIdAppConfig.

enabled

Boolean

Required

Mutable

Whether the device is enabled or disabled in the policy.

ipPairingConfiguration.anyIPAdress

Boolean

Optional

Mutable

If you want to limit users to specific IP addresses when pairing their device, set anyIPAdress to false, and use ipPairingConfiguration.onlyTheseIpAddresses to specify the valid IP addresses.

ipPairingConfiguration.onlyTheseIpAddresses

Array

Optional

Mutable

If you set ipPairingConfiguration.anyIPAdress to false, use onlyTheseIpAddresses to specify the IP addresses from which users can pair their devices. Each item in the array should be an IP address or an address range using CIDR notation, for example, 192.168.0.1/24

otp.failure.coolDown.duration

Integer

Required

Mutable

The amount of time the user is blocked after reaching the maximum number of passcode failures. Can be expressed in seconds or minutes. The minimum is two minutes, and the maximum is 30 minutes. 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 time unit to use 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.

promptForNicknameOnPairing

Boolean

Optional

Mutable

Set to true if you want to allow users to provide nicknames for devices during pairing.

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.

Device authentication policy events generated

Refer to Audit Reporting Events for the events generated.

Related topics