Fixed #16980 - Misc updates to the auth docs. Thanks Preston Holmes for the patch.

docs/topics/auth.txt

@@ -98,12 +98,13 @@ Fields
 
         This doesn't necessarily control whether or not the user can log in.
         Authentication backends aren't required to check for the ``is_active``
-        flag, so if you want to reject a login based on ``is_active`` being
+        flag, and the default backends do not. If you want to reject a login
-        ``False``, it's up to you to check that in your own login view.
+        based on ``is_active`` being ``False``, it's up to you to check that in
-        However, the :class:`~django.contrib.auth.forms.AuthenticationForm`
+        your own login view or a custom authentication backend. However, the
-        used by the :func:`~django.contrib.auth.views.login` view *does*
+        :class:`~django.contrib.auth.forms.AuthenticationForm` used by the
-        perform this check, as do the permission-checking methods such as
+        :func:`~django.contrib.auth.views.login` view (which is the default)
-        :meth:`~models.User.has_perm` and the authentication in the Django
+        *does* perform this check, as do the permission-checking methods such
+        as :meth:`~models.User.has_perm` and the authentication in the Django
         admin. All of those functions/methods will return ``False`` for
         inactive users.
 
@@ -1748,7 +1749,11 @@ By default, :setting:`AUTHENTICATION_BACKENDS` is set to::
 
     ('django.contrib.auth.backends.ModelBackend',)
 
-That's the basic authentication scheme that checks the Django users database.
+That's the basic authentication backend that checks the Django users database
+and queries the builtin permissions. It does not provide protection against
+brute force attacks via any rate limiting mechanism. You may either implement
+your own rate limiting mechanism in a custom auth backend, or use the
+mechanisms provided by most Web servers.
 
 The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same
 username and password is valid in multiple backends, Django will stop
@@ -1768,8 +1773,9 @@ processing at the first positive match.
 Writing an authentication backend
 ---------------------------------
 
-An authentication backend is a class that implements two methods:
+An authentication backend is a class that implements two required methods:
-``get_user(user_id)`` and ``authenticate(**credentials)``.
+``get_user(user_id)`` and ``authenticate(**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 -- and returns a ``User`` object.
@@ -1838,6 +1844,8 @@ object the first time a user authenticates::
             except User.DoesNotExist:
                 return None
 
+.. _authorization_methods:
+
 Handling authorization in custom backends
 -----------------------------------------
 
@@ -1868,13 +1876,16 @@ fairly simply::
                 return False
 
 This gives full permissions to the user granted access in the above example.
-Notice that the backend auth functions all take the user object as an argument,
+Notice that in addition to the same arguments given to the associated
-and they also accept the same arguments given to the associated
+:class:`django.contrib.auth.models.User` functions, the backend auth functions
-:class:`django.contrib.auth.models.User` functions.
+all take the user object, which may be an anonymous user, as an argument.
 
-A full authorization implementation can be found in
+A full authorization implementation can be found in the ``ModelBackend`` class
-`django/contrib/auth/backends.py`_, which is the default backend and queries
+in `django/contrib/auth/backends.py`_, which is the default backend and queries
-the ``auth_permission`` table most of the time.
+the ``auth_permission`` table most of the time. If you wish to provide
+custom behavior for only part of the backend API, you can take advantage of
+Python inheritence and subclass ``ModelBackend`` instead of implementing the
+complete API in a custom backend.
 
 .. _django/contrib/auth/backends.py: https://github.com/django/django/blob/master/django/contrib/auth/backends.py
 
@@ -1890,25 +1901,27 @@ authorize anonymous users to browse most of the site, and many allow anonymous
 posting of comments etc.
 
 Django's permission framework does not have a place to store permissions for
-anonymous users. However, it has a foundation that allows custom authentication
+anonymous users. However, the user object passed to an authentication backend
-backends to specify authorization for anonymous users. This is especially useful
+may be an :class:`django.contrib.auth.models.AnonymousUser` object, allowing
-for the authors of re-usable apps, who can delegate all questions of authorization
+the backend to specify custom authorization behavior for anonymous users. This
-to the auth backend, rather than needing settings, for example, to control
+is especially useful for the authors of re-usable apps, who can delegate all
-anonymous access.
+questions of authorization to the auth backend, rather than needing settings,
+for example, to control anonymous access.
 
+.. _inactive_auth:
 
 Authorization for inactive users
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 1.3
+.. versionchanged:: 1.3
 
 An inactive user is a one that is authenticated but has its attribute
 ``is_active`` set to ``False``. However this does not mean they are not
 authorized to do anything. For example they are allowed to activate their
 account.
 
-The support for anonymous users in the permission system allows for
+The support for anonymous users in the permission system allows for a scenario
-anonymous users to have permissions to do something while inactive
+where anonymous users have permissions to do something while inactive
 authenticated users do not.
 
 Do not forget to test for the ``is_active`` attribute of the user in your own
@@ -1916,9 +1929,11 @@ backend permission methods.
 
 
 Handling object permissions
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Django's permission framework has a foundation for object permissions, though
 there is no implementation for it in the core. That means that checking for
 object permissions will always return ``False`` or an empty list (depending on
-the check performed).
+the check performed). An authentication backend will receive the keyword
+parameters ``obj`` and ``user_obj`` for each object related authorization
+method and can return the object level permission as appropriate.