Multi-Factor Throttling Authentication API Guide
Introduction
Use this guide to configure SecureAuth Authentication API to prevent a user from attempting to log onto a realm using invalid credentials too often during a specified period of time.
Multi-Factor 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 OTPs
"Denial of service" - an attempt to disrupt service by quickly generating a large number of OTPs to overwhelm the system
This feature uses dynamic, rolling time periods to separately count the end-user's Multi-Factor Authentication method selection attempts and validation attempts.
When the end-user starts the realm login page, the 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 whenever the attempt count exceeds the number of attempts allowed
The attempt count is reset to 0 upon a successful authentication
Prerequisites
1. Ensure SecureAuth IdP v9.1 or later is running
2. Complete the steps in the Authentication API Guide
3. Complete Multi-Factor Throttling configuration steps in the SecureAuth IdP Web Admin
Refer to Multi-Factor Throttling Configuration Guide for more information
SecureAuth IdP Web Admin
Endpoints
Multi-Factor Throttling uses two endpoints: one for Multi-Factor Authentication throttling and another for One-time Passcode validation throttling
Multi-Factor Authentication throttling uses the /users/{username}/throttle endpoint to:
GET the end-user's current count of Multi-Factor Authentication method selection attempts
PUT (reset) the count of Multi-Factor Authentication method selection attempts to 0 after the end-user successfully authenticates; the attempt count is stored in a directory attribute configured in the Web Admin
One-time Passcode (OTP) validation throttling uses the /users/{username}/otpvalidatethrottle endpoint to:
GET the end-user's current count of OTP usage attempts
PUT (reset) the OTP throttling count to 0 after the end-user successfully authenticates;the attempt count is stored in a directory attribute configured in the Web Admin
The thresholds for this API are configured within the Multi-Factor Methods tab of the Web Admin; any authentication attempt exceeding these thresholds is disregarded and an error message is displayed to the end-user, based on the configuration defined in the steps above
GET
/throttle
HTTP Method | URI | Example |
---|---|---|
GET | /api/v1/users/{username}/throttle | https://secureauth.company.com/secureauth2/api/v1/users/jsmith/throttle |
/otpvalidatethrottle
HTTP Method | URI | Example |
---|---|---|
GET | /api/v1/users/{username}/otpvalidatethrottle | https://secureauth.company.com/secureauth2/api/v1/users/jsmith/otpvalidatethrottle |
PUT
/throttle
HTTP Method | URI | Example |
---|---|---|
PUT |
| https://secureauth.company.com/secureauth2/api/v1/users/jsmith/throttle |
/otpvalidatethrottle
HTTP Method | URI | Example |
---|---|---|
PUT |
| https://secureauth.company.com/secureauth2/api/v1/users/jsmith/otpvalidatethrottle |