Documentation

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:

  1. "Brute force" - an attempt to log in using trial-and-error with a large number of OTPs
  2. "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
     
Multi-Factor Throttling Use Case Example

Using default settings (5 attempts in 30 minutes, block further attempts until time is expired)

1. An end-user unsuccessfully attempts to authenticate with a Multi-Factor Authentication method at 1:00pm. The attempt count value increments to 1.

2. Twenty minutes later the same end-user unsuccessfully authenticates 4 more times.

3. The attempt count value is now 5, causing the end-user to be throttled. No further attempts can be made until the attempt count value drops below 5.

4. At 1:30pm (thirty minutes after the first unsuccessful attempt), the first unsuccessful Multi-Factor Authentication attempt drops off. The attempt count value decrements to 4. The end-user can now attempt to log in one more time.

5. This time the end-user successfully authenticates using a Multi-Factor Authentication method. The end-user now moves on to the next step in the authentication process (or is redirected to the target resource, depending on the workflow) and the attempt count value resets to 0.

Notes
  • Multi-Factor Throttling is enabled on a per realm basis, but all realms share the same attempt count value
  • Password entry is not considered in the attempt count for purposes of Multi-Factor Throttling (i.e. if the user successfully enters multi-factor but then unsuccessfully enters the password, there is no penalty in terms of throttling)
  • Two separate endpoints must be configured: one to count the end-user's attempt to use a selected Multi-Factor Authentication method, and the other to count the end-user's validation attempt using the selected Multi-Factor Authentication method
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
Multi-Factor Throttling Configuration Steps
Multi-Factor Methods

Configure throttling in the Multi-Factor Throttling frame, located in the Multi-Factor Settings sub-section

1.  Check Enable multi-factor throttling

2. In the Only allow __ failed attempts in __ (Minutes/Hours/Days) for each user fields, set the number of authentication attempts that will be allowed within a rolling time period before throttling takes effect

 The attempt count is incremented when the login page for the realm is opened; this ensures that abandoned attempts (when a user opens the login page but never completes the login attempt) are counted as well

3. Select one of the radio buttons to specify the action that will occur when the end-user exceeds the allowed number of authentication attempts:

  • Block use of multi-factor until time limit has expired: do not allow the end-user to perform another authentication attempt until the attempt count has decremented by at least 1
  • Lock user account after exceeding attempts: upon exceeding the max number of attempts configured above, the user account is locked; refer to Unlock Account Configuration Guide for further information on locked accounts

 

4. In the Store attempt count in dropdown, select the directory attribute that will store the number of multi-factor attempts, or choose Browser Session to only store the attempt count as a cookie for the length of a user's browser session

The directory attribute must be in the Plain Text data format

Click Save once the configuration is complete and before leaving the Multi-Factor Methods tab to avoid losing changes

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 MethodURIExample
GET
/api/v1/users/{username}/throttle
https://secureauth.company.com/secureauth2/api/v1/users/jsmith/throttle
Definitions
  • status: The status of user ID provided (found, not_found, invalid, etc.); will always be in response
  • message: Additional information regarding the status; will always be in response
  • count: The value of the integer corresponding to the number of the successful / failed attempt within the rolling time period
GET Endpoint Response Examples
GET Responses:
SuccessFailure
{
"status": "found",
"message": "",
"count": <INTEGER>
}
HTTP Status 200
{
"status": "not_found",
"message": "User Id was not found",
"count": ""
}
HTTP Status 404
/otpvalidatethrottle
HTTP MethodURIExample
GET
/api/v1/users/{username}/otpvalidatethrottle
https://secureauth.company.com/secureauth2/api/v1/users/jsmith/otpvalidatethrottle
Definitions
  • status: The status of user ID provided (found, not_found, invalid, etc.); will always be in response
  • message: Additional information regarding the status; will always be in response
  • count: The value of the integer corresponding to the number of the successful / failed attempt within the rolling time period
GET Endpoint Response Examples
GET Responses:
SuccessFailure
{
"status": "found",
"message": "",
"count": <INTEGER>
}
HTTP Status 200
{
"status": "not_found",
"message": "User Id was not found",
"count": ""
}
HTTP Status 404
PUT
/throttle
HTTP MethodURIExample
PUT/api/v1/users/{username}/throttle
https://secureauth.company.com/secureauth2/api/v1/users/jsmith/throttle
Definitions
  • status: The status of user ID provided (found, not_found, invalid, etc.); will always be in response
  • message: Additional information regarding the status; will always be in response
  • count: The value of the integer corresponding to the number of the successful / failed attempt within the rolling time period, which should be 0 (zero)
PUT Endpoint Response Examples
PUT Responses:
SuccessFailure
{
"status": "found",
"message": "",
"count": 0
}
HTTP Status 200
{
"status": "not_found",
"message": "User Id was not found",
"count": ""
}
HTTP Status 404
/otpvalidatethrottle
HTTP MethodURIExample
PUT/api/v1/users/{username}/otpvalidatethrottle
https://secureauth.company.com/secureauth2/api/v1/users/jsmith/otpvalidatethrottle
Definitions
  • status: The status of user ID provided (found, not_found, invalid, etc.); will always be in response
  • message: Additional information regarding the status; will always be in response
  • count: The value of the integer corresponding to the number of the successful / failed attempt within the rolling time period, which should be 0 (zero)
PUT Endpoint Response Examples
PUT Responses:
SuccessFailure
{
"status": "found",
"message": "",
"count": 0
}
HTTP Status 200
{
"status": "not_found",
"message": "User Id was not found",
"count": ""
}
HTTP Status 404
  • No labels