RFC: Rate limiting / throttling support

[maximelebastard]

Summary

Lucia currently allows an unlimited amount of login attempts for an account. That means it is your responsibility (typically using a WAF or a middleware) to limit the login attempts that can be made on a user account. This could be tricky to configure, and it often does not offer a satisfying fine-grain monitoring and control when it is done at an infrastructure level.

Potentially new concept added

A new Attempt model may be added in Lucia to represent a failed attempt of access to an account. It would be linked to a Key and not directly to the User.

Attempts counting

When trying to sign in, the counting of previous attempts could take two forms:

• KEY_OR_IP - Count the attempts for the key OR the requester IP: We would count attempts made on the targeted account OR by the requester IP. This could be useful to block dummy-bots trying multiple combination on multiple accounts (ie: bots trying leaked credentials). It would only work with dummy bots, the proper way to prevent login on leaked accounts would be a Multi-Factor authentication.
• KEY_ONLY - Count only the attempts for the key: We would only count the attempts made on a user key (existing or not - only limiting existing account would be a hint for an attacker). This is the least security that can be done as IP can rotate on elaborated attacks, it is not enough.

I still wonder if having a setting on that is useful. I may only provide the KEY_ONLY option. Any serious attacker is able to rotate his IP so this is not a criteria to identify an attack. And for bots trying leaked passwords, if it has the correct username and password the only way to prevent the attack would be MFA - rate limiting is a very weak and random safety on that type of attack.
Moreover, having to support both filters on database could make implementing this on redis more difficult as two collection would have to be maintained.

Mitigation method

When the maximum number of attempts is reached, we could provide two ways to block an attacker:

• THROTTLE mode: The user has to wait a given time between two attempts. This time is multiplied by a factor (x2 by default) for each attmept (ie: 1s, 2s, 4s, 8s, 16s, 32s, 1m04s…). This is the method used by AWS Cognito for example.
• LIMIT mode: The user has N attempts allowed for in the last P seconds. When the amount of attempts exceeds N, the user is no longer allowed to try to login util he waits for P. This is an older method used by frameworks like Laravel. If set to an extended period of time, it also allows to definitely block an account until manual action - for paranoids or really highly-secure needs.

Attempts would be stored in your database using the existing adapters. Attempts would have a time-to-live (1 month by default). Outdated attempts are automatically cleaned.

New options

The following new options could be provided to setup the rate limiting

type Configuration = {
	// ... existing configuration
        attempts?: {
		// Criteria used to retreive and count user attempts
		// - KEY_ONLY will only count attempts on the target account
		// - KEY_OR_IP will count attempts on the target account and other attempts made by the same IP address
		criteria?: "KEY_ONLY" | "KEY_OR_IP";
		// The Time-To-Live on an attempt, in seconds.
		// A null value will retain attempts indefinitely.
		// (default: 2 592 000 seconds = 30 days)
		attemptTtl?: number | null;
		// Behavior to adopt when too many attempts are made (default: THROTTLE)
		//  - THROTTLE: Forces the user to wait before two attempts. Waiting time is multiplied at each failed attempt.
		//  - lIMIT: After a given amount of attempts in a given amount of time, the user will have to wait to try again.
		mitigationPolicy?: "THROTTLE"|"LIMIT";
		throttleOptions?: {
			// The seconds to wait before a new attempt at the first failed attempt (default: 1 second)
			initialDelay?: number;
			// The factor of multiplication of the delay per each failed attempt (default: x2)
			delayFactor?: number;
		},
		limitOptions?: {
			// The period of evaluation of the attempts (default: 3600 = 1 hour)
			period?: number;
			// The amount of maximum login attempts in a period (default: 5)
			maxAttempts?: number;
		},

	}
}

Evolution of the login process

The login process would call two new methods checkAttempt before any password check - and registerAttempt for any failed attempt.

A new error AUTH_TOO_MANY_ATTEMPTS would be thrown in case of unsuccessful checkAttempts

function handleLogin(username: string, password: string, ipAddress: string) {
  try {
    // check attempts on that key or that IP. Wait x2 per missed attempt, starting from 1
    await auth.checkAttempts("username", username.toLowerCase(), ipAddress);

    // find user by key
    const key = await auth.useKey("username", username.toLowerCase(), password);

    // validate password
    await auth.useKey("username", username.toLowerCase(), password);

    // create and store the session
    const session = await auth.createSession({
      userId: key.userId,
      attributes: {},
    });
    const authRequest = auth.handleRequest(req, res);
    authRequest.setSession(session);
    redirect("/home");
  } catch (e) {
    if (
      e instanceof LuciaError &&
      (e.message === "AUTH_INVALID_KEY_ID" ||
        e.message === "AUTH_INVALID_PASSWORD")
    ) {
      // if the attempt is unsuccessful, store it for a later use
      await auth.registerAttempt("username", username.toLowerCase(), ipAddress);

      // give a wrong credentials feedback to the user
      redirect("/login?wrongpassword=true");
    }

    if (e instanceof LuciaError && e.message === "AUTH_TOO_MANY_ATTEMPTS") {
      // optional: get how much time the user has to wait before a new attempt
      const delay = await auth.getAttemptDelay(key, ipAddress); // returns a time in seconds

      // give a wrong credentials feedback to the user
      redirect(`/login?throttled=true&throttleDelay=${delay}`);
    }
  }
}

This RFC follows the draft #881

[cameronpcampbell]

In my opinion Lucia shouldn't handle throttling as it is out of scope for what lucia is.

Throttling should be done outside of Lucia, ideally at the beginning of the requests, for example:

function login() {
  -- throttle logic here
  
  -- lucia stuff here
}

function callback() {
  -- throttle logic here
  
  -- lucia stuff here
}