mirror of https://github.com/django/django.git
454 lines
16 KiB
Plaintext
454 lines
16 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. Is 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:: 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.
|
|
|
|
.. versionchanged:: 1.6
|
|
|
|
In Django 1.4 and 1.5, a blank string was unintentionally stored
|
|
as an unsable password.
|
|
|
|
.. 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.)
|
|
|
|
.. versionchanged:: 1.6
|
|
|
|
In Django 1.4 and 1.5, a blank string was unintentionally
|
|
considered to be an unusable password, resulting in this method
|
|
returning ``False`` for such a password.
|
|
|
|
.. 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 his/her
|
|
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)
|
|
|
|
Sends an email to the user. If ``from_email`` is ``None``, Django uses
|
|
the :setting:`DEFAULT_FROM_EMAIL`.
|
|
|
|
.. method:: get_profile()
|
|
|
|
.. deprecated:: 1.5
|
|
With the introduction of :ref:`custom User models <auth-custom-user>`,
|
|
the use of :setting:`AUTH_PROFILE_MODULE` to define a single profile
|
|
model is no longer supported. See the
|
|
:doc:`Django 1.5 release notes</releases/1.5>` for more information.
|
|
|
|
Returns a site-specific profile for this user. Raises
|
|
``django.contrib.auth.models.SiteProfileNotAvailable`` if the
|
|
current site doesn't allow profiles, or
|
|
:exc:`django.core.exceptions.ObjectDoesNotExist` if the user does not
|
|
have a profile.
|
|
|
|
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(self, 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.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:`~exceptions.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
|
|
==========
|
|
|
|
.. class:: models.Permission
|
|
|
|
Fields
|
|
------
|
|
|
|
:class:`~django.contrib.auth.models.Permission` objects have the following
|
|
fields:
|
|
|
|
.. attribute:: name
|
|
|
|
Required. 50 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 Django 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:
|
|
|
|
.. 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
|
|
|
|
.. versionadded:: 1.5
|
|
|
|
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`.
|
|
|
|
.. 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.
|