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

User authentication in Django

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

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.

Installation

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

Authentication support is bundled as a Django application in

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

    1. Put ``'django.contrib.auth'`` in your ``INSTALLED_APPS`` setting.

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

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

``django-admin.py startproject`` includes ``'django.contrib.auth'`` in

``INSTALLED_APPS`` for convenience. If your ``INSTALLED_APPS`` already contains

``'django.contrib.auth'``, feel free to run ``manage.py 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 ``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

=====

Users are represented by a standard Django model, which lives in

`django/contrib/auth/models.py`_.

.. _django/contrib/auth/models.py: http://code.djangoproject.com/browser/django/trunk/django/contrib/auth/models.py

API reference

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

Fields

~~~~~~

``User`` objects have the following fields:

    * ``username`` -- Required. 30 characters or fewer. Alphanumeric characters

      only (letters, digits and underscores).

    * ``first_name`` -- Optional. 30 characters or fewer.

    * ``last_name`` -- Optional. 30 characters or fewer.

    * ``email`` -- Optional. E-mail address.

    * ``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.

    * ``is_staff`` -- Boolean. Designates whether this user can access the

      admin site.

    * ``is_active`` -- Boolean. Designates whether this account can be used

      to log in. Set this flag to ``False`` instead of deleting accounts.

    * ``is_superuser`` -- Boolean. Designates that this user has all permissions

      without explicitly assigning them.

    * ``last_login`` -- A datetime of the user's last login. Is set to the

      current date/time by default.

    * ``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

~~~~~~~

``User`` objects have two many-to-many fields: ``groups`` and

``user_permissions``. ``User`` objects can access their related

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

    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, ``User`` objects have the following

custom methods:

    * ``is_anonymous()`` -- Always returns ``False``. This is a way of

      differentiating ``User`` and ``AnonymousUser`` objects. Generally, you

      should prefer using ``is_authenticated()`` to this method.

    * ``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.

    * ``get_full_name()`` -- Returns the ``first_name`` plus the ``last_name``,

      with a space in between.

    * ``set_password(raw_password)`` -- Sets the user's password to the given

      raw string, taking care of the password hashing. Doesn't save the

      ``User`` object.

    * ``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.)

    * ``get_group_permissions()`` -- Returns a list of permission strings that

      the user has, through his/her groups.

    * ``get_all_permissions()`` -- Returns a list of permission strings that

      the user has, both through group and user permissions.

    * ``has_perm(perm)`` -- Returns ``True`` if the user has the specified

      permission, where perm is in the format ``"package.codename"``.

      If the user is inactive, this method will always return ``False``.

    * ``has_perms(perm_list)`` -- Returns ``True`` if the user has each of the

      specified permissions, where each perm is in the format

      ``"package.codename"``. If the user is inactive, this method will 

      always return ``False``.

    * ``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``.

    * ``get_and_delete_messages()`` -- Returns a list of ``Message`` objects in

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

    * ``email_user(subject, message, from_email=None)`` -- Sends an e-mail to

      the user. If ``from_email`` is ``None``, Django uses the

      `DEFAULT_FROM_EMAIL`_ setting.

    * ``get_profile()`` -- Returns a site-specific profile for this user.

      Raises ``django.contrib.auth.models.SiteProfileNotAvailable`` if the current site

      doesn't allow profiles.

.. _Django model: ../model_api/

.. _DEFAULT_FROM_EMAIL: ../settings/#default-from-email

Manager functions

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

The ``User`` model has a custom manager that has the following helper functions:

    * ``create_user(username, email, password)`` -- Creates, saves and returns

      a ``User``. The ``username``, ``email`` and ``password`` are set as

      given, and the ``User`` gets ``is_active=True``.

      See _`Creating users` for example usage.

    * ``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 ``"I"`` or letters that look like it, to avoid user

      confusion.

Basic usage

-----------

Creating users

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

The most basic way to create users is to use the ``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 ready to be saved

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

    # if you want to change other fields.

    >>> user.is_staff = True

    >>> user.save()

Changing passwords

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

Change a password with ``set_password()``::

    >>> 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 ``password`` attribute directly unless you know what you're

doing. This is explained in the next section.

Passwords

---------

The ``password`` attribute of a ``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) or ``md5`` -- 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.

For example::

    sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4

The ``User.set_password()`` and ``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 ``check_password()``

