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.
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 |
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:
|
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 |
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. |
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. |
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:
|
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. |
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. |
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. |
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. |