Wt::Auth::AuthThrottle Class Reference

Class with helper functions to define throttling behaviour. More...

#include <Wt/Auth/AuthThrottle.h>

Public Member Functions
	AuthThrottle ()=default
	Default constructor.
virtual	~AuthThrottle ()=default
	Default destructor.
virtual int	delayForNextAttempt (const User &user) const
	Returns the amount of seconds the given User has to wait for the next authentication attempt. More...
virtual int	getAuthenticationThrottle (int failedAttempts) const
	Returns the number of seconds a user needs to wait between two authentication attempts, given the amount of failed attempts since the last successful login. More...
virtual void	initializeThrottlingMessage (WInteractWidget *button)
	Prepare a widget for showing client-side updated throttling message. More...
virtual void	updateThrottlingMessage (WInteractWidget *button, int delay)
	Show the count-down message and disable the widget for the given delay. More...

Detailed Description

Class with helper functions to define throttling behaviour.

During authentication, it may be desirable to limit the number of submissions a client can perform in order to prevent brute force attacks. This class allows developers to manage the throttling behaviour. The main functions offered by this class are:

1. compute how long a user has to wait before the next authentication attempt
2. offer methods to show interactive feedback (count-down timer) on the waiting time to the user

This class is used in PasswordService and in AbstractMfaProcess. By specializing this class, you can change Wt's behaviour related to authentication throttling.

Throttling has to be enabled; it is enabled by calling PasswordService::setAttemptThrottlingEnabled() for password authentication, or AuthService::setMfaThrottleEnabled() for MFA tokens.

By default this is disabled in both cases.

Note

for MFA one can also call Mfa::AbstractMfaProcess::setMfaThrottle() directly. The AuthService state can be used for the default TotpProcess implementation, or to manage your own state in case of a custom MFA approach.

Member Function Documentation

delayForNextAttempt()

int Wt::Auth::AuthThrottle::delayForNextAttempt ( const User &  user ) const

virtual

Returns the amount of seconds the given User has to wait for the next authentication attempt.

The default implementation queries the given user object for the last login attempt (User::lastLoginAttempt()) and the amount of consecutive failed logins (User::failedLoginAttempts()), to compute the remaining wait time for this user. This is calculated using getAuthenticationThrottle() and the current server time.

Since the User object normally fetches this data from a database, throttling works across different sessions, i.e. opening a new tab to get around throttling will not work.

This function returns 0 if a new attempt is permitted, or the amount of seconds the user has to wait for the next attempt.

See also

AbstractPasswordService::attemptThrottlingEnabled(), Mfa::AbstractMfaProcess::setMfaThrottle()

getAuthenticationThrottle()

int Wt::Auth::AuthThrottle::getAuthenticationThrottle ( int  failedAttempts ) const

virtual

Returns the number of seconds a user needs to wait between two authentication attempts, given the amount of failed attempts since the last successful login.

The returned value is in seconds.

The default implementation returns the following:

• failedAttempts == 0: 0
• failedAttempts == 1: 1
• failedAttempts == 2: 5
• failedAttempts == 3: 10
• failedAttempts > 3: 25

initializeThrottlingMessage()

void Wt::Auth::AuthThrottle::initializeThrottlingMessage ( WInteractWidget *  button )

virtual

Prepare a widget for showing client-side updated throttling message.

This method loads the necessary JavaScript and initializes a widget in preparation of calls to updateThrottlingMessage().

The widget's inner HTML will be replaced by a count-down message, defined in Wt.Auth.throttle-retry, for the duration of the wait time. In addition, the widget is disabled, so that the user cannot click it. When the count-down reaches 0, The original content of the widget is restored and the widget is re-enabled.

This will work with widgets such as buttons or anchors, which are usually used to implement button-style functionality.

See also

updateThrottlingMessage()

updateThrottlingMessage()

void Wt::Auth::AuthThrottle::updateThrottlingMessage ( WInteractWidget *  button, int  delay  )

virtual

Show the count-down message and disable the widget for the given delay.

The delay is specified in seconds.

This method is called after an attempt to authenticate, to inform the user with a client-side count-down indicator in the widget. This method should disable the widget, and show a count-down text to the user.

Each second the counter will be updated, and the number of seconds to wait for will decrease by one, eventually enabling the widget again.

You need to call configureThrottling() before you can do this. See the documentation of configureThrottling() for more information on the default behaviour of this method.

Note

Throttling delay must always be verified server-side

See also

delayForNextAttempt()