Ticket #16980: auth_docs_cleanup.diff

File auth_docs_cleanup.diff, 5.5 KB (added by Preston Holmes, 7 years ago)
  • docs/topics/auth.txt

    diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt
    index ecbc2f2..7b3c0a6 100644
    a b By default, :setting:`AUTHENTICATION_BACKENDS` is set to:: 
    16331633
    16341634    ('django.contrib.auth.backends.ModelBackend',)
    16351635
    1636 That's the basic authentication scheme that checks the Django users database.
     1636That's the basic authentication backend that checks the Django users database
     1637and queries the builtin permissions, it does not provide, out-of-the-box
     1638protection against brute force attacks via any rate limiting mechanism.
    16371639
    16381640The order of :setting:`AUTHENTICATION_BACKENDS` matters, so if the same
    16391641username and password is valid in multiple backends, Django will stop
    processing at the first positive match. 
    16521654Writing an authentication backend
    16531655---------------------------------
    16541656
    1655 An authentication backend is a class that implements two methods:
    1656 ``get_user(user_id)`` and ``authenticate(**credentials)``.
     1657An authentication backend is a class that implements two required methods:
     1658``get_user(user_id)`` and ``authenticate(**credentials)``, as well as a set of
     1659optional permission related :ref:`authorization methods <authorization_methods>`.
    16571660
    16581661The ``get_user`` method takes a ``user_id`` -- which could be a username,
    16591662database ID or whatever -- and returns a ``User`` object.
    object the first time a user authenticates:: 
    16991702        ADMIN_PASSWORD = 'sha1$4e987$afbcf42e21bd417fb71db8c66b321e9fc33051de'
    17001703        """
    17011704
     1705        # required transient attribute for auth backends
     1706        # (see deprecation timeline)
    17021707        supports_inactive_user = False
    17031708
    17041709        def authenticate(self, username=None, password=None):
    object the first time a user authenticates:: 
    17241729            except User.DoesNotExist:
    17251730                return None
    17261731
     1732.. _authorization_methods:
     1733
    17271734Handling authorization in custom backends
    17281735-----------------------------------------
    17291736
    fairly simply:: 
    17541761                return False
    17551762
    17561763This gives full permissions to the user granted access in the above example.
    1757 Notice that the backend auth functions all take the user object as an argument,
    1758 and they also accept the same arguments given to the associated
    1759 :class:`django.contrib.auth.models.User` functions.
     1764Notice that in addition to the same arguments given to the associated
     1765:class:`django.contrib.auth.models.User` functions, the backend auth functions
     1766all take the user object, which may be an anonymous user, as an argument.
    17601767
    1761 A full authorization implementation can be found in
    1762 `django/contrib/auth/backends.py`_, which is the default backend and queries
    1763 the ``auth_permission`` table most of the time.
     1768A full authorization implementation can be found in the ``ModelBackend`` class
     1769in `django/contrib/auth/backends.py`_, which is the default backend and queries
     1770the ``auth_permission`` table most of the time. If you wish to provide
     1771custom behavior for only part of the backend API, you can take advantage of
     1772Python inheritence and subclass ``ModelBackend`` instead of implementing the
     1773complete API in a custom backend.
    17641774
    17651775.. _django/contrib/auth/backends.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/backends.py
    17661776
    authorize anonymous users to browse most of the site, and many allow anonymous 
    17781788posting of comments etc.
    17791789
    17801790Django's permission framework does not have a place to store permissions for
    1781 anonymous users. However, it has a foundation that allows custom authentication
    1782 backends to specify authorization for anonymous users. This is especially useful
    1783 for the authors of re-usable apps, who can delegate all questions of authorization
    1784 to the auth backend, rather than needing settings, for example, to control
    1785 anonymous access.
     1791anonymous users. However, the user object passed to an authentication backend
     1792may be an :class:`django.contrib.auth.models.AnonymousUser` object, allowing
     1793the backend to specify custom authorization behavior for anonymous users. This
     1794is especially useful for the authors of re-usable apps, who can delegate all
     1795questions of authorization to the auth backend, rather than needing settings,
     1796for example, to control anonymous access.
    17861797
     1798.. _inactive_auth:
    17871799
    17881800Authorization for inactive users
    17891801~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    17901802
    1791 .. versionadded:: 1.3
     1803.. versionchanged:: 1.3
    17921804
    17931805An inactive user is a one that is authenticated but has its attribute
    17941806``is_active`` set to ``False``. However this does not mean they are not
    17951807authorized to do anything. For example they are allowed to activate their
    17961808account.
    17971809
    1798 The support for anonymous users in the permission system allows for
    1799 anonymous users to have permissions to do something while inactive
     1810The support for anonymous users in the permission system allows for a scenario
     1811where anonymous users have permissions to do something while inactive
    18001812authenticated users do not.
    18011813
    18021814To enable this on your own backend, you must set the class attribute
    passed to the authorization methods. 
    18111823
    18121824
    18131825Handling object permissions
    1814 ---------------------------
     1826~~~~~~~~~~~~~~~~~~~~~~~~~~~
    18151827
    18161828Django's permission framework has a foundation for object permissions, though
    18171829there is no implementation for it in the core. That means that checking for
    18181830object permissions will always return ``False`` or an empty list (depending on
    1819 the check performed).
     1831the check performed). An authentication backend will receive the keyword
     1832parameters ``obj`` and ``user_obj`` for each object related authorization
     1833method and can return the object level permission as appropriate.
Back to Top