691 lines
25 KiB
Plaintext
691 lines
25 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
|
||
==============
|
||
|
||
Fields
|
||
------
|
||
|
||
.. class:: models.User
|
||
|
||
: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>`. 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.
|
||
|
||
.. admonition:: Usernames and Unicode
|
||
|
||
Django originally accepted only ASCII letters in usernames.
|
||
Although it wasn't a deliberate choice, Unicode characters have
|
||
always been accepted when using Python 3. Django 1.10 officially
|
||
added Unicode support in usernames, keeping the ASCII-only behavior
|
||
on Python 2, with the option to customize the behavior using
|
||
:attr:`.User.username_validator`.
|
||
|
||
.. versionchanged:: 1.10
|
||
|
||
The ``max_length`` increased from 30 to 150 characters.
|
||
|
||
.. attribute:: first_name
|
||
|
||
Optional. 30 characters or fewer.
|
||
|
||
.. attribute:: last_name
|
||
|
||
Optional. 30 characters or fewer.
|
||
|
||
.. attribute:: email
|
||
|
||
Optional. 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. 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. Designates whether this user can access the admin site.
|
||
|
||
.. attribute:: is_active
|
||
|
||
Boolean. Designates whether this user account should be considered
|
||
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.
|
||
|
||
.. versionchanged:: 1.10
|
||
|
||
In older versions,
|
||
:class:`~django.contrib.auth.backends.ModelBackend` and
|
||
:class:`~django.contrib.auth.backends.RemoteUserBackend` allowed
|
||
inactive users to authenticate.
|
||
|
||
.. attribute:: is_superuser
|
||
|
||
Boolean. Designates that this user has all permissions without
|
||
explicitly assigning them.
|
||
|
||
.. attribute:: last_login
|
||
|
||
A datetime of the user's last login.
|
||
|
||
.. attribute:: date_joined
|
||
|
||
A datetime designating when the account was created. Is set to the
|
||
current date/time by default when the account is created.
|
||
|
||
Attributes
|
||
----------
|
||
|
||
.. class:: models.User
|
||
|
||
.. 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.
|
||
|
||
.. versionchanged:: 1.10
|
||
|
||
In older versions, this was a method. Backwards-compatibility
|
||
support for using it as a method will be removed in Django 2.0.
|
||
|
||
.. 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.
|
||
|
||
.. versionchanged:: 1.10
|
||
|
||
In older versions, this was a method. Backwards-compatibility
|
||
support for using it as a method will be removed in Django 2.0.
|
||
|
||
.. attribute:: username_validator
|
||
|
||
.. versionadded:: 1.10
|
||
|
||
Points to a validator instance used to validate usernames. Defaults to
|
||
:class:`validators.UnicodeUsernameValidator` on Python 3 and
|
||
:class:`validators.ASCIIUsernameValidator` on Python 2.
|
||
|
||
To change the default username validator, you can subclass the ``User``
|
||
model and set this attribute to a different validator instance. For
|
||
example, to use ASCII usernames on Python 3::
|
||
|
||
from django.contrib.auth.models import User
|
||
from django.contrib.auth.validators import ASCIIUsernameValidator
|
||
|
||
class CustomUser(User):
|
||
username_validator = ASCIIUsernameValidator()
|
||
|
||
class Meta:
|
||
proxy = True # If no new field is added.
|
||
|
||
Methods
|
||
-------
|
||
|
||
.. class:: models.User
|
||
|
||
.. 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)
|
||
|
||
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. 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.
|
||
|
||
.. method:: has_usable_password()
|
||
|
||
Returns ``False`` if
|
||
:meth:`~django.contrib.auth.models.User.set_unusable_password()` has
|
||
been called for this user.
|
||
|
||
.. method:: get_group_permissions(obj=None)
|
||
|
||
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.
|
||
|
||
.. 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
|
||
inactive, this method will always return ``False``.
|
||
|
||
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,
|
||
this method will always return ``False``.
|
||
|
||
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
|
||
always return ``False``.
|
||
|
||
.. 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)
|
||
|
||
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.
|
||
|
||
.. method:: create_superuser(username, email, password, **extra_fields)
|
||
|
||
Same as :meth:`create_user`, but sets :attr:`~models.User.is_staff` and
|
||
:attr:`~models.User.is_superuser` to ``True``.
|
||
|
||
``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
|
||
|
||
.. attribute:: name
|
||
|
||
Required. 255 characters or fewer. Example: ``'Can vote'``.
|
||
|
||
.. attribute:: content_type
|
||
|
||
Required. A reference to the ``django_content_type`` database table,
|
||
which contains a record for each installed 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
|
||
|
||
.. attribute:: name
|
||
|
||
Required. 80 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
|
||
|
||
.. versionadded:: 1.10
|
||
|
||
A field validator allowing only ASCII letters, in addition to ``@``, ``.``,
|
||
``+``, ``-``, and ``_``. The default validator for ``User.username`` on
|
||
Python 2.
|
||
|
||
.. class:: validators.UnicodeUsernameValidator
|
||
|
||
.. versionadded:: 1.10
|
||
|
||
A field validator allowing Unicode letters, in addition to ``@``, ``.``,
|
||
``+``, ``-``, and ``_``. The default validator for ``User.username`` on
|
||
Python 3.
|
||
|
||
.. _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.
|
||
|
||
.. function:: 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.
|
||
|
||
.. function:: 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.
|
||
|
||
.. function:: 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`.
|
||
|
||
.. versionchanged:: 1.11
|
||
|
||
The ``request`` argument was added.
|
||
|
||
.. _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:: 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``.
|
||
|
||
.. method:: authenticate(request, username=None, password=None, **kwargs)
|
||
|
||
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:: 1.11
|
||
|
||
The ``request`` argument was added.
|
||
|
||
.. method:: get_user_permissions(user_obj, obj=None)
|
||
|
||
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``.
|
||
|
||
.. method:: get_group_permissions(user_obj, obj=None)
|
||
|
||
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``.
|
||
|
||
.. method:: get_all_permissions(user_obj, obj=None)
|
||
|
||
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``.
|
||
|
||
.. 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
|
||
:attr:`~django.contrib.auth.models.CustomUser.is_active`.
|
||
|
||
.. method:: has_module_perms(self, user_obj, app_label)
|
||
|
||
Returns whether the ``user_obj`` has any permissions on the app
|
||
``app_label``.
|
||
|
||
.. method:: ModelBackend.user_can_authenticate()
|
||
|
||
.. versionadded:: 1.10
|
||
|
||
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.
|
||
|
||
.. class:: AllowAllUsersModelBackend
|
||
|
||
.. versionadded:: 1.10
|
||
|
||
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:: RemoteUserBackend.create_unknown_user
|
||
|
||
``True`` or ``False``. Determines whether or not a
|
||
:class:`~django.contrib.auth.models.User` object is created if not already
|
||
in the database. Defaults to ``True``.
|
||
|
||
.. method:: RemoteUserBackend.authenticate(request, remote_user)
|
||
|
||
The username passed as ``remote_user`` is considered trusted. This method
|
||
simply 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).
|
||
|
||
.. method:: RemoteUserBackend.clean_username(username)
|
||
|
||
Performs any cleaning on the ``username`` (e.g. stripping LDAP DN
|
||
information) prior to using it to get or create a
|
||
:class:`~django.contrib.auth.models.User` object. Returns the cleaned
|
||
username.
|
||
|
||
.. method:: RemoteUserBackend.configure_user(user)
|
||
|
||
Configures a newly created user. This method is called immediately after a
|
||
new user is created, 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.
|
||
|
||
.. method:: RemoteUserBackend.user_can_authenticate()
|
||
|
||
.. versionadded:: 1.10
|
||
|
||
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
|
||
|
||
.. versionadded:: 1.10
|
||
|
||
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)
|
||
|
||
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.
|
||
|
||
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.
|