Fixed #25187 -- Made request available in authentication backends.

5 files changed, 51 insertions, 11 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 8be137e635..a1c55646d0 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -38,6 +38,9 @@ details on these changes.
 
 * ``DatabaseIntrospection.get_indexes()`` will be removed.
 
+* The ``authenticate()`` method of authentication backends will require a
+  ``request`` argument.
+
 .. _deprecation-removed-in-2.0:
 
 2.0
diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt
index f12b16daa0..38f18b6dc8 100644
--- a/docs/ref/contrib/auth.txt
+++ b/docs/ref/contrib/auth.txt
@@ -518,7 +518,7 @@ The following backends are available in :mod:`django.contrib.auth.backends`:
     implement them other than returning an empty set of permissions if
     ``obj is not None``.
 
-    .. method:: authenticate(username=None, password=None, **kwargs)
+    .. method:: authenticate(request, username=None, password=None, **kwargs)
 
         Tries to authenticate ``username`` with ``password`` by calling
         :meth:`User.check_password
@@ -528,6 +528,14 @@ The following backends are available in :mod:`django.contrib.auth.backends`:
         <django.contrib.auth.models.CustomUser.USERNAME_FIELD>`. Returns an
         authenticated user or ``None``.
 
+        ``request`` is an :class:`~django.http.HttpRequest` and may be ``None``
+        if it wasn't provided to :func:`~django.contrib.auth.authenticate`
+        (which passes it on to the backend).
+
+        .. versionchanged:: 1.11
+
+            The ``request`` argument was added.
+
     .. method:: get_user_permissions(user_obj, obj=None)
 
         Returns the set of permission strings the ``user_obj`` has from their
@@ -603,7 +611,7 @@ The following backends are available in :mod:`django.contrib.auth.backends`:
     :class:`~django.contrib.auth.models.User` object is created if not already
     in the database.  Defaults to ``True``.
 
-.. method:: RemoteUserBackend.authenticate(remote_user)
+.. method:: RemoteUserBackend.authenticate(request, remote_user)
 
     The username passed as ``remote_user`` is considered trusted. This method
     simply returns the ``User`` object with the given username, creating a new
@@ -614,6 +622,10 @@ The following backends are available in :mod:`django.contrib.auth.backends`:
     ``False`` and a ``User`` object with the given username is not found in the
     database.
 
+    ``request`` is an :class:`~django.http.HttpRequest` and may be ``None`` if
+    it wasn't provided to :func:`~django.contrib.auth.authenticate` (which
+    passes it on to the backend).
+
 .. method:: RemoteUserBackend.clean_username(username)
 
    Performs any cleaning on the ``username`` (e.g. stripping LDAP DN
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index 7b5bcc450f..a6edfcdf25 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -113,6 +113,10 @@ Minor features
   allows using the authentication system :ref:`without any of the built-in
   models <using-auth-without-models>`.
 
+* The ``HttpRequest`` is now passed to :func:`~django.contrib.auth.authenticate`
+  which in turn passes it to the authentication backend if it accepts a
+  ``request`` argument.
+
 :mod:`django.contrib.contenttypes`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -556,3 +560,7 @@ Miscellaneous
 
 * ``DatabaseIntrospection.get_indexes()`` is deprecated in favor of
   ``DatabaseIntrospection.get_constraints()``.
+
+* :func:`~django.contrib.auth.authenticate` now passes a ``request`` argument
+  to the ``authenticate()`` method of authentication backends. Support for
+  methods that don't accept ``request`` will be removed in Django 2.1.
diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt
index d102d9939b..085f74fcde 100644
--- a/docs/topics/auth/customizing.txt
+++ b/docs/topics/auth/customizing.txt
@@ -89,25 +89,26 @@ Writing an authentication backend
 ---------------------------------
 
 An authentication backend is a class that implements two required methods:
-``get_user(user_id)`` and ``authenticate(**credentials)``, as well as a set of
-optional permission related :ref:`authorization methods <authorization_methods>`.
+``get_user(user_id)`` and ``authenticate(request, **credentials)``, as well as
+a set of optional permission related :ref:`authorization methods
+<authorization_methods>`.
 
 The ``get_user`` method takes a ``user_id`` -- which could be a username,
 database ID or whatever, but has to be the primary key of your ``User`` object
 -- and returns a ``User`` object.
 
-The ``authenticate`` method takes credentials as keyword arguments. Most of
-the time, it'll just look like this::
+The ``authenticate`` method takes a ``request`` argument and credentials as
+keyword arguments. Most of the time, it'll just look like this::
 
     class MyBackend(object):
-        def authenticate(self, username=None, password=None):
+        def authenticate(self, request, username=None, password=None):
             # Check the username/password and return a User.
             ...
 
 But it could also authenticate a token, like so::
 
     class MyBackend(object):
-        def authenticate(self, token=None):
+        def authenticate(self, request, token=None):
             # Check the token and return a User.
             ...
 
@@ -115,6 +116,10 @@ Either way, ``authenticate`` should check the credentials it gets, and it
 should return a ``User`` object that matches those credentials, if the
 credentials are valid. If they're not valid, it should return ``None``.
 
+``request`` is an :class:`~django.http.HttpRequest` and may be ``None`` if it
+wasn't provided to :func:`~django.contrib.auth.authenticate` (which passes it
+on to the backend).
+
 The Django admin is tightly coupled to the Django :ref:`User object
 <user-objects>`. The best way to deal with this is to create a Django ``User``
 object for each user that exists for your backend (e.g., in your LDAP
@@ -140,7 +145,7 @@ object the first time a user authenticates::
         ADMIN_PASSWORD = 'pbkdf2_sha256$30000$Vo0VlMnkR4Bk$qEvtdyZRWTcOsCnI/oQ7fVOu1XAURIZYoOZ3iq8Dr4M='
         """
 
-        def authenticate(self, username=None, password=None):
+        def authenticate(self, request, username=None, password=None):
             login_valid = (settings.ADMIN_LOGIN == username)
             pwd_valid = check_password(password, settings.ADMIN_PASSWORD)
             if login_valid and pwd_valid:
@@ -163,6 +168,11 @@ object the first time a user authenticates::
             except User.DoesNotExist:
                 return None
 
+.. versionchanged:: 1.11
+
+    The ``request`` parameter was added to ``authenticate()`` and support for
+    backends that don't accept it will be removed in Django 2.1.
+
 .. _authorization_methods:
 
 Handling authorization in custom backends
diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index a484a89d6d..310f09e322 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -115,7 +115,7 @@ Changing a user's password will log out all their sessions. See
 Authenticating users
 --------------------
 
-.. function:: authenticate(\**credentials)
+.. function:: authenticate(request=None, \**credentials)
 
     Use :func:`~django.contrib.auth.authenticate()` to verify a set of
     credentials. It takes credentials as keyword arguments, ``username`` and
@@ -133,6 +133,13 @@ Authenticating users
         else:
             # No backend authenticated the credentials
 
+    ``request`` is an optional :class:`~django.http.HttpRequest` which is
+    passed on the ``authenticate()`` method of the authentication backends.
+
+    .. versionchanged:: 1.11
+
+        The optional ``request`` argument was added.
+
     .. note::
 
         This is a low level way to authenticate a set of credentials; for
@@ -342,7 +349,7 @@ If you have an authenticated user you want to attach to the current session
         def my_view(request):
             username = request.POST['username']
             password = request.POST['password']
-            user = authenticate(username=username, password=password)
+            user = authenticate(request, username=username, password=password)
             if user is not None:
                 login(request, user)
                 # Redirect to a success page.