[1.7.x] Added a note regarding django.contrib.auth.authenticate.

Thanks Josh Brown for the suggestion.

Backport of ae5b662796 from master

1 files changed, 10 insertions, 0 deletions

diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index 24eaf064b6..6da34321f1 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -142,6 +142,16 @@ Authenticating Users
             # the authentication system was unable to verify the username and password
             print("The username and password were incorrect.")
 
+    .. note::
+
+        This is a low level way to authenticate a set of credentials; for
+        example, it's used by the
+        :class:`~django.contrib.auth.middleware.RemoteUserMiddleware`. Unless
+        you are writing your own authentication system, you probably won't use
+        this. Rather if you are looking for a way to limit access to logged in
+        users, see the :func:`~django.contrib.auth.decorators.login_required`
+        decorator.
+
 .. _topic-authorization:
 
 Permissions and Authorization