=============================

User authentication in Django

=============================

.. module:: django.contrib.auth

   :synopsis: Django's authentication framework.

Django comes with a user authentication system. It handles user accounts,

groups, permissions and cookie-based user sessions. This document explains how

things work.

Overview

========

The auth system consists of:

    * Users

    * Permissions: Binary (yes/no) flags designating whether a user may perform

      a certain task.

    * Groups: A generic way of applying labels and permissions to more than one

      user.

    * Messages: A simple way to queue messages for given users.

.. deprecated:: 1.2

   The Messages component of the auth system will be removed in Django 1.4.

Installation

============

Authentication support is bundled as a Django application in

``django.contrib.auth``. To install it, do the following:

    1. Put ``'django.contrib.auth'`` and ``'django.contrib.contenttypes'`` in

       your :setting:`INSTALLED_APPS` setting.

       (The :class:`~django.contrib.auth.models.Permission` model in

       :mod:`django.contrib.auth` depends on :mod:`django.contrib.contenttypes`.)

    2. Run the command ``manage.py syncdb``.

Note that the default :file:`settings.py` file created by

:djadmin:`django-admin.py startproject <startproject>` includes

``'django.contrib.auth'`` and ``'django.contrib.contenttypes'`` in

:setting:`INSTALLED_APPS` for convenience.  If your :setting:`INSTALLED_APPS`

already contains these apps, feel free to run :djadmin:`manage.py syncdb

<syncdb>` again; you can run that command as many times as you'd like, and each

time it'll only install what's needed.

The :djadmin:`syncdb` command creates the necessary database tables, creates

permission objects for all installed apps that need 'em, and prompts you to

create a superuser account the first time you run it.

Once you've taken those steps, that's it.

Users

=====

.. class:: models.User

API reference

-------------

Fields

~~~~~~

.. class:: models.User

    :class:`~django.contrib.auth.models.User` objects have the following

    fields:

    .. attribute:: models.User.username

        Required. 30 characters or fewer. Alphanumeric characters only

        (letters, digits and underscores).

        .. versionchanged:: 1.2

           Usernames may now contain ``@``, ``+``, ``.`` and ``-`` characters.

    .. attribute:: models.User.first_name

        Optional. 30 characters or fewer.

    .. attribute:: models.User.last_name

        Optional. 30 characters or fewer.

    .. attribute:: models.User.email

        Optional. E-mail address.

    .. attribute:: models.User.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 "Passwords" section below.

    .. attribute:: models.User.is_staff

        Boolean. Designates whether this user can access the admin site.

    .. attribute:: models.User.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, so 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.

        However, the :class:`~django.contrib.auth.forms.AuthenticationForm`

        used by the :func:`~django.contrib.auth.views.login` view *does*

        perform this check, as do the permission-checking methods such as

        :meth:`~models.User.has_perm` and the authentication in the Django

        admin. All of those functions/methods will return ``False`` for

        inactive users.

    .. attribute:: models.User.is_superuser

        Boolean. Designates that this user has all permissions without

        explicitly assigning them.

    .. attribute:: models.User.last_login

        A datetime of the user's last login. Is set to the current date/time by

        default.

    .. attribute:: models.User.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

    :class:`~django.contrib.auth.models.User` objects have two many-to-many

    fields: models.User. ``groups`` and ``user_permissions``.

    :class:`~django.contrib.auth.models.User` objects can access their related

    objects in the same way as any other :doc:`Django model

    </topics/db/models>`:

    .. code-block:: python

        myuser.groups = [group_list]

        myuser.groups.add(group, group, ...)

        myuser.groups.remove(group, group, ...)

        myuser.groups.clear()

        myuser.user_permissions = [permission_list]

        myuser.user_permissions.add(permission, permission, ...)

        myuser.user_permissions.remove(permission, permission, ...)

        myuser.user_permissions.clear()

    In addition to those automatic API methods,

    :class:`~django.contrib.auth.models.User` objects have the following custom

    methods:

    .. method:: models.User.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:: models.User.is_authenticated()

        Always returns ``True``. 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 - it only indicates that the user has provided a

        valid username and password.

    .. method:: models.User.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:: models.User.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:: models.User.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:: models.User.set_unusable_password()

        .. versionadded:: 1.0

        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:: models.User.has_usable_password()

        .. versionadded:: 1.0

        Returns ``False`` if

        :meth:`~django.contrib.auth.models.User.set_unusable_password()` has

        been called for this user.

    .. method:: models.User.get_group_permissions(obj=None)

        Returns a set of permission strings that the user has, through his/her

        groups.

        .. versionadded:: 1.2

        If ``obj`` is passed in, only returns the group permissions for

        this specific object.

    .. method:: models.User.get_all_permissions(obj=None)

        Returns a set of permission strings that the user has, both through

        group and user permissions.

        .. versionadded:: 1.2

        If ``obj`` is passed in, only returns the permissions for this

        specific object.

    .. method:: models.User.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

        `permissions`_ section below). If the user is inactive, this method will

        always return ``False``.

        .. versionadded:: 1.2

        If ``obj`` is passed in, this method won't check for a permission for

        the model, but for this specific object.

    .. method:: models.User.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``.

        .. versionadded:: 1.2

        If ``obj`` is passed in, this method won't check for permissions for

        the model, but for the specific object.

    .. method:: models.User.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:: models.User.get_and_delete_messages()

        Returns a list of :class:`~django.contrib.auth.models.Message` objects

        in the user's queue and deletes the messages from the queue.

    .. method:: models.User.email_user(subject, message, from_email=None)

        Sends an e-mail to the user. If

        :attr:`~django.contrib.auth.models.User.from_email` is ``None``, Django

        uses the :setting:`DEFAULT_FROM_EMAIL`.

    .. method:: models.User.get_profile()

        Returns a site-specific profile for this user. Raises

        :exc:`django.contrib.auth.models.SiteProfileNotAvailable` if the

        current site doesn't allow profiles. For information on how to define a

        site-specific user profile, see the section on `storing additional user

        information`_ below.

