mirror of
https://github.com/django/django.git
synced 2024-12-22 17:16:24 +00:00
861 lines
31 KiB
Plaintext
861 lines
31 KiB
Plaintext
=======================
|
||
``django.contrib.auth``
|
||
=======================
|
||
|
||
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
|
||
|
||
``User`` model
|
||
==============
|
||
|
||
.. class:: models.User
|
||
|
||
Fields
|
||
------
|
||
|
||
.. class:: models.User
|
||
:noindex:
|
||
|
||
:class:`~django.contrib.auth.models.User` objects have the following
|
||
fields:
|
||
|
||
.. attribute:: username
|
||
|
||
Required. 150 characters or fewer. Usernames may contain alphanumeric,
|
||
``_``, ``@``, ``+``, ``.`` and ``-`` characters.
|
||
|
||
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>`.
|
||
|
||
.. attribute:: first_name
|
||
|
||
Optional (:attr:`blank=True <django.db.models.Field.blank>`). 150
|
||
characters or fewer.
|
||
|
||
.. attribute:: last_name
|
||
|
||
Optional (:attr:`blank=True <django.db.models.Field.blank>`). 150
|
||
characters or fewer.
|
||
|
||
.. attribute:: email
|
||
|
||
Optional (:attr:`blank=True <django.db.models.Field.blank>`). Email
|
||
address.
|
||
|
||
.. 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. The metadata in this field may mark the password
|
||
as unusable. See the :doc:`password documentation
|
||
</topics/auth/passwords>`.
|
||
|
||
.. attribute:: groups
|
||
|
||
Many-to-many relationship to :class:`~django.contrib.auth.models.Group`
|
||
|
||
.. attribute:: user_permissions
|
||
|
||
Many-to-many relationship to :class:`~django.contrib.auth.models.Permission`
|
||
|
||
.. attribute:: is_staff
|
||
|
||
Boolean. Allows this user to access the admin site.
|
||
|
||
.. attribute:: is_active
|
||
|
||
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.
|
||
|
||
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 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
|
||
:class:`~django.contrib.auth.forms.AuthenticationForm` used by the
|
||
:class:`~django.contrib.auth.views.LoginView` as it rejects inactive
|
||
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.
|
||
|
||
.. attribute:: is_superuser
|
||
|
||
Boolean. Treats this user as having all permissions without assigning
|
||
any permission to it in particular.
|
||
|
||
.. attribute:: last_login
|
||
|
||
A datetime of the user's last login.
|
||
|
||
.. attribute:: date_joined
|
||
|
||
The date/time when the account was created.
|
||
|
||
Attributes
|
||
----------
|
||
|
||
.. class:: models.User
|
||
:noindex:
|
||
|
||
.. 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.
|
||
|
||
Methods
|
||
-------
|
||
|
||
.. class:: models.User
|
||
:noindex:
|
||
|
||
.. method:: get_username()
|
||
|
||
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.
|
||
|
||
.. 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.
|
||
|
||
.. method:: get_short_name()
|
||
|
||
Returns the :attr:`~django.contrib.auth.models.User.first_name`.
|
||
|
||
.. 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.
|
||
|
||
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.
|
||
|
||
.. method:: check_password(raw_password)
|
||
.. method:: acheck_password(raw_password)
|
||
|
||
*Asynchronous version*: ``acheck_password()``
|
||
|
||
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.)
|
||
|
||
.. method:: set_unusable_password()
|
||
|
||
Marks the user as having no password set by updating the metadata in
|
||
the :attr:`~django.contrib.auth.models.User.password` field. 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.
|
||
|
||
.. 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`.
|
||
|
||
.. method:: has_usable_password()
|
||
|
||
Returns ``False`` if
|
||
:meth:`~django.contrib.auth.models.User.set_unusable_password()` has
|
||
been called for this user.
|
||
|
||
.. method:: get_user_permissions(obj=None)
|
||
.. method:: aget_user_permissions(obj=None)
|
||
|
||
*Asynchronous version*: ``aget_user_permissions()``
|
||
|
||
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.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aget_user_permissions()`` method was added.
|
||
|
||
.. method:: get_group_permissions(obj=None)
|
||
.. method:: aget_group_permissions(obj=None)
|
||
|
||
*Asynchronous version*: ``aget_group_permissions()``
|
||
|
||
Returns a set of permission strings that the user has, through their
|
||
groups.
|
||
|
||
If ``obj`` is passed in, only returns the group permissions for
|
||
this specific object.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aget_group_permissions()`` method was added.
|
||
|
||
.. method:: get_all_permissions(obj=None)
|
||
.. method:: aget_all_permissions(obj=None)
|
||
|
||
*Asynchronous version*: ``aget_all_permissions()``
|
||
|
||
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.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aget_all_permissions()`` method was added.
|
||
|
||
.. method:: has_perm(perm, obj=None)
|
||
.. method:: ahas_perm(perm, obj=None)
|
||
|
||
*Asynchronous version*: ``ahas_perm()``
|
||
|
||
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
|
||
inactive, this method will always return ``False``. For an active
|
||
superuser, this method will always return ``True``.
|
||
|
||
If ``obj`` is passed in, this method won't check for a permission for
|
||
the model, but for this specific object.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``ahas_perm()`` method was added.
|
||
|
||
.. method:: has_perms(perm_list, obj=None)
|
||
.. method:: ahas_perms(perm_list, obj=None)
|
||
|
||
*Asynchronous version*: ``ahas_perms()``
|
||
|
||
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,
|
||
this method will always return ``False``. For an active superuser, this
|
||
method will always return ``True``.
|
||
|
||
If ``obj`` is passed in, this method won't check for permissions for
|
||
the model, but for the specific object.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``ahas_perms()`` method was added.
|
||
|
||
.. method:: has_module_perms(package_name)
|
||
.. method:: ahas_module_perms(package_name)
|
||
|
||
*Asynchronous version*: ``ahas_module_perms()``
|
||
|
||
Returns ``True`` if the user has any permissions in the given package
|
||
(the Django app label). If the user is inactive, this method will
|
||
always return ``False``. For an active superuser, this method will
|
||
always return ``True``.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``ahas_module_perms()`` method was added.
|
||
|
||
.. method:: email_user(subject, message, from_email=None, **kwargs)
|
||
|
||
Sends an email to the user. If ``from_email`` is ``None``, Django uses
|
||
the :setting:`DEFAULT_FROM_EMAIL`. Any ``**kwargs`` are passed to the
|
||
underlying :meth:`~django.core.mail.send_mail()` call.
|
||
|
||
Manager methods
|
||
---------------
|
||
|
||
.. class:: models.UserManager
|
||
|
||
The :class:`~django.contrib.auth.models.User` model has a custom manager
|
||
that has the following helper methods (in addition to the methods provided
|
||
by :class:`~django.contrib.auth.models.BaseUserManager`):
|
||
|
||
.. method:: create_user(username, email=None, password=None, **extra_fields)
|
||
.. method:: acreate_user(username, email=None, password=None, **extra_fields)
|
||
|
||
*Asynchronous version*: ``acreate_user()``
|
||
|
||
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.
|
||
|
||
The ``extra_fields`` keyword arguments are passed through to the
|
||
:class:`~django.contrib.auth.models.User`’s ``__init__`` method to
|
||
allow setting arbitrary fields on a :ref:`custom user model
|
||
<auth-custom-user>`.
|
||
|
||
See :ref:`Creating users <topics-auth-creating-users>` for example usage.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``acreate_user()`` method was added.
|
||
|
||
.. method:: create_superuser(username, email=None, password=None, **extra_fields)
|
||
.. method:: acreate_superuser(username, email=None, password=None, **extra_fields)
|
||
|
||
*Asynchronous version*: ``acreate_superuser()``
|
||
|
||
Same as :meth:`create_user`, but sets :attr:`~models.User.is_staff` and
|
||
:attr:`~models.User.is_superuser` to ``True``.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``acreate_superuser()`` method was added.
|
||
|
||
.. 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.
|
||
|
||
``AnonymousUser`` object
|
||
========================
|
||
|
||
.. 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``.
|
||
* :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.
|
||
* :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``.
|
||
* :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
|
||
:meth:`~django.db.models.Model.delete()` raise :exc:`NotImplementedError`.
|
||
|
||
In practice, you probably won't need to use
|
||
:class:`~django.contrib.auth.models.AnonymousUser` objects on your own, but
|
||
they're used by web requests, as explained in the next section.
|
||
|
||
``Permission`` model
|
||
====================
|
||
|
||
.. class:: models.Permission
|
||
|
||
Fields
|
||
------
|
||
|
||
:class:`~django.contrib.auth.models.Permission` objects have the following
|
||
fields:
|
||
|
||
.. class:: models.Permission
|
||
:noindex:
|
||
|
||
.. attribute:: name
|
||
|
||
Required. 255 characters or fewer. Example: ``'Can vote'``.
|
||
|
||
.. attribute:: content_type
|
||
|
||
Required. A foreign key to the
|
||
:class:`~django.contrib.contenttypes.models.ContentType` model.
|
||
|
||
.. attribute:: codename
|
||
|
||
Required. 100 characters or fewer. Example: ``'can_vote'``.
|
||
|
||
Methods
|
||
-------
|
||
|
||
:class:`~django.contrib.auth.models.Permission` objects have the standard
|
||
data-access methods like any other :doc:`Django model </ref/models/instances>`.
|
||
|
||
``Group`` model
|
||
===============
|
||
|
||
.. class:: models.Group
|
||
|
||
Fields
|
||
------
|
||
|
||
:class:`~django.contrib.auth.models.Group` objects have the following fields:
|
||
|
||
.. class:: models.Group
|
||
:noindex:
|
||
|
||
.. attribute:: name
|
||
|
||
Required. 150 characters or fewer. Any characters are permitted.
|
||
Example: ``'Awesome Users'``.
|
||
|
||
.. attribute:: permissions
|
||
|
||
Many-to-many field to :class:`~django.contrib.auth.models.Permission`::
|
||
|
||
group.permissions.set([permission_list])
|
||
group.permissions.add(permission, permission, ...)
|
||
group.permissions.remove(permission, permission, ...)
|
||
group.permissions.clear()
|
||
|
||
Validators
|
||
==========
|
||
|
||
.. class:: validators.ASCIIUsernameValidator
|
||
|
||
A field validator allowing only ASCII letters and numbers, in addition to
|
||
``@``, ``.``, ``+``, ``-``, and ``_``.
|
||
|
||
.. class:: validators.UnicodeUsernameValidator
|
||
|
||
A field validator allowing Unicode characters, in addition to ``@``, ``.``,
|
||
``+``, ``-``, and ``_``. The default validator for ``User.username``.
|
||
|
||
.. _topics-auth-signals:
|
||
|
||
Login and logout signals
|
||
========================
|
||
|
||
.. module:: django.contrib.auth.signals
|
||
|
||
The auth framework uses the following :doc:`signals </topics/signals>` that
|
||
can be used for notification when a user logs in or out.
|
||
|
||
.. data:: user_logged_in
|
||
|
||
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.
|
||
|
||
.. data:: user_logged_out
|
||
|
||
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.
|
||
|
||
.. data:: user_login_failed
|
||
|
||
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.
|
||
|
||
``request``
|
||
The :class:`~django.http.HttpRequest` object, if one was provided to
|
||
:func:`~django.contrib.auth.authenticate`.
|
||
|
||
.. _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`:
|
||
|
||
.. class:: BaseBackend
|
||
|
||
A base class that provides default implementations for all required
|
||
methods. By default, it will reject any user and provide no permissions.
|
||
|
||
.. method:: get_user_permissions(user_obj, obj=None)
|
||
.. method:: aget_user_permissions(user_obj, obj=None)
|
||
|
||
*Asynchronous version*: ``aget_user_permissions()``
|
||
|
||
Returns an empty set.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aget_user_permissions()`` function was added.
|
||
|
||
.. method:: get_group_permissions(user_obj, obj=None)
|
||
.. method:: aget_group_permissions(user_obj, obj=None)
|
||
|
||
*Asynchronous version*: ``aget_group_permissions()``
|
||
|
||
Returns an empty set.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aget_group_permissions()`` function was added.
|
||
|
||
.. method:: get_all_permissions(user_obj, obj=None)
|
||
.. method:: aget_all_permissions(user_obj, obj=None)
|
||
|
||
*Asynchronous version*: ``aget_all_permissions()``
|
||
|
||
Uses :meth:`get_user_permissions` and :meth:`get_group_permissions` to
|
||
get the set of permission strings the ``user_obj`` has.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aget_all_permissions()`` function was added.
|
||
|
||
.. method:: has_perm(user_obj, perm, obj=None)
|
||
.. method:: ahas_perm(user_obj, perm, obj=None)
|
||
|
||
*Asynchronous version*: ``ahas_perm()``
|
||
|
||
Uses :meth:`get_all_permissions` to check if ``user_obj`` has the
|
||
permission string ``perm``.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``ahas_perm()`` function was added.
|
||
|
||
.. class:: ModelBackend
|
||
|
||
This is the default authentication backend used by Django. It
|
||
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`.
|
||
|
||
: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``.
|
||
|
||
: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``.
|
||
|
||
.. method:: authenticate(request, username=None, password=None, **kwargs)
|
||
.. method:: aauthenticate(request, username=None, password=None, **kwargs)
|
||
|
||
*Asynchronous version*: ``aauthenticate()``
|
||
|
||
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``.
|
||
|
||
``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).
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aauthenticate()`` function was added.
|
||
|
||
.. method:: get_user_permissions(user_obj, obj=None)
|
||
.. method:: aget_user_permissions(user_obj, obj=None)
|
||
|
||
*Asynchronous version*: ``aget_user_permissions()``
|
||
|
||
Returns the set of permission strings the ``user_obj`` has from their
|
||
own user permissions. Returns an empty set if
|
||
:attr:`~django.contrib.auth.models.AbstractBaseUser.is_anonymous` or
|
||
:attr:`~django.contrib.auth.models.CustomUser.is_active` is ``False``.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aget_user_permissions()`` function was added.
|
||
|
||
.. method:: get_group_permissions(user_obj, obj=None)
|
||
.. method:: aget_group_permissions(user_obj, obj=None)
|
||
|
||
*Asynchronous version*: ``aget_group_permissions()``
|
||
|
||
Returns the set of permission strings the ``user_obj`` has from the
|
||
permissions of the groups they belong. Returns an empty set if
|
||
:attr:`~django.contrib.auth.models.AbstractBaseUser.is_anonymous` or
|
||
:attr:`~django.contrib.auth.models.CustomUser.is_active` is ``False``.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aget_group_permissions()`` function was added.
|
||
|
||
.. method:: get_all_permissions(user_obj, obj=None)
|
||
.. method:: aget_all_permissions(user_obj, obj=None)
|
||
|
||
*Asynchronous version*: ``aget_all_permissions()``
|
||
|
||
Returns the set of permission strings the ``user_obj`` has, including both
|
||
user permissions and group permissions. Returns an empty set if
|
||
:attr:`~django.contrib.auth.models.AbstractBaseUser.is_anonymous` or
|
||
:attr:`~django.contrib.auth.models.CustomUser.is_active` is ``False``.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aget_all_permissions()`` function was added.
|
||
|
||
.. method:: has_perm(user_obj, perm, obj=None)
|
||
.. method:: ahas_perm(user_obj, perm, obj=None)
|
||
|
||
*Asynchronous version*: ``ahas_perm()``
|
||
|
||
Uses :meth:`get_all_permissions` to check if ``user_obj`` has the
|
||
permission string ``perm``. Returns ``False`` if the user is not
|
||
:attr:`~django.contrib.auth.models.CustomUser.is_active`.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``ahas_perm()`` function was added.
|
||
|
||
.. method:: has_module_perms(user_obj, app_label)
|
||
.. method:: ahas_module_perms(user_obj, app_label)
|
||
|
||
*Asynchronous version*: ``ahas_module_perms()``
|
||
|
||
Returns whether the ``user_obj`` has any permissions on the app
|
||
``app_label``.
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``ahas_module_perms()`` function was added.
|
||
|
||
.. method:: user_can_authenticate()
|
||
|
||
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.
|
||
|
||
.. 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.
|
||
|
||
.. class:: AllowAllUsersModelBackend
|
||
|
||
Same as :class:`ModelBackend` except that it doesn't reject inactive users
|
||
because :meth:`~ModelBackend.user_can_authenticate` always returns ``True``.
|
||
|
||
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.
|
||
|
||
.. 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.
|
||
|
||
If you need more control, you can create your own authentication backend
|
||
that inherits from this class and override these attributes or methods:
|
||
|
||
.. attribute:: create_unknown_user
|
||
|
||
``True`` or ``False``. Determines whether or not a user object is
|
||
created if not already in the database Defaults to ``True``.
|
||
|
||
.. method:: authenticate(request, remote_user)
|
||
.. method:: aauthenticate(request, remote_user)
|
||
|
||
*Asynchronous version*: ``aauthenticate()``
|
||
|
||
The username passed as ``remote_user`` is considered trusted. This
|
||
method returns the user object with the given username, creating a new
|
||
user object if :attr:`~RemoteUserBackend.create_unknown_user` is
|
||
``True``.
|
||
|
||
Returns ``None`` if :attr:`~RemoteUserBackend.create_unknown_user` is
|
||
``False`` and a ``User`` object with the given username is not found in
|
||
the database.
|
||
|
||
``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).
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aauthenticate()`` function was added.
|
||
|
||
.. method:: clean_username(username)
|
||
|
||
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.
|
||
|
||
.. method:: configure_user(request, user, created=True)
|
||
.. method:: aconfigure_user(request, user, created=True)
|
||
|
||
*Asynchronous version*: ``aconfigure_user()``
|
||
|
||
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. When fetching or creating an user is called
|
||
from a synchronous context, ``configure_user`` is called,
|
||
``aconfigure_user`` is called from async contexts.
|
||
|
||
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.
|
||
|
||
``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).
|
||
|
||
.. versionchanged:: 5.2
|
||
|
||
``aconfigure_user()`` function was added.
|
||
|
||
.. method:: user_can_authenticate()
|
||
|
||
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.
|
||
|
||
.. class:: AllowAllUsersRemoteUserBackend
|
||
|
||
Same as :class:`RemoteUserBackend` except that it doesn't reject inactive
|
||
users because :attr:`~RemoteUserBackend.user_can_authenticate` always
|
||
returns ``True``.
|
||
|
||
Utility functions
|
||
=================
|
||
|
||
.. currentmodule:: django.contrib.auth
|
||
|
||
.. function:: get_user(request)
|
||
.. function:: aget_user(request)
|
||
|
||
*Asynchronous version*: ``aget_user()``
|
||
|
||
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`
|
||
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`.
|
||
|
||
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.
|
||
|