added clarification on source_ip and X-Forwarded-For

authserv/server.py

@@ -20,6 +20,16 @@ def _auth(username, service, shard, password, otp_token, source_ip):
     return auth.authenticate(user, service, password, otp_token)
 
 
+# Quick clarification on the rate limits: 'username' is the one that's
+# going to be used all the time, while the X-Forwarded-For header on
+# the request is only going to be present for those authentication
+# requests where we have knowledge of the original users' IP (remember
+# that 'source_ip' can sometimes be the server address or localhost).
+# For instance, authentication requests that come from PAM usually do
+# not have knowledge of the users' IP address, as the protocols for
+# which we use PAM handlers do not support forwarding of the IP
+# address. So we're practically only going to use X-Forwarded-For for
+# requests that reach our frontends via HTTP.
 @app.route('/api/1/auth', methods=('POST',))
 @ratelimit_http_request(key_from_request(header='HTTP_X_FORWARDED_FOR'),
                         count=10, period=60)