.. _storing additional user information: #storing-additional-information-about-users

Manager functions

~~~~~~~~~~~~~~~~~

.. class:: models.UserManager

    The :class:`~django.contrib.auth.models.User` model has a custom manager

    that has the following helper functions:

    .. method:: models.UserManager.create_user(username, email, password=None)

        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 convered to lowercase, and the returned

        :class:`~django.contrib.auth.models.User` object will have

        :attr:`~models.User.is_active` set to ``True``.

        If no password is provided,

        :meth:`~django.contrib.auth.models.User.set_unusable_password()` will

        be called.

        See `Creating users`_ for example usage.

    .. method:: models.UserManager.make_random_password(length=10, allowed_chars='abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789')

        Returns a random password with the given length and given string of

        allowed characters. (Note that the default value of ``allowed_chars``

        doesn't contain letters that can cause user confusion, including:

            * ``i``, ``l``, ``I``, and ``1`` (lowercase letter i, lowercase

              letter L, uppercase letter i, and the number one)

            * ``o``, ``O``, and ``0`` (uppercase letter o, lowercase letter o,

              and zero)

Basic usage

-----------

.. _topics-auth-creating-users:

Creating users

~~~~~~~~~~~~~~

The most basic way to create users is to use the

:meth:`~django.contrib.auth.models.UserManager.create_user` helper function

that comes with Django::

    >>> from django.contrib.auth.models import User

    >>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword')

    # At this point, user is a User object that has already been saved

    # to the database. You can continue to change its attributes

    # if you want to change other fields.

    >>> user.is_staff = True

    >>> user.save()

You can also create users using the Django admin site. Assuming you've enabled

the admin site and hooked it to the URL ``/admin/``, the "Add user" page is at

``/admin/auth/user/add/``. You should also see a link to "Users" in the "Auth"

section of the main admin index page. The "Add user" admin page is different

than standard admin pages in that it requires you to choose a username and

password before allowing you to edit the rest of the user's fields.

Also note: if you want your own user account to be able to create users using

the Django admin site, you'll need to give yourself permission to add users

*and* change users (i.e., the "Add user" and "Change user" permissions). If

your account has permission to add users but not to change them, you won't be

able to add users. Why? Because if you have permission to add users, you have

the power to create superusers, which can then, in turn, change other users. So

Django requires add *and* change permissions as a slight security measure.

Changing passwords

~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.2

   The ``manage.py changepassword`` command was added.

:djadmin:`manage.py changepassword *username* <changepassword>` offers a method

of changing a User's password from the command line. It prompts you to

change the password of a given user which you must enter twice. If

they both match, the new password will be changed immediately. If you

do not supply a user, the command will attempt to change the password

whose username matches the current user.

You can also change a password programmatically, using

:meth:`~django.contrib.auth.models.User.set_password()`:

.. code-block:: python

    >>> from django.contrib.auth.models import User

    >>> u = User.objects.get(username__exact='john')

    >>> u.set_password('new password')

    >>> u.save()

Don't set the :attr:`~django.contrib.auth.models.User.password` attribute

directly unless you know what you're doing. This is explained in the next

section.

Passwords

---------

The :attr:`~django.contrib.auth.models.User.password` attribute of a

:class:`~django.contrib.auth.models.User` object is a string in this format::

    hashtype$salt$hash

That's hashtype, salt and hash, separated by the dollar-sign character.

Hashtype is either ``sha1`` (default), ``md5`` or ``crypt`` -- the algorithm

used to perform a one-way hash of the password. Salt is a random string used

to salt the raw password to create the hash. Note that the ``crypt`` method is

only supported on platforms that have the standard Python ``crypt`` module

available.

.. versionadded:: 1.0

    Support for the ``crypt`` module is new in Django 1.0.

For example::

    sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4

The :meth:`~django.contrib.auth.models.User.set_password` and

:meth:`~django.contrib.auth.models.User.check_password` functions handle the

setting and checking of these values behind the scenes.

Previous Django versions, such as 0.90, used simple MD5 hashes without password

salts. For backwards compatibility, those are still supported; they'll be

converted automatically to the new style the first time

:meth:`~django.contrib.auth.models.User.check_password()` works correctly for

a given user.

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:

    * :attr:`~django.contrib.auth.models.User.id` 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.contrib.auth.models.User.save()`,

      :meth:`~django.contrib.auth.models.User.delete()`,

      :meth:`~django.contrib.auth.models.User.set_groups()` and

      :meth:`~django.contrib.auth.models.User.set_permissions()` 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.

.. _topics-auth-creating-superusers:

Creating superusers

-------------------

.. versionadded:: 1.0

   The ``manage.py createsuperuser`` command is new.

:djadmin:`manage.py syncdb <syncdb>` prompts you to create a superuser the

first time you run it after adding ``'django.contrib.auth'`` to your

:setting:`INSTALLED_APPS`. If you need to create a superuser at a later date,

you can use a command line utility::

    manage.py createsuperuser --username=joe --email=joe@example.com

You will be prompted for a password. After you enter one, the user will be

created immediately. If you leave off the :djadminopt:`--username` or the

:djadminopt:`--email` options, it will prompt you for those values.

If you're using an older release of Django, the old way of creating a superuser

on the command line still works::

    python /path/to/django/contrib/auth/create_superuser.py

...where :file:`/path/to` is the path to the Django codebase on your

filesystem. The ``manage.py`` command is preferred because it figures out the

correct path and environment for you.

.. _auth-profiles:

Storing additional information about users

------------------------------------------

If you'd like to store additional information related to your users, Django

provides a method to specify a site-specific related model -- termed a "user

profile" -- for this purpose.

To make use of this feature, define a model with fields for the

additional information you'd like to store, or additional methods

you'd like to have available, and also add a

:class:`~django.db.models.Field.OneToOneField` from your model to the

:class:`~django.contrib.auth.models.User` model. This will ensure only

one instance of your model can be created for each

:class:`~django.contrib.auth.models.User`.

To indicate that this model is the user profile model for a given site, fill in

the setting :setting:`AUTH_PROFILE_MODULE` with a string consisting of the

following items, separated by a dot:

1. The name of the application (case sensitive) in which the user

   profile model is defined (in other words, the

   name which was passed to :djadmin:`manage.py startapp <startapp>` to create

   the application).

2. The name of the model (not case sensitive) class.

For example, if the profile model was a class named ``UserProfile`` and was

defined inside an application named ``accounts``, the appropriate setting would

be::

    AUTH_PROFILE_MODULE = 'accounts.UserProfile'

When a user profile model has been defined and specified in this manner, each

:class:`~django.contrib.auth.models.User` object will have a method --

:class:`~django.contrib.auth.models.User.get_profile()` -- which returns the

instance of the user profile model associated with that

:class:`~django.contrib.auth.models.User`.

The method :class:`~django.contrib.auth.models.User.get_profile()`

does not create the profile, if it does not exist. You need to

register a handler for the signal

:attr:`django.db.models.signals.post_save` on the User model, and, in

the handler, if created=True, create the associated user profile.

For more information, see `Chapter 12 of the Django book`_.

.. _Chapter 12 of the Django book: http://www.djangobook.com/en/1.0/chapter12/#cn222

Authentication in Web requests

==============================