works correctly for a given user.

Anonymous users

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

``django.contrib.auth.models.AnonymousUser`` is a class that implements

the ``django.contrib.auth.models.User`` interface, with these differences:

    * ``id`` is always ``None``.

    * ``is_anonymous()`` returns ``True`` instead of ``False``.

    * ``is_authenticated()`` returns ``False`` instead of ``True``.

    * ``has_perm()`` always returns ``False``.

    * ``set_password()``, ``check_password()``, ``save()``, ``delete()``,

      ``set_groups()`` and ``set_permissions()`` raise ``NotImplementedError``.

In practice, you probably won't need to use ``AnonymousUser`` objects on your

own, but they're used by Web requests, as explained in the next section.

Creating superusers

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

``manage.py syncdb`` prompts you to create a superuser the first time you run

it after adding ``'django.contrib.auth'`` to your ``INSTALLED_APPS``. But if

you need to create a superuser after that via the command line, you can use the

``create_superuser.py`` utility. Just run this command::

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

Make sure to substitute ``/path/to/`` with the path to the Django codebase on

your filesystem.

Authentication in Web requests

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

Until now, this document has dealt with the low-level APIs for manipulating

authentication-related objects. On a higher level, Django can hook this

authentication framework into its system of `request objects`_.

First, install the ``SessionMiddleware`` and ``AuthenticationMiddleware``

middlewares by adding them to your ``MIDDLEWARE_CLASSES`` setting. See the

`session documentation`_ for more information.

Once you have those middlewares installed, you'll be able to access

``request.user`` in views. ``request.user`` will give you a ``User`` object

representing the currently logged-in user. If a user isn't currently logged in,

``request.user`` will be set to an instance of ``AnonymousUser`` (see the

previous section). You can tell them apart with ``is_authenticated()``, like so::

    if request.user.is_authenticated():

        # Do something for authenticated users.

    else:

        # Do something for anonymous users.

.. _request objects: ../request_response/#httprequest-objects

.. _session documentation: ../sessions/

How to log a user in

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

Django provides two functions in ``django.contrib.auth``: ``authenticate()``

and ``login()``.

To authenticate a given username and password, use ``authenticate()``. It

takes two keyword arguments, ``username`` and ``password``, and it returns

a ``User`` object if the password is valid for the given username. If the

password is invalid, ``authenticate()`` returns ``None``. Example::

    from django.contrib.auth import authenticate

    user = authenticate(username='john', password='secret')

    if user is not None:

        if user.is_active:

            print "You provided a correct username and password!"

        else:

            print "Your account has been disabled!"

    else:

        print "Your username and password were incorrect."

To log a user in, in a view, use ``login()``. It takes an ``HttpRequest``

object and a ``User`` object. ``login()`` saves the user's ID in the session,

using Django's session framework, so, as mentioned above, you'll need to make

sure to have the session middleware installed.

This example shows how you might use both ``authenticate()`` and ``login()``::

    from django.contrib.auth import authenticate, login

    def my_view(request):

        username = request.POST['username']

        password = request.POST['password']

        user = authenticate(username=username, password=password)

        if user is not None:

            if user.is_active:

                login(request, user)

                # Redirect to a success page.

            else:

                # Return a 'disabled account' error message

        else:

            # Return an 'invalid login' error message.

Manually checking a user's password

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

If you'd like to manually authenticate a user by comparing a

plain-text password to the hashed password in the database, use the

convenience function `django.contrib.auth.models.check_password`. It

takes two arguments: the plain-text password to check, and the full

value of a user's ``password`` field in the database to check against,

and returns ``True`` if they match, ``False`` otherwise.

How to log a user out

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

To log out a user who has been logged in via ``django.contrib.auth.login()``,

use ``django.contrib.auth.logout()`` within your view. It takes an

``HttpRequest`` object and has no return value. Example::

    from django.contrib.auth import logout

    def logout_view(request):

        logout(request)

        # Redirect to a success page.

Note that ``logout()`` doesn't throw any errors if the user wasn't logged in.

Limiting access to logged-in users

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

The raw way

~~~~~~~~~~~

The simple, raw way to limit access to pages is to check

``request.user.is_authenticated()`` and either redirect to a login page::

    from django.http import HttpResponseRedirect

    def my_view(request):

        if not request.user.is_authenticated():

            return HttpResponseRedirect('/login/?next=%s' % request.path)

        # ...

