Multi-factor throttling authentication API guide

Use this guide to set up SecureAuth® Identity Platform Authentication API to stop a user from trying to log in too many times with wrong information in a given time.

Multi-factor authentication (MFA) throttling provides protection against two common forms of attack:

Brute force. An attempt to log in using trial-and-error with a large number of one-time passcodes (OTPs).
Denial of service. An attempt to disrupt service by quickly generating a large number of one-time passcodes (OTPs) to overwhelm the system.

This feature uses a dynamic, rolling time period to keep count of MFA attempts. When an end user opens the application login page, an attempt count value increments by 1. That attempt lives for the duration of the configured time period; once the time period for that attempt has elapsed, the attempt count decrements by 1.

The configured throttling action occurs when the attempt count exceeds the number of allowed attempts
The attempt count is reset to 0 upon a successful authentication

Using default settings — which is 5 attempts in 30 minutes, block further attempts until time is expired:

A user unsuccessfully attempts to authenticate with a multi-factor method at 1:00 p.m. The attempt count value increments to one (1).
Twenty minutes later, the user unsuccessfully authenticates four (4) more times.
The attempt count value is now five (5) and the system throttles the user. The user cannot make any attempts until the count value drops below five (5).
At 1:30 p.m. (30 minutes after the first unsuccessful attempt), the first unsuccessful MFA drops off. The attempt count value decrements to four (4). The user can now attempt to log in one more time.
This time, the user successfully authenticates using an MFA method. The user moves on to the next step in the login workflow and the attempt count value resets to zero (0).

Note

Throttling in multi-factor authentication is enabled on a per application realm basis, but all realms share the same attempt count value.
Password entry is not considered in the attempt count for throttling in multi-factor authentication. For example, if the user successfully enters a multi-factor method, but enters the wrong password, then there is no throttling penalty.

Prerequisites

SecureAuth IdP 9.2 or later
Complete the steps in the Authentication API guide
Set up multi-factor throttling in the SecureAuth IdP. See the Multi-factor throttling configuration document.

Endpoints

Multi-Factor Throttling uses two endpoints: one for multi-factor authentication throttling and another for one-time passcode (OTP) validation throttling.

For multi-factor authentication throttling, use the /users/{username}/throttle endpoint to:

GET the current count of MFA method attempts by the user
PUT (reset) the count of MFA method attempts to zero (0) upon successful authentication by the user. It stores the attempt count in a data store profile mapping for Multi-Factor Throttle in the Advanced Settings.

For one-time passcode (OTP) validation throttling use the /users/{username}/otpvalidatethrottle endpoint to:

GET the current count of OTP usage attempts by the user
PUT (reset) the count of OTP usage attempts to zero (0) upon successful authentication by the user. It stores the attempt count in a data store profile mapping for Multi-Factor Throttle in the Advanced Settings.

The configuration thresholds for throttling in MFA attempts for this API is in the Advanced Settings on the Multi-Factor Methods tab. When authentication attempts exceeds the threshold, it disregards the authentication attempt and displays an error message to the end user.

GET /throttle

HTTP method	URI	Example
GET	`/api/v1/users/{username}/throttle`	https://secureauth.company.com/secureauth2/api/v1/users/jsmith/throttle

Success response	Failure response
{ "status": "found", "message": "", "count": <INTEGER> } HTTP Status 200	{ "status": "not_found", "message": "User Id was not found", "count": "" } HTTP Status 404

GET /otpvalidatethrottle

HTTP method	URI	Example
GET	`/api/v1/users/{username}/otpvalidatethrottle`	https://secureauth.company.com/secureauth2/api/v1/users/jsmith/otpvalidatethrottle

Success response	Failure response
{ "status": "found", "message": "", "count": <INTEGER> } HTTP Status 200	{ "status": "not_found", "message": "User Id was not found", "count": "" } HTTP Status 404

PUT /throttle

HTTP method	URI	Example
PUT	`/api/v1/users/{username}/throttle`	https://secureauth.company.com/secureauth2/api/v1/users/jsmith/throttle

Success response	Failure response
{ "status": "found", "message": "", "count": 0 } HTTP Status 200	{ "status": "not_found", "message": "User Id was not found", "count": "" } HTTP Status 404

PUT /otpvalidatethrottle

HTTP method	URI	Example
PUT	`/api/v1/users/{username}/otpvalidatethrottle`	https://secureauth.company.com/secureauth2/api/v1/users/jsmith/otpvalidatethrottle

Success response	Failure response
{ "status": "found", "message": "", "count": 0 } HTTP Status 200	{ "status": "not_found", "message": "User Id was not found", "count": "" } HTTP Status 404

In this section: