2016-01-03 10:56:22 +00:00
|
|
|
|
=======================
|
2008-08-23 22:25:40 +00:00
|
|
|
|
``django.contrib.auth``
|
|
|
|
|
=======================
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
This document provides API reference material for the components of Django's
|
|
|
|
|
authentication system. For more details on the usage of these components or
|
|
|
|
|
how to customize authentication and authorization see the :doc:`authentication
|
|
|
|
|
topic guide </topics/auth/index>`.
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: django.contrib.auth
|
|
|
|
|
|
2016-01-24 21:26:11 +00:00
|
|
|
|
``User`` model
|
|
|
|
|
==============
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2020-04-06 05:41:43 +00:00
|
|
|
|
.. class:: models.User
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
Fields
|
|
|
|
|
------
|
|
|
|
|
|
|
|
|
|
.. class:: models.User
|
2020-04-06 05:41:43 +00:00
|
|
|
|
:noindex:
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
:class:`~django.contrib.auth.models.User` objects have the following
|
|
|
|
|
fields:
|
|
|
|
|
|
|
|
|
|
.. attribute:: username
|
|
|
|
|
|
2015-12-29 19:52:48 +00:00
|
|
|
|
Required. 150 characters or fewer. Usernames may contain alphanumeric,
|
2012-12-28 19:00:11 +00:00
|
|
|
|
``_``, ``@``, ``+``, ``.`` and ``-`` characters.
|
|
|
|
|
|
2015-12-29 19:52:48 +00:00
|
|
|
|
The ``max_length`` should be sufficient for many use cases. If you need
|
|
|
|
|
a longer length, please use a :ref:`custom user model
|
|
|
|
|
<specifying-custom-user-model>`. If you use MySQL with the ``utf8mb4``
|
|
|
|
|
encoding (recommended for proper Unicode support), specify at most
|
|
|
|
|
``max_length=191`` because MySQL can only create unique indexes with
|
|
|
|
|
191 characters in that case by default.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. attribute:: first_name
|
|
|
|
|
|
2020-03-17 12:12:32 +00:00
|
|
|
|
Optional (:attr:`blank=True <django.db.models.Field.blank>`). 150
|
2017-04-02 01:24:42 +00:00
|
|
|
|
characters or fewer.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: last_name
|
|
|
|
|
|
2017-04-02 01:24:42 +00:00
|
|
|
|
Optional (:attr:`blank=True <django.db.models.Field.blank>`). 150
|
|
|
|
|
characters or fewer.
|
2017-01-22 14:45:42 +00:00
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. attribute:: email
|
|
|
|
|
|
2017-04-02 01:24:42 +00:00
|
|
|
|
Optional (:attr:`blank=True <django.db.models.Field.blank>`). Email
|
|
|
|
|
address.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: password
|
|
|
|
|
|
|
|
|
|
Required. A hash of, and metadata about, the password. (Django doesn't
|
|
|
|
|
store the raw password.) Raw passwords can be arbitrarily long and can
|
|
|
|
|
contain any character. See the :doc:`password documentation
|
|
|
|
|
</topics/auth/passwords>`.
|
|
|
|
|
|
|
|
|
|
.. attribute:: groups
|
|
|
|
|
|
|
|
|
|
Many-to-many relationship to :class:`~django.contrib.auth.models.Group`
|
|
|
|
|
|
|
|
|
|
.. attribute:: user_permissions
|
|
|
|
|
|
2019-01-09 23:22:29 +00:00
|
|
|
|
Many-to-many relationship to :class:`~django.contrib.auth.models.Permission`
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: is_staff
|
|
|
|
|
|
2023-11-21 14:52:04 +00:00
|
|
|
|
Boolean. Allows this user to access the admin site.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: is_active
|
|
|
|
|
|
2023-11-21 14:52:04 +00:00
|
|
|
|
Boolean. Marks this user account as active. We recommend that you set
|
|
|
|
|
this flag to ``False`` instead of deleting accounts. That way, if your
|
|
|
|
|
applications have any foreign keys to users, the foreign keys won't
|
|
|
|
|
break.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
This doesn't necessarily control whether or not the user can log in.
|
|
|
|
|
Authentication backends aren't required to check for the ``is_active``
|
2016-02-05 14:46:19 +00:00
|
|
|
|
flag but the default backend
|
|
|
|
|
(:class:`~django.contrib.auth.backends.ModelBackend`) and the
|
|
|
|
|
:class:`~django.contrib.auth.backends.RemoteUserBackend` do. You can
|
|
|
|
|
use :class:`~django.contrib.auth.backends.AllowAllUsersModelBackend`
|
|
|
|
|
or :class:`~django.contrib.auth.backends.AllowAllUsersRemoteUserBackend`
|
|
|
|
|
if you want to allow inactive users to login. In this case, you'll also
|
|
|
|
|
want to customize the
|
2012-12-28 19:00:11 +00:00
|
|
|
|
:class:`~django.contrib.auth.forms.AuthenticationForm` used by the
|
2016-05-15 15:28:00 +00:00
|
|
|
|
:class:`~django.contrib.auth.views.LoginView` as it rejects inactive
|
2016-02-05 14:46:19 +00:00
|
|
|
|
users. Be aware that the permission-checking methods such as
|
|
|
|
|
:meth:`~django.contrib.auth.models.User.has_perm` and the
|
|
|
|
|
authentication in the Django admin all return ``False`` for inactive
|
|
|
|
|
users.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. attribute:: is_superuser
|
|
|
|
|
|
2023-11-21 14:52:04 +00:00
|
|
|
|
Boolean. Treats this user as having all permissions without assigning
|
|
|
|
|
any permission to it in particular.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: last_login
|
|
|
|
|
|
2014-07-29 12:56:00 +00:00
|
|
|
|
A datetime of the user's last login.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. attribute:: date_joined
|
|
|
|
|
|
2023-11-21 14:52:04 +00:00
|
|
|
|
The date/time when the account was created.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2016-04-02 11:18:26 +00:00
|
|
|
|
Attributes
|
|
|
|
|
----------
|
|
|
|
|
|
|
|
|
|
.. class:: models.User
|
2020-04-06 05:41:43 +00:00
|
|
|
|
:noindex:
|
2016-04-02 11:18:26 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: is_authenticated
|
|
|
|
|
|
|
|
|
|
Read-only attribute which is always ``True`` (as opposed to
|
|
|
|
|
``AnonymousUser.is_authenticated`` which is always ``False``). This is
|
|
|
|
|
a way to tell if the user has been authenticated. This does not imply
|
|
|
|
|
any permissions and doesn't check if the user is active or has a valid
|
|
|
|
|
session. Even though normally you will check this attribute on
|
|
|
|
|
``request.user`` to find out whether it has been populated by the
|
|
|
|
|
:class:`~django.contrib.auth.middleware.AuthenticationMiddleware`
|
|
|
|
|
(representing the currently logged-in user), you should know this
|
|
|
|
|
attribute is ``True`` for any :class:`~models.User` instance.
|
|
|
|
|
|
|
|
|
|
.. attribute:: is_anonymous
|
|
|
|
|
|
|
|
|
|
Read-only attribute which is always ``False``. This is a way of
|
|
|
|
|
differentiating :class:`~models.User` and :class:`~models.AnonymousUser`
|
|
|
|
|
objects. Generally, you should prefer using
|
|
|
|
|
:attr:`~django.contrib.auth.models.User.is_authenticated` to this
|
|
|
|
|
attribute.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
Methods
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
.. class:: models.User
|
2020-04-06 05:41:43 +00:00
|
|
|
|
:noindex:
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
.. method:: get_username()
|
|
|
|
|
|
2016-11-23 20:03:33 +00:00
|
|
|
|
Returns the username for the user. Since the ``User`` model can be
|
|
|
|
|
swapped out, you should use this method instead of referencing the
|
|
|
|
|
username attribute directly.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
.. method:: get_full_name()
|
|
|
|
|
|
|
|
|
|
Returns the :attr:`~django.contrib.auth.models.User.first_name` plus
|
|
|
|
|
the :attr:`~django.contrib.auth.models.User.last_name`, with a space in
|
|
|
|
|
between.
|
|
|
|
|
|
2013-12-30 22:42:11 +00:00
|
|
|
|
.. method:: get_short_name()
|
|
|
|
|
|
|
|
|
|
Returns the :attr:`~django.contrib.auth.models.User.first_name`.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. method:: set_password(raw_password)
|
|
|
|
|
|
|
|
|
|
Sets the user's password to the given raw string, taking care of the
|
|
|
|
|
password hashing. Doesn't save the
|
|
|
|
|
:class:`~django.contrib.auth.models.User` object.
|
|
|
|
|
|
2013-06-17 16:06:26 +00:00
|
|
|
|
When the ``raw_password`` is ``None``, the password will be set to an
|
|
|
|
|
unusable password, as if
|
|
|
|
|
:meth:`~django.contrib.auth.models.User.set_unusable_password()`
|
|
|
|
|
were used.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. method:: check_password(raw_password)
|
2023-05-14 16:12:22 +00:00
|
|
|
|
.. method:: acheck_password(raw_password)
|
|
|
|
|
|
|
|
|
|
*Asynchronous version*: ``acheck_password()``
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
Returns ``True`` if the given raw string is the correct password for
|
|
|
|
|
the user. (This takes care of the password hashing in making the
|
|
|
|
|
comparison.)
|
|
|
|
|
|
2023-05-14 16:12:22 +00:00
|
|
|
|
.. versionchanged:: 5.0
|
|
|
|
|
|
|
|
|
|
``acheck_password()`` method was added.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. method:: set_unusable_password()
|
|
|
|
|
|
|
|
|
|
Marks the user as having no password set. This isn't the same as
|
|
|
|
|
having a blank string for a password.
|
|
|
|
|
:meth:`~django.contrib.auth.models.User.check_password()` for this user
|
|
|
|
|
will never return ``True``. Doesn't save the
|
|
|
|
|
:class:`~django.contrib.auth.models.User` object.
|
|
|
|
|
|
|
|
|
|
You may need this if authentication for your application takes place
|
|
|
|
|
against an existing external source such as an LDAP directory.
|
|
|
|
|
|
2023-12-19 17:04:04 +00:00
|
|
|
|
.. admonition:: Password reset restriction
|
|
|
|
|
|
|
|
|
|
Users having an unusable password will not able to request a
|
|
|
|
|
password reset email via
|
|
|
|
|
:class:`~django.contrib.auth.views.PasswordResetView`.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. method:: has_usable_password()
|
|
|
|
|
|
|
|
|
|
Returns ``False`` if
|
|
|
|
|
:meth:`~django.contrib.auth.models.User.set_unusable_password()` has
|
2018-03-20 21:19:27 +00:00
|
|
|
|
been called for this user.
|
|
|
|
|
|
2019-03-23 23:40:44 +00:00
|
|
|
|
.. method:: get_user_permissions(obj=None)
|
|
|
|
|
|
|
|
|
|
Returns a set of permission strings that the user has directly.
|
|
|
|
|
|
|
|
|
|
If ``obj`` is passed in, only returns the user permissions for this
|
|
|
|
|
specific object.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. method:: get_group_permissions(obj=None)
|
|
|
|
|
|
2014-07-21 17:55:37 +00:00
|
|
|
|
Returns a set of permission strings that the user has, through their
|
2012-12-28 19:00:11 +00:00
|
|
|
|
groups.
|
|
|
|
|
|
|
|
|
|
If ``obj`` is passed in, only returns the group permissions for
|
|
|
|
|
this specific object.
|
|
|
|
|
|
|
|
|
|
.. method:: get_all_permissions(obj=None)
|
|
|
|
|
|
|
|
|
|
Returns a set of permission strings that the user has, both through
|
|
|
|
|
group and user permissions.
|
|
|
|
|
|
|
|
|
|
If ``obj`` is passed in, only returns the permissions for this
|
|
|
|
|
specific object.
|
|
|
|
|
|
|
|
|
|
.. method:: has_perm(perm, obj=None)
|
|
|
|
|
|
|
|
|
|
Returns ``True`` if the user has the specified permission, where perm
|
|
|
|
|
is in the format ``"<app label>.<permission codename>"``. (see
|
|
|
|
|
documentation on :ref:`permissions <topic-authorization>`). If the user is
|
2019-07-02 09:20:53 +00:00
|
|
|
|
inactive, this method will always return ``False``. For an active
|
|
|
|
|
superuser, this method will always return ``True``.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
If ``obj`` is passed in, this method won't check for a permission for
|
|
|
|
|
the model, but for this specific object.
|
|
|
|
|
|
|
|
|
|
.. method:: has_perms(perm_list, obj=None)
|
|
|
|
|
|
|
|
|
|
Returns ``True`` if the user has each of the specified permissions,
|
|
|
|
|
where each perm is in the format
|
|
|
|
|
``"<app label>.<permission codename>"``. If the user is inactive,
|
2019-07-02 09:20:53 +00:00
|
|
|
|
this method will always return ``False``. For an active superuser, this
|
|
|
|
|
method will always return ``True``.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
If ``obj`` is passed in, this method won't check for permissions for
|
|
|
|
|
the model, but for the specific object.
|
|
|
|
|
|
|
|
|
|
.. method:: has_module_perms(package_name)
|
|
|
|
|
|
|
|
|
|
Returns ``True`` if the user has any permissions in the given package
|
|
|
|
|
(the Django app label). If the user is inactive, this method will
|
2019-07-02 09:20:53 +00:00
|
|
|
|
always return ``False``. For an active superuser, this method will
|
|
|
|
|
always return ``True``.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2013-08-10 08:13:41 +00:00
|
|
|
|
.. method:: email_user(subject, message, from_email=None, **kwargs)
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
Sends an email to the user. If ``from_email`` is ``None``, Django uses
|
2015-01-26 20:39:52 +00:00
|
|
|
|
the :setting:`DEFAULT_FROM_EMAIL`. Any ``**kwargs`` are passed to the
|
|
|
|
|
underlying :meth:`~django.core.mail.send_mail()` call.
|
2013-08-10 08:13:41 +00:00
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
Manager methods
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
.. class:: models.UserManager
|
|
|
|
|
|
|
|
|
|
The :class:`~django.contrib.auth.models.User` model has a custom manager
|
2013-01-10 20:16:25 +00:00
|
|
|
|
that has the following helper methods (in addition to the methods provided
|
|
|
|
|
by :class:`~django.contrib.auth.models.BaseUserManager`):
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2013-01-10 20:16:25 +00:00
|
|
|
|
.. method:: create_user(username, email=None, password=None, **extra_fields)
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
Creates, saves and returns a :class:`~django.contrib.auth.models.User`.
|
|
|
|
|
|
|
|
|
|
The :attr:`~django.contrib.auth.models.User.username` and
|
|
|
|
|
:attr:`~django.contrib.auth.models.User.password` are set as given. The
|
|
|
|
|
domain portion of :attr:`~django.contrib.auth.models.User.email` is
|
|
|
|
|
automatically converted to lowercase, and the returned
|
|
|
|
|
:class:`~django.contrib.auth.models.User` object will have
|
|
|
|
|
:attr:`~django.contrib.auth.models.User.is_active` set to ``True``.
|
|
|
|
|
|
|
|
|
|
If no password is provided,
|
|
|
|
|
:meth:`~django.contrib.auth.models.User.set_unusable_password()` will
|
|
|
|
|
be called.
|
|
|
|
|
|
2013-01-10 20:16:25 +00:00
|
|
|
|
The ``extra_fields`` keyword arguments are passed through to the
|
2013-08-05 16:23:26 +00:00
|
|
|
|
:class:`~django.contrib.auth.models.User`’s ``__init__`` method to
|
2016-11-23 20:03:33 +00:00
|
|
|
|
allow setting arbitrary fields on a :ref:`custom user model
|
2013-01-10 20:16:25 +00:00
|
|
|
|
<auth-custom-user>`.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2013-01-10 20:16:25 +00:00
|
|
|
|
See :ref:`Creating users <topics-auth-creating-users>` for example usage.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2019-06-14 09:12:08 +00:00
|
|
|
|
.. method:: create_superuser(username, email=None, password=None, **extra_fields)
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2013-01-10 20:16:25 +00:00
|
|
|
|
Same as :meth:`create_user`, but sets :attr:`~models.User.is_staff` and
|
|
|
|
|
:attr:`~models.User.is_superuser` to ``True``.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2016-08-25 16:26:18 +00:00
|
|
|
|
.. method:: with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)
|
|
|
|
|
|
|
|
|
|
Returns users that have the given permission ``perm`` either in the
|
|
|
|
|
``"<app label>.<permission codename>"`` format or as a
|
|
|
|
|
:class:`~django.contrib.auth.models.Permission` instance. Returns an
|
|
|
|
|
empty queryset if no users who have the ``perm`` found.
|
|
|
|
|
|
|
|
|
|
If ``is_active`` is ``True`` (default), returns only active users, or
|
|
|
|
|
if ``False``, returns only inactive users. Use ``None`` to return all
|
|
|
|
|
users irrespective of active state.
|
|
|
|
|
|
|
|
|
|
If ``include_superusers`` is ``True`` (default), the result will
|
|
|
|
|
include superusers.
|
|
|
|
|
|
|
|
|
|
If ``backend`` is passed in and it's defined in
|
|
|
|
|
:setting:`AUTHENTICATION_BACKENDS`, then this method will use it.
|
|
|
|
|
Otherwise, it will use the ``backend`` in
|
|
|
|
|
:setting:`AUTHENTICATION_BACKENDS`, if there is only one, or raise an
|
|
|
|
|
exception.
|
|
|
|
|
|
2016-01-24 21:26:11 +00:00
|
|
|
|
``AnonymousUser`` object
|
|
|
|
|
========================
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
.. class:: models.AnonymousUser
|
|
|
|
|
|
|
|
|
|
:class:`django.contrib.auth.models.AnonymousUser` is a class that
|
|
|
|
|
implements the :class:`django.contrib.auth.models.User` interface, with
|
|
|
|
|
these differences:
|
|
|
|
|
|
|
|
|
|
* :ref:`id <automatic-primary-key-fields>` is always ``None``.
|
2014-09-17 17:56:56 +00:00
|
|
|
|
* :attr:`~django.contrib.auth.models.User.username` is always the empty
|
|
|
|
|
string.
|
|
|
|
|
* :meth:`~django.contrib.auth.models.User.get_username()` always returns
|
|
|
|
|
the empty string.
|
2016-04-02 11:18:26 +00:00
|
|
|
|
* :attr:`~django.contrib.auth.models.User.is_anonymous` is ``True``
|
|
|
|
|
instead of ``False``.
|
|
|
|
|
* :attr:`~django.contrib.auth.models.User.is_authenticated` is
|
|
|
|
|
``False`` instead of ``True``.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
* :attr:`~django.contrib.auth.models.User.is_staff` and
|
|
|
|
|
:attr:`~django.contrib.auth.models.User.is_superuser` are always
|
|
|
|
|
``False``.
|
|
|
|
|
* :attr:`~django.contrib.auth.models.User.is_active` is always ``False``.
|
|
|
|
|
* :attr:`~django.contrib.auth.models.User.groups` and
|
|
|
|
|
:attr:`~django.contrib.auth.models.User.user_permissions` are always
|
|
|
|
|
empty.
|
|
|
|
|
* :meth:`~django.contrib.auth.models.User.set_password()`,
|
|
|
|
|
:meth:`~django.contrib.auth.models.User.check_password()`,
|
|
|
|
|
:meth:`~django.db.models.Model.save` and
|
2014-04-26 14:00:15 +00:00
|
|
|
|
:meth:`~django.db.models.Model.delete()` raise :exc:`NotImplementedError`.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
In practice, you probably won't need to use
|
|
|
|
|
:class:`~django.contrib.auth.models.AnonymousUser` objects on your own, but
|
2021-07-23 06:48:16 +00:00
|
|
|
|
they're used by web requests, as explained in the next section.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2016-01-24 21:26:11 +00:00
|
|
|
|
``Permission`` model
|
|
|
|
|
====================
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
.. class:: models.Permission
|
|
|
|
|
|
|
|
|
|
Fields
|
|
|
|
|
------
|
|
|
|
|
|
|
|
|
|
:class:`~django.contrib.auth.models.Permission` objects have the following
|
|
|
|
|
fields:
|
|
|
|
|
|
2014-06-26 10:56:45 +00:00
|
|
|
|
.. class:: models.Permission
|
2020-04-06 05:41:43 +00:00
|
|
|
|
:noindex:
|
2014-06-26 10:56:45 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: name
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2014-11-21 12:05:22 +00:00
|
|
|
|
Required. 255 characters or fewer. Example: ``'Can vote'``.
|
|
|
|
|
|
2014-06-26 10:56:45 +00:00
|
|
|
|
.. attribute:: content_type
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2014-06-26 10:56:45 +00:00
|
|
|
|
Required. A reference to the ``django_content_type`` database table,
|
|
|
|
|
which contains a record for each installed model.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2014-06-26 10:56:45 +00:00
|
|
|
|
.. attribute:: codename
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2014-06-26 10:56:45 +00:00
|
|
|
|
Required. 100 characters or fewer. Example: ``'can_vote'``.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
Methods
|
|
|
|
|
-------
|
|
|
|
|
|
|
|
|
|
:class:`~django.contrib.auth.models.Permission` objects have the standard
|
|
|
|
|
data-access methods like any other :doc:`Django model </ref/models/instances>`.
|
|
|
|
|
|
2016-01-24 21:26:11 +00:00
|
|
|
|
``Group`` model
|
|
|
|
|
===============
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
.. class:: models.Group
|
|
|
|
|
|
|
|
|
|
Fields
|
|
|
|
|
------
|
|
|
|
|
|
|
|
|
|
:class:`~django.contrib.auth.models.Group` objects have the following fields:
|
|
|
|
|
|
2014-06-26 10:56:45 +00:00
|
|
|
|
.. class:: models.Group
|
2020-04-06 05:41:43 +00:00
|
|
|
|
:noindex:
|
2014-06-26 10:56:45 +00:00
|
|
|
|
|
|
|
|
|
.. attribute:: name
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2018-11-14 20:13:34 +00:00
|
|
|
|
Required. 150 characters or fewer. Any characters are permitted.
|
|
|
|
|
Example: ``'Awesome Users'``.
|
|
|
|
|
|
2014-06-26 10:56:45 +00:00
|
|
|
|
.. attribute:: permissions
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2014-06-26 10:56:45 +00:00
|
|
|
|
Many-to-many field to :class:`~django.contrib.auth.models.Permission`::
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2015-10-08 21:17:10 +00:00
|
|
|
|
group.permissions.set([permission_list])
|
2014-06-26 10:56:45 +00:00
|
|
|
|
group.permissions.add(permission, permission, ...)
|
|
|
|
|
group.permissions.remove(permission, permission, ...)
|
|
|
|
|
group.permissions.clear()
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2016-04-22 17:39:13 +00:00
|
|
|
|
Validators
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
.. class:: validators.ASCIIUsernameValidator
|
|
|
|
|
|
2017-07-27 12:42:01 +00:00
|
|
|
|
A field validator allowing only ASCII letters and numbers, in addition to
|
|
|
|
|
``@``, ``.``, ``+``, ``-``, and ``_``.
|
2016-04-22 17:39:13 +00:00
|
|
|
|
|
|
|
|
|
.. class:: validators.UnicodeUsernameValidator
|
|
|
|
|
|
2017-07-27 12:42:01 +00:00
|
|
|
|
A field validator allowing Unicode characters, in addition to ``@``, ``.``,
|
2017-01-18 16:51:29 +00:00
|
|
|
|
``+``, ``-``, and ``_``. The default validator for ``User.username``.
|
2016-04-22 17:39:13 +00:00
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. _topics-auth-signals:
|
|
|
|
|
|
|
|
|
|
Login and logout signals
|
|
|
|
|
========================
|
|
|
|
|
|
|
|
|
|
.. module:: django.contrib.auth.signals
|
|
|
|
|
|
2013-03-01 21:15:23 +00:00
|
|
|
|
The auth framework uses the following :doc:`signals </topics/signals>` that
|
|
|
|
|
can be used for notification when a user logs in or out.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2022-01-10 10:16:29 +00:00
|
|
|
|
.. data:: user_logged_in
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
Sent when a user logs in successfully.
|
|
|
|
|
|
|
|
|
|
Arguments sent with this signal:
|
|
|
|
|
|
|
|
|
|
``sender``
|
|
|
|
|
The class of the user that just logged in.
|
|
|
|
|
|
|
|
|
|
``request``
|
|
|
|
|
The current :class:`~django.http.HttpRequest` instance.
|
|
|
|
|
|
|
|
|
|
``user``
|
|
|
|
|
The user instance that just logged in.
|
|
|
|
|
|
2022-01-10 10:16:29 +00:00
|
|
|
|
.. data:: user_logged_out
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
Sent when the logout method is called.
|
|
|
|
|
|
|
|
|
|
``sender``
|
|
|
|
|
As above: the class of the user that just logged out or ``None``
|
|
|
|
|
if the user was not authenticated.
|
|
|
|
|
|
|
|
|
|
``request``
|
|
|
|
|
The current :class:`~django.http.HttpRequest` instance.
|
|
|
|
|
|
|
|
|
|
``user``
|
|
|
|
|
The user instance that just logged out or ``None`` if the
|
|
|
|
|
user was not authenticated.
|
|
|
|
|
|
2022-01-10 10:16:29 +00:00
|
|
|
|
.. data:: user_login_failed
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
|
|
|
|
Sent when the user failed to login successfully
|
|
|
|
|
|
|
|
|
|
``sender``
|
|
|
|
|
The name of the module used for authentication.
|
|
|
|
|
|
|
|
|
|
``credentials``
|
|
|
|
|
A dictionary of keyword arguments containing the user credentials that were
|
|
|
|
|
passed to :func:`~django.contrib.auth.authenticate()` or your own custom
|
|
|
|
|
authentication backend. Credentials matching a set of 'sensitive' patterns,
|
|
|
|
|
(including password) will not be sent in the clear as part of the signal.
|
|
|
|
|
|
2016-02-19 00:58:30 +00:00
|
|
|
|
``request``
|
|
|
|
|
The :class:`~django.http.HttpRequest` object, if one was provided to
|
|
|
|
|
:func:`~django.contrib.auth.authenticate`.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. _authentication-backends-reference:
|
|
|
|
|
|
|
|
|
|
Authentication backends
|
|
|
|
|
=======================
|
|
|
|
|
|
|
|
|
|
.. module:: django.contrib.auth.backends
|
|
|
|
|
:synopsis: Django's built-in authentication backend classes.
|
|
|
|
|
|
|
|
|
|
This section details the authentication backends that come with Django. For
|
|
|
|
|
information on how to use them and how to write your own authentication
|
|
|
|
|
backends, see the :ref:`Other authentication sources section
|
|
|
|
|
<authentication-backends>` of the :doc:`User authentication guide
|
|
|
|
|
</topics/auth/index>`.
|
|
|
|
|
|
|
|
|
|
Available authentication backends
|
|
|
|
|
---------------------------------
|
|
|
|
|
|
|
|
|
|
The following backends are available in :mod:`django.contrib.auth.backends`:
|
|
|
|
|
|
2019-03-08 16:48:50 +00:00
|
|
|
|
.. class:: BaseBackend
|
|
|
|
|
|
|
|
|
|
A base class that provides default implementations for all required
|
|
|
|
|
methods. By default, it will reject any user and provide no permissions.
|
|
|
|
|
|
2019-03-23 23:40:44 +00:00
|
|
|
|
.. method:: get_user_permissions(user_obj, obj=None)
|
|
|
|
|
|
|
|
|
|
Returns an empty set.
|
|
|
|
|
|
2019-03-08 16:48:50 +00:00
|
|
|
|
.. method:: get_group_permissions(user_obj, obj=None)
|
|
|
|
|
|
|
|
|
|
Returns an empty set.
|
|
|
|
|
|
|
|
|
|
.. method:: get_all_permissions(user_obj, obj=None)
|
|
|
|
|
|
2019-03-23 23:40:44 +00:00
|
|
|
|
Uses :meth:`get_user_permissions` and :meth:`get_group_permissions` to
|
|
|
|
|
get the set of permission strings the ``user_obj`` has.
|
2019-03-08 16:48:50 +00:00
|
|
|
|
|
|
|
|
|
.. method:: has_perm(user_obj, perm, obj=None)
|
|
|
|
|
|
|
|
|
|
Uses :meth:`get_all_permissions` to check if ``user_obj`` has the
|
|
|
|
|
permission string ``perm``.
|
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. class:: ModelBackend
|
|
|
|
|
|
|
|
|
|
This is the default authentication backend used by Django. It
|
2013-02-06 22:25:51 +00:00
|
|
|
|
authenticates using credentials consisting of a user identifier and
|
|
|
|
|
password. For Django's default user model, the user identifier is the
|
|
|
|
|
username, for custom user models it is the field specified by
|
|
|
|
|
USERNAME_FIELD (see :doc:`Customizing Users and authentication
|
|
|
|
|
</topics/auth/customizing>`).
|
|
|
|
|
|
|
|
|
|
It also handles the default permissions model as defined for
|
|
|
|
|
:class:`~django.contrib.auth.models.User` and
|
|
|
|
|
:class:`~django.contrib.auth.models.PermissionsMixin`.
|
2012-12-28 19:00:11 +00:00
|
|
|
|
|
2013-12-30 07:37:27 +00:00
|
|
|
|
:meth:`has_perm`, :meth:`get_all_permissions`, :meth:`get_user_permissions`,
|
|
|
|
|
and :meth:`get_group_permissions` allow an object to be passed as a
|
|
|
|
|
parameter for object-specific permissions, but this backend does not
|
|
|
|
|
implement them other than returning an empty set of permissions if
|
|
|
|
|
``obj is not None``.
|
|
|
|
|
|
2016-08-25 16:26:18 +00:00
|
|
|
|
:meth:`with_perm` also allows an object to be passed as a parameter, but
|
|
|
|
|
unlike others methods it returns an empty queryset if ``obj is not None``.
|
|
|
|
|
|
2016-07-11 14:40:39 +00:00
|
|
|
|
.. method:: authenticate(request, username=None, password=None, **kwargs)
|
2013-12-30 07:37:27 +00:00
|
|
|
|
|
|
|
|
|
Tries to authenticate ``username`` with ``password`` by calling
|
|
|
|
|
:meth:`User.check_password
|
|
|
|
|
<django.contrib.auth.models.User.check_password>`. If no ``username``
|
|
|
|
|
is provided, it tries to fetch a username from ``kwargs`` using the
|
|
|
|
|
key :attr:`CustomUser.USERNAME_FIELD
|
|
|
|
|
<django.contrib.auth.models.CustomUser.USERNAME_FIELD>`. Returns an
|
|
|
|
|
authenticated user or ``None``.
|
|
|
|
|
|
2016-07-11 14:40:39 +00:00
|
|
|
|
``request`` is an :class:`~django.http.HttpRequest` and may be ``None``
|
|
|
|
|
if it wasn't provided to :func:`~django.contrib.auth.authenticate`
|
|
|
|
|
(which passes it on to the backend).
|
|
|
|
|
|
2013-12-30 07:37:27 +00:00
|
|
|
|
.. method:: get_user_permissions(user_obj, obj=None)
|
|
|
|
|
|
|
|
|
|
Returns the set of permission strings the ``user_obj`` has from their
|
2014-06-24 11:09:38 +00:00
|
|
|
|
own user permissions. Returns an empty set if
|
2016-04-02 11:18:26 +00:00
|
|
|
|
:attr:`~django.contrib.auth.models.AbstractBaseUser.is_anonymous` or
|
2014-06-24 11:09:38 +00:00
|
|
|
|
:attr:`~django.contrib.auth.models.CustomUser.is_active` is ``False``.
|
2013-12-30 07:37:27 +00:00
|
|
|
|
|
|
|
|
|
.. method:: get_group_permissions(user_obj, obj=None)
|
|
|
|
|
|
|
|
|
|
Returns the set of permission strings the ``user_obj`` has from the
|
2014-06-24 11:09:38 +00:00
|
|
|
|
permissions of the groups they belong. Returns an empty set if
|
2016-04-02 11:18:26 +00:00
|
|
|
|
:attr:`~django.contrib.auth.models.AbstractBaseUser.is_anonymous` or
|
2014-06-24 11:09:38 +00:00
|
|
|
|
:attr:`~django.contrib.auth.models.CustomUser.is_active` is ``False``.
|
2013-12-30 07:37:27 +00:00
|
|
|
|
|
|
|
|
|
.. method:: get_all_permissions(user_obj, obj=None)
|
|
|
|
|
|
2014-06-14 14:58:16 +00:00
|
|
|
|
Returns the set of permission strings the ``user_obj`` has, including both
|
2014-06-24 11:09:38 +00:00
|
|
|
|
user permissions and group permissions. Returns an empty set if
|
2016-04-02 11:18:26 +00:00
|
|
|
|
:attr:`~django.contrib.auth.models.AbstractBaseUser.is_anonymous` or
|
2014-06-24 11:09:38 +00:00
|
|
|
|
:attr:`~django.contrib.auth.models.CustomUser.is_active` is ``False``.
|
2013-12-30 07:37:27 +00:00
|
|
|
|
|
|
|
|
|
.. method:: has_perm(user_obj, perm, obj=None)
|
|
|
|
|
|
|
|
|
|
Uses :meth:`get_all_permissions` to check if ``user_obj`` has the
|
|
|
|
|
permission string ``perm``. Returns ``False`` if the user is not
|
2014-06-24 11:09:38 +00:00
|
|
|
|
:attr:`~django.contrib.auth.models.CustomUser.is_active`.
|
2013-12-30 07:37:27 +00:00
|
|
|
|
|
2017-03-17 00:33:59 +00:00
|
|
|
|
.. method:: has_module_perms(user_obj, app_label)
|
2013-12-30 07:37:27 +00:00
|
|
|
|
|
|
|
|
|
Returns whether the ``user_obj`` has any permissions on the app
|
|
|
|
|
``app_label``.
|
|
|
|
|
|
2018-11-03 15:07:44 +00:00
|
|
|
|
.. method:: user_can_authenticate()
|
2016-02-05 14:46:19 +00:00
|
|
|
|
|
|
|
|
|
Returns whether the user is allowed to authenticate. To match the
|
|
|
|
|
behavior of :class:`~django.contrib.auth.forms.AuthenticationForm`
|
|
|
|
|
which :meth:`prohibits inactive users from logging in
|
|
|
|
|
<django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed>`,
|
|
|
|
|
this method returns ``False`` for users with :attr:`is_active=False
|
|
|
|
|
<django.contrib.auth.models.User.is_active>`. Custom user models that
|
|
|
|
|
don't have an :attr:`~django.contrib.auth.models.CustomUser.is_active`
|
|
|
|
|
field are allowed.
|
|
|
|
|
|
2016-08-25 16:26:18 +00:00
|
|
|
|
.. method:: with_perm(perm, is_active=True, include_superusers=True, obj=None)
|
|
|
|
|
|
|
|
|
|
Returns all active users who have the permission ``perm`` either in
|
|
|
|
|
the form of ``"<app label>.<permission codename>"`` or a
|
|
|
|
|
:class:`~django.contrib.auth.models.Permission` instance. Returns an
|
|
|
|
|
empty queryset if no users who have the ``perm`` found.
|
|
|
|
|
|
|
|
|
|
If ``is_active`` is ``True`` (default), returns only active users, or
|
|
|
|
|
if ``False``, returns only inactive users. Use ``None`` to return all
|
|
|
|
|
users irrespective of active state.
|
|
|
|
|
|
|
|
|
|
If ``include_superusers`` is ``True`` (default), the result will
|
|
|
|
|
include superusers.
|
|
|
|
|
|
2016-02-05 14:46:19 +00:00
|
|
|
|
.. class:: AllowAllUsersModelBackend
|
|
|
|
|
|
2019-01-09 23:22:29 +00:00
|
|
|
|
Same as :class:`ModelBackend` except that it doesn't reject inactive users
|
|
|
|
|
because :meth:`~ModelBackend.user_can_authenticate` always returns ``True``.
|
2016-02-05 14:46:19 +00:00
|
|
|
|
|
2019-01-09 23:22:29 +00:00
|
|
|
|
When using this backend, you'll likely want to customize the
|
|
|
|
|
:class:`~django.contrib.auth.forms.AuthenticationForm` used by the
|
|
|
|
|
:class:`~django.contrib.auth.views.LoginView` by overriding the
|
|
|
|
|
:meth:`~django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed`
|
|
|
|
|
method as it rejects inactive users.
|
2016-02-05 14:46:19 +00:00
|
|
|
|
|
2012-12-28 19:00:11 +00:00
|
|
|
|
.. class:: RemoteUserBackend
|
|
|
|
|
|
|
|
|
|
Use this backend to take advantage of external-to-Django-handled
|
|
|
|
|
authentication. It authenticates using usernames passed in
|
|
|
|
|
:attr:`request.META['REMOTE_USER'] <django.http.HttpRequest.META>`. See
|
|
|
|
|
the :doc:`Authenticating against REMOTE_USER </howto/auth-remote-user>`
|
|
|
|
|
documentation.
|
2014-04-18 20:06:26 +00:00
|
|
|
|
|
|
|
|
|
If you need more control, you can create your own authentication backend
|
|
|
|
|
that inherits from this class and override these attributes or methods:
|
|
|
|
|
|
2018-11-03 15:07:44 +00:00
|
|
|
|
.. attribute:: create_unknown_user
|
2014-04-18 20:06:26 +00:00
|
|
|
|
|
2018-11-03 15:07:44 +00:00
|
|
|
|
``True`` or ``False``. Determines whether or not a user object is
|
|
|
|
|
created if not already in the database Defaults to ``True``.
|
2014-04-18 20:06:26 +00:00
|
|
|
|
|
2018-11-03 15:07:44 +00:00
|
|
|
|
.. method:: authenticate(request, remote_user)
|
2014-04-18 20:06:26 +00:00
|
|
|
|
|
2018-11-03 15:07:44 +00:00
|
|
|
|
The username passed as ``remote_user`` is considered trusted. This
|
2019-06-17 14:54:55 +00:00
|
|
|
|
method returns the user object with the given username, creating a new
|
|
|
|
|
user object if :attr:`~RemoteUserBackend.create_unknown_user` is
|
2018-11-03 15:07:44 +00:00
|
|
|
|
``True``.
|
2014-04-18 20:06:26 +00:00
|
|
|
|
|
2018-11-03 15:07:44 +00:00
|
|
|
|
Returns ``None`` if :attr:`~RemoteUserBackend.create_unknown_user` is
|
|
|
|
|
``False`` and a ``User`` object with the given username is not found in
|
|
|
|
|
the database.
|
2014-04-18 20:06:26 +00:00
|
|
|
|
|
2018-11-03 15:07:44 +00:00
|
|
|
|
``request`` is an :class:`~django.http.HttpRequest` and may be ``None``
|
|
|
|
|
if it wasn't provided to :func:`~django.contrib.auth.authenticate`
|
|
|
|
|
(which passes it on to the backend).
|
2016-07-11 14:40:39 +00:00
|
|
|
|
|
2018-11-03 15:07:44 +00:00
|
|
|
|
.. method:: clean_username(username)
|
2014-04-18 20:06:26 +00:00
|
|
|
|
|
2019-01-09 23:22:29 +00:00
|
|
|
|
Performs any cleaning on the ``username`` (e.g. stripping LDAP DN
|
|
|
|
|
information) prior to using it to get or create a user object. Returns
|
|
|
|
|
the cleaned username.
|
2014-04-18 20:06:26 +00:00
|
|
|
|
|
2022-03-04 10:04:07 +00:00
|
|
|
|
.. method:: configure_user(request, user, created=True)
|
2014-04-18 20:06:26 +00:00
|
|
|
|
|
2022-03-04 10:04:07 +00:00
|
|
|
|
Configures the user on each authentication attempt. This method is
|
|
|
|
|
called immediately after fetching or creating the user being
|
|
|
|
|
authenticated, and can be used to perform custom setup actions, such as
|
|
|
|
|
setting the user's groups based on attributes in an LDAP directory.
|
|
|
|
|
Returns the user object.
|
|
|
|
|
|
|
|
|
|
The setup can be performed either once when the user is created
|
|
|
|
|
(``created`` is ``True``) or on existing users (``created`` is
|
|
|
|
|
``False``) as a way of synchronizing attributes between the remote and
|
|
|
|
|
the local systems.
|
2016-02-05 14:46:19 +00:00
|
|
|
|
|
2018-12-13 16:14:03 +00:00
|
|
|
|
``request`` is an :class:`~django.http.HttpRequest` and may be ``None``
|
|
|
|
|
if it wasn't provided to :func:`~django.contrib.auth.authenticate`
|
|
|
|
|
(which passes it on to the backend).
|
|
|
|
|
|
2018-11-03 15:07:44 +00:00
|
|
|
|
.. method:: user_can_authenticate()
|
2016-02-05 14:46:19 +00:00
|
|
|
|
|
2018-11-03 15:07:44 +00:00
|
|
|
|
Returns whether the user is allowed to authenticate. This method
|
|
|
|
|
returns ``False`` for users with :attr:`is_active=False
|
|
|
|
|
<django.contrib.auth.models.User.is_active>`. Custom user models that
|
|
|
|
|
don't have an :attr:`~django.contrib.auth.models.CustomUser.is_active`
|
|
|
|
|
field are allowed.
|
2016-02-05 14:46:19 +00:00
|
|
|
|
|
|
|
|
|
.. class:: AllowAllUsersRemoteUserBackend
|
|
|
|
|
|
2019-01-09 23:22:29 +00:00
|
|
|
|
Same as :class:`RemoteUserBackend` except that it doesn't reject inactive
|
|
|
|
|
users because :attr:`~RemoteUserBackend.user_can_authenticate` always
|
|
|
|
|
returns ``True``.
|
2016-09-10 23:38:05 +00:00
|
|
|
|
|
2016-08-24 09:21:28 +00:00
|
|
|
|
Utility functions
|
|
|
|
|
=================
|
|
|
|
|
|
|
|
|
|
.. currentmodule:: django.contrib.auth
|
|
|
|
|
|
|
|
|
|
.. function:: get_user(request)
|
2023-02-11 01:43:26 +00:00
|
|
|
|
.. function:: aget_user(request)
|
|
|
|
|
|
|
|
|
|
*Asynchronous version*: ``aget_user()``
|
2016-08-24 09:21:28 +00:00
|
|
|
|
|
|
|
|
|
Returns the user model instance associated with the given ``request``’s
|
|
|
|
|
session.
|
|
|
|
|
|
|
|
|
|
It checks if the authentication backend stored in the session is present in
|
|
|
|
|
:setting:`AUTHENTICATION_BACKENDS`. If so, it uses the backend's
|
|
|
|
|
``get_user()`` method to retrieve the user model instance and then verifies
|
|
|
|
|
the session by calling the user model's
|
|
|
|
|
:meth:`~django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash`
|
2023-03-06 15:18:03 +00:00
|
|
|
|
method. If the verification fails and :setting:`SECRET_KEY_FALLBACKS` are
|
|
|
|
|
provided, it verifies the session against each fallback key using
|
|
|
|
|
:meth:`~django.contrib.auth.models.AbstractBaseUser.\
|
|
|
|
|
get_session_auth_fallback_hash`.
|
2016-08-24 09:21:28 +00:00
|
|
|
|
|
|
|
|
|
Returns an instance of :class:`~django.contrib.auth.models.AnonymousUser`
|
|
|
|
|
if the authentication backend stored in the session is no longer in
|
|
|
|
|
:setting:`AUTHENTICATION_BACKENDS`, if a user isn't returned by the
|
|
|
|
|
backend's ``get_user()`` method, or if the session auth hash doesn't
|
|
|
|
|
validate.
|
2023-03-06 15:18:03 +00:00
|
|
|
|
|
2023-02-11 01:43:26 +00:00
|
|
|
|
.. versionchanged:: 5.0
|
|
|
|
|
|
|
|
|
|
``aget_user()`` function was added.
|