...or display an error message::

    def my_view(request):

        if not request.user.is_authenticated():

            return render_to_response('myapp/login_error.html')

        # ...

The login_required decorator

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

As a shortcut, you can use the convenient ``login_required`` decorator::

    from django.contrib.auth.decorators import login_required

    def my_view(request):

        # ...

    my_view = login_required(my_view)

Here's an equivalent example, using the more compact decorator syntax

introduced in Python 2.4::

    from django.contrib.auth.decorators import login_required

    @login_required

    def my_view(request):

        # ...

``login_required`` does the following:

    * If the user isn't logged in, redirect to ``/accounts/login/``, passing

      the current absolute URL in the query string as ``next``. For example:

      ``/accounts/login/?next=/polls/3/``.

    * If the user is logged in, execute the view normally. The view code is

      free to assume the user is logged in.

Note that you'll need to map the appropriate Django view to ``/accounts/login/``.

To do this, add the following line to your URLconf::

    (r'^accounts/login/$', 'django.contrib.auth.views.login'),

Here's what ``django.contrib.auth.views.login`` does:

    * If called via ``GET``, it displays a login form that POSTs to the same

      URL. More on this in a bit.

    * If called via ``POST``, it tries to log the user in. If login is

      successful, the view redirects to the URL specified in ``next``. If

      ``next`` isn't provided, it redirects to ``/accounts/profile/`` (which is

      currently hard-coded). If login isn't successful, it redisplays the login

      form.

It's your responsibility to provide the login form in a template called

``registration/login.html`` by default. This template gets passed three

template context variables:

    * ``form``: A ``FormWrapper`` object representing the login form. See the

      `forms documentation`_ for more on ``FormWrapper`` objects.

    * ``next``: The URL to redirect to after successful login. This may contain

      a query string, too.

    * ``site_name``: The name of the current ``Site``, according to the

      ``SITE_ID`` setting. See the `site framework docs`_.

If you'd prefer not to call the template ``registration/login.html``, you can

pass the ``template_name`` parameter via the extra arguments to the view in

your URLconf. For example, this URLconf line would use ``myapp/login.html``

instead::

    (r'^accounts/login/$', 'django.contrib.auth.views.login', {'template_name': 'myapp/login.html'}),

Here's a sample ``registration/login.html`` template you can use as a starting

point. It assumes you have a ``base.html`` template that defines a ``content``

block::

    {% extends "base.html" %}

    {% block content %}

    {% if form.has_errors %}

    <p>Your username and password didn't match. Please try again.</p>

    {% endif %}

    <form method="post" action=".">

    <table>

    <tr><td><label for="id_username">Username:</label></td><td>{{ form.username }}</td></tr>

    <tr><td><label for="id_password">Password:</label></td><td>{{ form.password }}</td></tr>

    </table>

    <input type="submit" value="login" />

    <input type="hidden" name="next" value="{{ next }}" />

    </form>

    {% endblock %}

.. _forms documentation: ../forms/

.. _site framework docs: ../sites/

Other built-in views

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

In addition to the `login` view, the authentication system includes a

few other useful built-in views:

``django.contrib.auth.views.logout``

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

**Description:**

Logs a user out.

**Optional arguments:**

    * ``template_name``: The full name of a template to display after

      logging the user out. This will default to

      ``registration/logged_out.html`` if no argument is supplied.

**Template context:**

    * ``title``: The string "Logged out", localized.

``django.contrib.auth.views.logout_then_login``

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

**Description:**

Logs a user out, then redirects to the login page.

**Optional arguments:**

    * ``login_url``: The URL of the login page to redirect to. This

      will default to ``/accounts/login/`` if not supplied.

``django.contrib.auth.views.password_change``

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

**Description:**

Allows a user to change their password.

**Optional arguments:**

    * ``template_name``: The full name of a template to use for

      displaying the password change form. This will default to

      ``registration/password_change_form.html`` if not supplied.

**Template context:**

    * ``form``: The password change form.

``django.contrib.auth.views.password_change_done``

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

**Description:**

The page shown after a user has changed their password.

**Optional arguments:**

    * ``template_name``: The full name of a template to use. This will

      default to ``registration/password_change_done.html`` if not

      supplied.

``django.contrib.auth.views.password_reset``

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

**Description:**

Allows a user to reset their password, and sends them the new password

in an email.