Mitigate login throttle bypasses in docs

This commit mitigates rate limit bypasses in the configuration
docs by normalizing the email throttle key. (The normalization process
used is the same as used by the Clearance gem.)

---

Often an authentication process normalizes email addresses and usernames
before look up, say by downcasing and removing any whitespace.

Throttles that do not perform the same normalization are vulnerable
to rate limit bypasses.

For example, an attacker can bypass a vulnerable throttle by using
unlimited case and whitespace variants for the same email address:

- Variant 1: `victim@example.org`
- Variant 2: `victim@example. org` (one whitespace)
- Variant 3: `victim@example.  org` (two whitespaces)
- Variant 4: `ViCtIm@eXaMpLe.org`
- etc, etc.

All of these variants resolve to the same email address, but allow
an attacker to bypass a vulnerable throttle. To mitigate, the email
throttle key should be normalized using the same logic the
authentication process uses for normalizing emails.

(cherry picked from commit 03926e0b75)

README.md

@@ -263,10 +263,12 @@ Rack::Attack.throttle("requests by ip", limit: 5, period: 2) do |request|
 end
 
 # Throttle login attempts for a given email parameter to 6 reqs/minute
-# Return the email as a discriminator on POST /login requests
+# Return the *normalized* email as a discriminator on POST /login requests
 Rack::Attack.throttle('limit logins per email', limit: 6, period: 60) do |req|
   if req.path == '/login' && req.post?
-    req.params['email']
+    # Normalize the email, using the same logic as your authentication process, to
+    # protect against rate limit bypasses.
+    req.params['email'].to_s.downcase.gsub(/\s+/, "")
   end
 end
 

docs/example_configuration.md

@@ -53,7 +53,7 @@ class Rack::Attack
 
   # Throttle POST requests to /login by email param
   #
-  # Key: "rack::attack:#{Time.now.to_i/:period}:logins/email:#{req.email}"
+  # Key: "rack::attack:#{Time.now.to_i/:period}:logins/email:#{normalized_email}"
   #
   # Note: This creates a problem where a malicious user could intentionally
   # throttle logins for another user and force their login requests to be
@@ -61,8 +61,9 @@ class Rack::Attack
   # on wood!)
   throttle("logins/email", limit: 5, period: 20.seconds) do |req|
     if req.path == '/login' && req.post?
-      # return the email if present, nil otherwise
-      req.params['email'].presence
+      # Normalize the email, using the same logic as your authentication process, to
+      # protect against rate limit bypasses. Return the normalized email if present, nil otherwise.
+      req.params['email'].to_s.downcase.gsub(/\s+/, "").presence
     end
   end
 

examples/rack_attack.rb

@@ -13,8 +13,10 @@ Rack::Attack.throttle "logins/ip", limit: 2, period: 1 do |req|
 end
 
 # Throttle login attempts per email, 10/minute/email
+# Normalize the email, using the same logic as your authentication process, to
+# protect against rate limit bypasses.
 Rack::Attack.throttle "logins/email", limit: 2, period: 60 do |req|
-  req.post? && req.path == "/login" && req.params['email']
+  req.post? && req.path == "/login" && req.params['email'].to_s.downcase.gsub(/\s+/, "")
 end
 
 # blocklist bad IPs from accessing admin pages