The MFA settings endpoint supports operations to read, update, and reset the PingOne MFA settings associated with a specified environment. A PUT
request lets you manage the maximum number of allowed devices for pairing, and it lets you set the device selection option. A successful DELETE
operation resets the MFA settings to the default.
The MFA settings property pairing.maxAllowedDevices
defines the maximum number of paired MFA devices each user within an environment can have. This can be any number up to 15. The default value is 5. You can update the setting with GET /environments/{{envID}}/mfaSettings
and reset the setting to its default with PUT /environments/{{envID}}/mfaSettings
.
If the maxAllowedDevices
value is decreased below the number of paired devices a user currently has, the user’s existing paired devices remain. After a paired device is deleted though, the user cannot replace it with a new one. This remains true until the number of existing paired devices is below the current value for maxAllowedDevices
.
If the maxAllowedDevices
limit is reached and the user attempts to create a new device, an error similar to the following is returned.
400 BAD REQUEST
{
"id": "<errorId>",
"code": "REQUEST_FAILED",
"message": "The request could not be completed. There was an issue processing the request.",
"details": [
{
"code": "LIMIT_EXCEEDED",
"message": "Maximum allowed devices has been reached",
"innerError": {
"maximumAllowed": 5
}
}
]
}
The MFA settings property lockout.failureCount
and lockout.durationSeconds
defines the maximum number of incorrect MFA authorization actions a user can attempt (such as entering an incorrect OTP or denying a push confirmation on a native device) before the account is locked. The lockout.durationSeconds
defines the amount of time after the lockout.failureCount
value is exceeded to keep the account in a locked state. You can update the setting with PUT /environments/{{envID}}/mfaSettings
.
For more information about account lockout, see User Accounts.
Property | Type | Required? | Mutable? | Description |
---|---|---|---|---|
lockout |
Object | Optional | Mutable | Contains information about the MFA policy lockout settings. |
lockout.failureCount |
Integer | Optional | Mutable | The maximum number of incorrect authentication attempts before the account is locked. |
lockout.durationSeconds |
Integer | Optional | Mutable | The number of seconds to keep the account in a locked state. |
pairing |
Object | Optional | Mutable | Contains information about the MFA policy device pairing settings. |
pairing.maxAllowedDevices |
Integer | Optional | Mutable | The maximum number of MFA devices each user can have. This can be any number up to 15. The default value is 5. All devices that are Active or Blocked are subject to this limit. |
pairing.pairingKeyFormat |
String | Optional | Mutable | The type of pairing key issued. The valid values are NUMERIC (12-digit key) and ALPHANUMERIC (16-character alphanumeric key). |
phoneExtensions |
Object | Optional | Mutable | Contains settings for phone extension support. |
phoneExtensions.enabled |
Boolean | Optional | Mutable | Set to true to allow one-time passwords to be delivered via voice to phone numbers that include extensions. Set to false to disable support for phone numbers with extensions. By default, support for extensions is disabled. |
updatedAt |
Date | N/A | Read-only | When the resource was last updated. |
users |
Object | Optional | Mutable | Contains information about the default settings for new users. |
users.mfaEnabled |
Boolean | Optional | Mutable | Set mfaEnabled to true if you want MFA to be enabled by default for new users. |
Code | Message |
---|---|
200 | Successful operation. |
400 | The request could not be completed. |
401 | You do not have access to this resource. |
404 | The requested resource was not found. |