Skip to main content

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:

  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

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

/api/v1/users/{username}/throttle

https://secureauth.company.com/secureauth2/api/v1/users/jsmith/throttle

/otpvalidatethrottle

HTTP Method

URI

Example

PUT

/api/v1/users/{username}/otpvalidatethrottle

https://secureauth.company.com/secureauth2/api/v1/users/jsmith/otpvalidatethrottle