Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.4.X] Fixed #16980 - Misc updates to the auth docs. Thanks Preston …

…Holmes for the patch.

Backport of 865ff32 from master
  • Loading branch information...
commit c54034a2ad9e0ebf918530fa4b8f11e4ea0f489e 1 parent 49f9bb2
Tim Graham authored August 04, 2012

Showing 1 changed file with 40 additions and 25 deletions. Show diff stats Hide diff stats

  1. 65  docs/topics/auth.txt
65  docs/topics/auth.txt
@@ -101,12 +101,13 @@ Fields
101 101
 
102 102
         This doesn't necessarily control whether or not the user can log in.
103 103
         Authentication backends aren't required to check for the ``is_active``
104  
-        flag, so if you want to reject a login based on ``is_active`` being
105  
-        ``False``, it's up to you to check that in your own login view.
106  
-        However, the :class:`~django.contrib.auth.forms.AuthenticationForm`
107  
-        used by the :func:`~django.contrib.auth.views.login` view *does*
108  
-        perform this check, as do the permission-checking methods such as
109  
-        :meth:`~models.User.has_perm` and the authentication in the Django
  104
+        flag, and the default backends do not. If you want to reject a login
  105
+        based on ``is_active`` being ``False``, it's up to you to check that in
  106
+        your own login view or a custom authentication backend. However, the
  107
+        :class:`~django.contrib.auth.forms.AuthenticationForm` used by the
  108
+        :func:`~django.contrib.auth.views.login` view (which is the default)
  109
+        *does* perform this check, as do the permission-checking methods such
  110
+        as :meth:`~models.User.has_perm` and the authentication in the Django
110 111
         admin. All of those functions/methods will return ``False`` for
111 112
         inactive users.
112 113
 
@@ -1781,7 +1782,11 @@ By default, :setting:`AUTHENTICATION_BACKENDS` is set to::
1781 1782
 
1782 1783
     ('django.contrib.auth.backends.ModelBackend',)
1783 1784
 
1784  
-That's the basic authentication scheme that checks the Django users database.
  1785
+That's the basic authentication backend that checks the Django users database
  1786
+and queries the builtin permissions. It does not provide protection against
  1787
+brute force attacks via any rate limiting mechanism. You may either implement
  1788
+your own rate limiting mechanism in a custom auth backend, or use the
  1789
+mechanisms provided by most Web servers.
1785 1790
 
1786 1791
 The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same
1787 1792
 username and password is valid in multiple backends, Django will stop
@@ -1801,8 +1806,9 @@ processing at the first positive match.
1801 1806
 Writing an authentication backend
1802 1807
 ---------------------------------
1803 1808
 
1804  
-An authentication backend is a class that implements two methods:
1805  
-``get_user(user_id)`` and ``authenticate(**credentials)``.
  1809
+An authentication backend is a class that implements two required methods:
  1810
+``get_user(user_id)`` and ``authenticate(**credentials)``, as well as a set of
  1811
+optional permission related :ref:`authorization methods <authorization_methods>`.
1806 1812
 
1807 1813
 The ``get_user`` method takes a ``user_id`` -- which could be a username,
1808 1814
 database ID or whatever -- and returns a ``User`` object.
@@ -1873,6 +1879,8 @@ object the first time a user authenticates::
1873 1879
             except User.DoesNotExist:
1874 1880
                 return None
1875 1881
 
  1882
+.. _authorization_methods:
  1883
+
1876 1884
 Handling authorization in custom backends
1877 1885
 -----------------------------------------
1878 1886
 
@@ -1903,13 +1911,16 @@ fairly simply::
1903 1911
                 return False
1904 1912
 
1905 1913
 This gives full permissions to the user granted access in the above example.
1906  
-Notice that the backend auth functions all take the user object as an argument,
1907  
-and they also accept the same arguments given to the associated
1908  
-:class:`django.contrib.auth.models.User` functions.
  1914
+Notice that in addition to the same arguments given to the associated
  1915
+:class:`django.contrib.auth.models.User` functions, the backend auth functions
  1916
+all take the user object, which may be an anonymous user, as an argument.
1909 1917
 
1910  
-A full authorization implementation can be found in
1911  
-`django/contrib/auth/backends.py`_, which is the default backend and queries
1912  
-the ``auth_permission`` table most of the time.
  1918
+A full authorization implementation can be found in the ``ModelBackend`` class
  1919
+in `django/contrib/auth/backends.py`_, which is the default backend and queries
  1920
+the ``auth_permission`` table most of the time. If you wish to provide
  1921
+custom behavior for only part of the backend API, you can take advantage of
  1922
+Python inheritence and subclass ``ModelBackend`` instead of implementing the
  1923
+complete API in a custom backend.
1913 1924
 
1914 1925
 .. _django/contrib/auth/backends.py: https://code.djangoproject.com/browser/django/trunk/django/contrib/auth/backends.py
1915 1926
 
@@ -1927,25 +1938,27 @@ authorize anonymous users to browse most of the site, and many allow anonymous
1927 1938
 posting of comments etc.
1928 1939
 
1929 1940
 Django's permission framework does not have a place to store permissions for
1930  
-anonymous users. However, it has a foundation that allows custom authentication
1931  
-backends to specify authorization for anonymous users. This is especially useful
1932  
-for the authors of re-usable apps, who can delegate all questions of authorization
1933  
-to the auth backend, rather than needing settings, for example, to control
1934  
-anonymous access.
  1941
+anonymous users. However, the user object passed to an authentication backend
  1942
+may be an :class:`django.contrib.auth.models.AnonymousUser` object, allowing
  1943
+the backend to specify custom authorization behavior for anonymous users. This
  1944
+is especially useful for the authors of re-usable apps, who can delegate all
  1945
+questions of authorization to the auth backend, rather than needing settings,
  1946
+for example, to control anonymous access.
1935 1947
 
  1948
+.. _inactive_auth:
1936 1949
 
1937 1950
 Authorization for inactive users
1938 1951
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1939 1952
 
1940  
-.. versionadded:: 1.3
  1953
+.. versionchanged:: 1.3
1941 1954
 
1942 1955
 An inactive user is a one that is authenticated but has its attribute
1943 1956
 ``is_active`` set to ``False``. However this does not mean they are not
1944 1957
 authorized to do anything. For example they are allowed to activate their
1945 1958
 account.
1946 1959
 
1947  
-The support for anonymous users in the permission system allows for
1948  
-anonymous users to have permissions to do something while inactive
  1960
+The support for anonymous users in the permission system allows for a scenario
  1961
+where anonymous users have permissions to do something while inactive
1949 1962
 authenticated users do not.
1950 1963
 
1951 1964
 To enable this on your own backend, you must set the class attribute
@@ -1960,9 +1973,11 @@ passed to the authorization methods.
1960 1973
 
1961 1974
 
1962 1975
 Handling object permissions
1963  
----------------------------
  1976
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
1964 1977
 
1965 1978
 Django's permission framework has a foundation for object permissions, though
1966 1979
 there is no implementation for it in the core. That means that checking for
1967 1980
 object permissions will always return ``False`` or an empty list (depending on
1968  
-the check performed).
  1981
+the check performed). An authentication backend will receive the keyword
  1982
+parameters ``obj`` and ``user_obj`` for each object related authorization
  1983
+method and can return the object level permission as appropriate.

0 notes on commit c54034a

Please sign in to comment.
Something went wrong with that request. Please try again.