mirror of
https://github.com/django/django.git
synced 2024-11-30 15:10:46 +01:00
536 lines
19 KiB
Plaintext
536 lines
19 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
|
||
====
|
||
|
||
Fields
|
||
------
|
||
|
||
.. class:: models.User
|
||
|
||
:class:`~django.contrib.auth.models.User` objects have the following
|
||
fields:
|
||
|
||
.. attribute:: username
|
||
|
||
Required. 30 characters or fewer. Usernames may contain alphanumeric,
|
||
``_``, ``@``, ``+``, ``.`` and ``-`` 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, and the default backends do not. If you want to reject a login
|
||
based on ``is_active`` being ``False``, it's up to you to check that in
|
||
your own login view or a custom authentication backend. However, the
|
||
:class:`~django.contrib.auth.forms.AuthenticationForm` used by the
|
||
:func:`~django.contrib.auth.views.login` view (which is the default)
|
||
*does* perform this check, as do the permission-checking methods such
|
||
as :meth:`~django.contrib.auth.models.User.has_perm` and the
|
||
authentication in the Django admin. All of those functions/methods will
|
||
return ``False`` for inactive users.
|
||
|
||
.. 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.
|
||
|
||
.. versionchanged:: 1.8
|
||
|
||
This field will be ``null`` if the user has never logged in.
|
||
Previously it was set to the current date/time by default.
|
||
|
||
.. 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.
|
||
|
||
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:: is_anonymous()
|
||
|
||
Always returns ``False``. This is a way of differentiating
|
||
:class:`~django.contrib.auth.models.User` and
|
||
:class:`~django.contrib.auth.models.AnonymousUser` objects.
|
||
Generally, you should prefer using
|
||
:meth:`~django.contrib.auth.models.User.is_authenticated()` to this
|
||
method.
|
||
|
||
.. method:: is_authenticated()
|
||
|
||
Always returns ``True`` (as opposed to
|
||
``AnonymousUser.is_authenticated()`` which always returns ``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 call this method 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 method
|
||
returns ``True`` for any :class:`~django.contrib.auth.models.User`
|
||
instance.
|
||
|
||
.. 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``.
|
||
|
||
|
||
Anonymous users
|
||
===============
|
||
|
||
.. 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_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.is_anonymous()` returns ``True``
|
||
instead of ``False``.
|
||
* :meth:`~django.contrib.auth.models.User.is_authenticated()` returns
|
||
``False`` instead of ``True``.
|
||
* :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`.
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
``AnonymousUser.get_username()`` has been added to
|
||
better mirror :class:`django.contrib.auth.models.User`.
|
||
|
||
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
|
||
==========
|
||
|
||
.. 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'``.
|
||
|
||
.. versionchanged:: 1.8
|
||
|
||
The ``max_length`` increased from 50 to 255 characters.
|
||
|
||
.. 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
|
||
=====
|
||
|
||
.. 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 = [permission_list]
|
||
group.permissions.add(permission, permission, ...)
|
||
group.permissions.remove(permission, permission, ...)
|
||
group.permissions.clear()
|
||
|
||
.. _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.
|
||
|
||
.. _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(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``.
|
||
|
||
.. method:: get_user_permissions(user_obj, obj=None)
|
||
|
||
.. versionadded:: 1.8
|
||
|
||
Returns the set of permission strings the ``user_obj`` has from their
|
||
own user permissions. Returns an empty set if
|
||
:meth:`~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
|
||
:meth:`~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
|
||
:meth:`~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``.
|
||
|
||
.. 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(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.
|
||
|
||
.. 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.
|