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

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.

Note

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

Note

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

Warning

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 Method	URI	Example
GET	/api/v1/users/{username}/throttle	https://secureauth.company.com/secureauth2/api/v1/users/jsmith/throttle

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

/otpvalidatethrottle

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

Success	Failure
GET Responses:
{ "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	Failure
PUT Responses:
{ "status": "found", "message": "", "count": 0 } HTTP Status 200	{ "status": "not_found", "message": "User Id was not found", "count": "" } HTTP Status 404

/otpvalidatethrottle

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

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

Multi-Factor Throttling Authentication API Guide

Introduction

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

Note

Prerequisites

SecureAuth IdP Web Admin

Multi-Factor Methods

Note

Warning

Endpoints

GET

/throttle

/otpvalidatethrottle

PUT

/throttle

/otpvalidatethrottle

Search results