mirror of
https://github.com/django/django.git
synced 2024-12-24 18:16:19 +00:00
Fixed #16980 - Misc updates to the auth docs. Thanks Preston Holmes for the patch.
This commit is contained in:
parent
542c20b382
commit
865ff32b84
@ -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
|
||||
``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.
|
||||
|
||||
@ -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:
|
||||
``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.
|
||||
@ -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,
|
||||
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://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
|
||||
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.
|
||||
|
||||
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.
|
||||
|
Loading…
Reference in New Issue
Block a user