Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[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
@timgraham timgraham authored
Showing with 40 additions and 25 deletions.
  1. +40 −25 docs/topics/auth.txt
View
65 docs/topics/auth.txt
@@ -101,12 +101,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
- ``False``, it's up to you to check that in your own login view.
- However, the :class:`~django.contrib.auth.forms.AuthenticationForm`
- used by the :func:`~django.contrib.auth.views.login` view *does*
- perform this check, as do the permission-checking methods such as
- :meth:`~models.User.has_perm` and the authentication in the Django
+ flag, and the default backends do not. If you want to reject a login
+ based on ``is_active`` being ``False``, it's up to you to check that in
+ your own login view or a custom authentication backend. However, the
+ :class:`~django.contrib.auth.forms.AuthenticationForm` used by the
+ :func:`~django.contrib.auth.views.login` view (which is the default)
+ *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.
@@ -1781,7 +1782,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
@@ -1801,8 +1806,9 @@ processing at the first positive match.
Writing an authentication backend
---------------------------------
-An authentication backend is a class that implements two methods:
-``get_user(user_id)`` and ``authenticate(**credentials)``.
+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>`.
The ``get_user`` method takes a ``user_id`` -- which could be a username,
database ID or whatever -- and returns a ``User`` object.
@@ -1873,6 +1879,8 @@ object the first time a user authenticates::
except User.DoesNotExist:
return None
+.. _authorization_methods:
+
Handling authorization in custom backends
-----------------------------------------
@@ -1903,13 +1911,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,
-and they also accept the same arguments given to the associated
-:class:`django.contrib.auth.models.User` functions.
+Notice that in addition to the same arguments given to the associated
+:class:`django.contrib.auth.models.User` functions, the backend auth functions
+all take the user object, which may be an anonymous user, as an argument.
-A full authorization implementation can be found in
-`django/contrib/auth/backends.py`_, which is the default backend and queries
-the ``auth_permission`` table most of the time.
+A full authorization implementation can be found in the ``ModelBackend`` class
+in `django/contrib/auth/backends.py`_, which is the default backend and queries
+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://code.djangoproject.com/browser/django/trunk/django/contrib/auth/backends.py
@@ -1927,25 +1938,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
-backends to specify authorization for anonymous users. This is especially useful
-for the authors of re-usable apps, who can delegate all questions of authorization
-to the auth backend, rather than needing settings, for example, to control
-anonymous access.
+anonymous users. However, the user object passed to an authentication backend
+may be an :class:`django.contrib.auth.models.AnonymousUser` object, allowing
+the backend to specify custom authorization behavior for anonymous users. This
+is especially useful for the authors of re-usable apps, who can delegate all
+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
-anonymous users to have permissions to do something while inactive
+The support for anonymous users in the permission system allows for a scenario
+where anonymous users have permissions to do something while inactive
authenticated users do not.
To enable this on your own backend, you must set the class attribute
@@ -1960,9 +1973,11 @@ passed to the authorization 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.
Please sign in to comment.
Something went wrong with that request. Please try again.