| ``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. |
| |
| .. 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 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) |
| |
| .. versionchanged:: 1.4 |
| The ``email`` parameter was made optional. The username |
| parameter is now checked for emptiness and raises a |
| :exc:`~exceptions.ValueError` in case of a negative result. |
| |
| 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. |
