<commit_before>.. _topics-auth:

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

    .. 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 :ref:`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 list 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 list 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`,
        :attr:`~django.contrib.auth.models.User.email` and
        :attr:`~django.contrib.auth.models.User.password` are set as given, and the
        :class:`~django.contrib.auth.models.User` gets ``is_active=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', '<EMAIL>', '<PASSWORD>')

    # 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>` 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('<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.has_perm()` always returns
      ``False``.
    * :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=<EMAIL>

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.ForeignKey` from your
model to the :class:`~django.contrib.auth.models.User` model, specified with
``unique=True`` to 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
==============================

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
:class:`request objects <django.http.HttpRequest>`.

First, install the
:class:`~django.contrib.sessions.middleware.SessionMiddleware` and
:class:`~django.contrib.auth.middleware.AuthenticationMiddleware`
middlewares by adding them to your :setting:`MIDDLEWARE_CLASSES` setting. See
the :ref:`session documentation <topics-http-sessions>` for more information.

Once you have those middlewares installed, you'll be able to access
:attr:`request.user <django.http.HttpRequest.user>` in views.
:attr:`request.user <django.http.HttpRequest.user>` will give you a
:class:`~django.contrib.auth.models.User` object representing the currently
logged-in user. If a user isn't currently logged in,
:attr:`request.user <django.http.HttpRequest.user>` will be set to an instance
of :class:`~django.contrib.auth.models.AnonymousUser` (see the previous
section). You can tell them apart with
:meth:`~django.contrib.auth.models.User.is_authenticated()`, like so::

    if request.user.is_authenticated():
        # Do something for authenticated users.
    else:
        # Do something for anonymous users.

.. _howtologauserin:

How to log a user in
--------------------

Django provides two functions in :mod:`django.contrib.auth`:
:func:`~django.contrib.auth.authenticate()` and
:func:`~django.contrib.auth.login()`.

.. function:: authenticate()

    To authenticate a given username and password, use
    :func:`~django.contrib.auth.authenticate()`. It takes two keyword
    arguments, ``username`` and ``password``, and it returns a
    :class:`~django.contrib.auth.models.User` object if the password is valid
    for the given username. If the password is invalid,
    :func:`~django.contrib.auth.authenticate()` returns ``None``. Example::

        from django.contrib.auth import authenticate
        user = authenticate(username='john', password='<PASSWORD>')
        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."

.. function:: login()

    To log a user in, in a view, use :func:`~django.contrib.auth.login()`. It
    takes an :class:`~django.http.HttpRequest` object and a
    :class:`~django.contrib.auth.models.User` object.
    :func:`~django.contrib.auth.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
    :func:`~django.contrib.auth.authenticate()` and
    :func:`~django.contrib.auth.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.

.. admonition:: Calling ``authenticate()`` first

    When you're manually logging a user in, you *must* call
    :func:`~django.contrib.auth.authenticate()` before you call
    :func:`~django.contrib.auth.login()`.
    :func:`~django.contrib.auth.authenticate()`
    sets an attribute on the :class:`~django.contrib.auth.models.User` noting
    which authentication backend successfully authenticated that user (see the
    `backends documentation`_ for details), and this information is needed
    later during the login process.

.. _backends documentation: #other-authentication-sources

Manually checking a user's password
-----------------------------------

.. function:: check_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 :func:`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
---------------------

.. function:: logout()

    To log out a user who has been logged in via
    :func:`django.contrib.auth.login()`, use
    :func:`django.contrib.auth.logout()` within your view. It takes an
    :class:`~django.http.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 :func:`~django.contrib.auth.logout()` doesn't throw any errors if
    the user wasn't logged in.

    .. versionchanged:: 1.0
       Calling ``logout()`` now cleans session data.

    When you call :func:`~django.contrib.auth.logout()`, the session data for
    the current request is completely cleaned out. All existing data is
    removed. This is to prevent another person from using the same web browser
    to log in and have access to the previous user's session data. If you want
    to put anything into the session that will be available to the user
    immediately after logging out, do that *after* calling
    :func:`django.contrib.auth.logout()`.

Limiting access to logged-in users
----------------------------------

The raw way
~~~~~~~~~~~

The simple, raw way to limit access to pages is to check
:meth:`request.user.is_authenticated()
<django.contrib.auth.models.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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. function:: decorators.login_required()

    As a shortcut, you can use the convenient
    :func:`~django.contrib.auth.decorators.login_required` decorator::

        from django.contrib.auth.decorators import login_required

        @login_required
        def my_view(request):
            ...

    :func:`~django.contrib.auth.decorators.login_required` also takes an
    optional ``redirect_field_name`` parameter. Example::


        from django.contrib.auth.decorators import login_required

        @login_required(redirect_field_name='redirect_to')
        def my_view(request):
            ...

    :func:`~django.contrib.auth.decorators.login_required` does the following:

        * If the user isn't logged in, redirect to
          :setting:`settings.LOGIN_URL <LOGIN_URL>` (``/accounts/login/`` by
          default), passing the current absolute URL in the query string. The
          name of the GET argument is determined by the ``redirect_field_name``
          argument provided to the decorator. The default argument name is
          ``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
:setting:`settings.LOGIN_URL <LOGIN_URL>`. For example, using the defaults, add
the following line to your URLconf::

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

.. function:: views.login(request, [template_name, redirect_field_name, authentication_form])

    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
          :setting:`settings.LOGIN_REDIRECT_URL <LOGIN_REDIRECT_URL>` (which
          defaults to ``/accounts/profile/``). 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 four
    template context variables:

        * ``form``: A :class:`~django.forms.Form` object representing the login
          form. See the :ref:`forms documentation <topics-forms-index>` for
          more on ``Form`` objects.

        * ``next``: The URL to redirect to after successful login. This may
          contain a query string, too.

        * ``site``: The current :class:`~django.contrib.sites.models.Site`,
          according to the :setting:`SITE_ID` setting. If you don't have the
          site framework installed, this will be set to an instance of
          :class:`~django.contrib.sites.models.RequestSite`, which derives the
          site name and domain from the current
          :class:`~django.http.HttpRequest`.

        * ``site_name``: An alias for ``site.name``. If you don't have the site
          framework installed, this will be set to the value of
          :attr:`request.META['SERVER_NAME'] <django.http.HttpRequest.META>`.
          For more on sites, see :ref:`ref-contrib-sites`.

    If you'd prefer not to call the template :file:`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
    :file:`myapp/login.html` instead::

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

    You can also specify the name of the ``GET`` field which contains the URL
    to redirect to after login by passing ``redirect_field_name`` to the view.
    By default, the field is called ``next``.

    Here's a sample :file:`registration/login.html` template you can use as a
    starting point. It assumes you have a :file:`base.html` template that
    defines a ``content`` block:

    .. code-block:: html

        {% extends "base.html" %}

        {% block content %}

        {% if form.errors %}
        <p>Your username and password didn't match. Please try again.</p>
        {% endif %}

        <form method="post" action="{% url django.contrib.auth.views.login %}">{% csrf_token %}
        <table>
        <tr>
            <td>{{ form.username.label_tag }}</td>
            <td>{{ form.username }}</td>
        </tr>
        <tr>
            <td>{{ form.password.label_tag }}</td>
            <td>{{ form.password }}</td>
        </tr>
        </table>

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

        {% endblock %}

    .. versionadded:: 1.2

    If you are using alternate authentication (see
    :ref:`authentication-backends`) you can pass a custom authentication form
    to the login view via the ``authentication_form`` parameter. This form must
    accept a ``request`` keyword argument in its ``__init__`` method, and
    provide a ``get_user`` argument which returns the authenticated user object
    (this method is only ever called after successful form validation).

    .. _forms documentation: ../forms/
    .. _site framework docs: ../sites/

Other built-in views
--------------------

In addition to the :func:`~views.login` view, the authentication system
includes a few other useful built-in views located in
:mod:`django.contrib.auth.views`:

.. function:: views.logout(request, [next_page, template_name, redirect_field_name])

    Logs a user out.

    **Optional arguments:**

        * ``next_page``: The URL to redirect to after logout.

        * ``template_name``: The full name of a template to display after
          logging the user out. This will default to
          :file:`registration/logged_out.html` if no argument is supplied.

        * ``redirect_field_name``: The name of a ``GET`` field containing the
          URL to redirect to after log out. Overrides ``next_page`` if the given
          ``GET`` parameter is passed.

    **Template context:**

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

.. function:: views.logout_then_login(request[, login_url])

    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 :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.

.. function:: views.password_change(request[, template_name, post_change_redirect, password_change_form])

    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
          :file:`registration/password_change_form.html` if not supplied.

        * ``post_change_redirect``: The URL to redirect to after a successful
          password change.

        * .. versionadded:: 1.2

          ``password_change_form``: A custom "change password" form which must
          accept a ``user`` keyword argument. The form is responsible for
          actually changing the user's password.


    **Template context:**

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

.. function:: views.password_change_done(request[, template_name])

    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 :file:`registration/password_change_done.html` if not
          supplied.

.. function:: views.password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect])

    Allows a user to reset their password, and sends them the new password
    in an e-mail.

    **Optional arguments:**

        * ``template_name``: The full name of a template to use for
          displaying the password reset form. This will default to
          :file:`registration/password_reset_form.html` if not supplied.

        * ``email_template_name``: The full name of a template to use for
          generating the e-mail with the new password. This will default to
          :file:`registration/password_reset_email.html` if not supplied.

        * ``password_reset_form``: Form that will be used to set the password.
          Defaults to ``SetPasswordForm``.

        * ``token_generator``: Instance of the class to check the password. This
          will default to ``default_token_generator``, it's an instance of
          ``django.contrib.auth.tokens.PasswordResetTokenGenerator``.

        * ``post_reset_redirect``: The URL to redirect to after a successful
          password change.

    **Template context:**

        * ``form``: The form for resetting the user's password.

.. function:: views.password_reset_done(request[, template_name])

    The page shown after a user has reset their password.

    **Optional arguments:**

        * ``template_name``: The full name of a template to use. This will
          default to :file:`registration/password_reset_done.html` if not
          supplied.

.. function:: views.redirect_to_login(next[, login_url, redirect_field_name])
<commit_msg>Fixed #12895 - Fixed typo in auth docs. Thanks Timo.<commit_after>.. _topics-auth:

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

    .. 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 :ref:`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 list 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 list 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`,
        :attr:`~django.contrib.auth.models.User.email` and
        :attr:`~django.contrib.auth.models.User.password` are set as given, and the
        :class:`~django.contrib.auth.models.User` gets ``is_active=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', '<EMAIL>', '<PASSWORD>np<PASSWORD>')

    # 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>` 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('<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.has_perm()` always returns
      ``False``.
    * :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=<EMAIL>

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.ForeignKey` from your
model to the :class:`~django.contrib.auth.models.User` model, specified with
``unique=True`` to 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
==============================

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
:class:`request objects <django.http.HttpRequest>`.

First, install the
:class:`~django.contrib.sessions.middleware.SessionMiddleware` and
:class:`~django.contrib.auth.middleware.AuthenticationMiddleware`
middlewares by adding them to your :setting:`MIDDLEWARE_CLASSES` setting. See
the :ref:`session documentation <topics-http-sessions>` for more information.

Once you have those middlewares installed, you'll be able to access
:attr:`request.user <django.http.HttpRequest.user>` in views.
:attr:`request.user <django.http.HttpRequest.user>` will give you a
:class:`~django.contrib.auth.models.User` object representing the currently
logged-in user. If a user isn't currently logged in,
:attr:`request.user <django.http.HttpRequest.user>` will be set to an instance
of :class:`~django.contrib.auth.models.AnonymousUser` (see the previous
section). You can tell them apart with
:meth:`~django.contrib.auth.models.User.is_authenticated()`, like so::

    if request.user.is_authenticated():
        # Do something for authenticated users.
    else:
        # Do something for anonymous users.

.. _howtologauserin:

How to log a user in
--------------------

Django provides two functions in :mod:`django.contrib.auth`:
:func:`~django.contrib.auth.authenticate()` and
:func:`~django.contrib.auth.login()`.

.. function:: authenticate()

    To authenticate a given username and password, use
    :func:`~django.contrib.auth.authenticate()`. It takes two keyword
    arguments, ``username`` and ``password``, and it returns a
    :class:`~django.contrib.auth.models.User` object if the password is valid
    for the given username. If the password is invalid,
    :func:`~django.contrib.auth.authenticate()` returns ``None``. Example::

        from django.contrib.auth import authenticate
        user = authenticate(username='john', password='<PASSWORD>')
        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."

.. function:: login()

    To log a user in, in a view, use :func:`~django.contrib.auth.login()`. It
    takes an :class:`~django.http.HttpRequest` object and a
    :class:`~django.contrib.auth.models.User` object.
    :func:`~django.contrib.auth.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
    :func:`~django.contrib.auth.authenticate()` and
    :func:`~django.contrib.auth.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.

.. admonition:: Calling ``authenticate()`` first

    When you're manually logging a user in, you *must* call
    :func:`~django.contrib.auth.authenticate()` before you call
    :func:`~django.contrib.auth.login()`.
    :func:`~django.contrib.auth.authenticate()`
    sets an attribute on the :class:`~django.contrib.auth.models.User` noting
    which authentication backend successfully authenticated that user (see the
    `backends documentation`_ for details), and this information is needed
    later during the login process.

.. _backends documentation: #other-authentication-sources

Manually checking a user's password
-----------------------------------

.. function:: check_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 :func:`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
---------------------

.. function:: logout()

    To log out a user who has been logged in via
    :func:`django.contrib.auth.login()`, use
    :func:`django.contrib.auth.logout()` within your view. It takes an
    :class:`~django.http.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 :func:`~django.contrib.auth.logout()` doesn't throw any errors if
    the user wasn't logged in.

    .. versionchanged:: 1.0
       Calling ``logout()`` now cleans session data.

    When you call :func:`~django.contrib.auth.logout()`, the session data for
    the current request is completely cleaned out. All existing data is
    removed. This is to prevent another person from using the same web browser
    to log in and have access to the previous user's session data. If you want
    to put anything into the session that will be available to the user
    immediately after logging out, do that *after* calling
    :func:`django.contrib.auth.logout()`.

Limiting access to logged-in users
----------------------------------

The raw way
~~~~~~~~~~~

The simple, raw way to limit access to pages is to check
:meth:`request.user.is_authenticated()
<django.contrib.auth.models.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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. function:: decorators.login_required()

    As a shortcut, you can use the convenient
    :func:`~django.contrib.auth.decorators.login_required` decorator::

        from django.contrib.auth.decorators import login_required

        @login_required
        def my_view(request):
            ...

    :func:`~django.contrib.auth.decorators.login_required` also takes an
    optional ``redirect_field_name`` parameter. Example::


        from django.contrib.auth.decorators import login_required

        @login_required(redirect_field_name='redirect_to')
        def my_view(request):
            ...

    :func:`~django.contrib.auth.decorators.login_required` does the following:

        * If the user isn't logged in, redirect to
          :setting:`settings.LOGIN_URL <LOGIN_URL>` (``/accounts/login/`` by
          default), passing the current absolute URL in the query string. The
          name of the GET argument is determined by the ``redirect_field_name``
          argument provided to the decorator. The default argument name is
          ``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
:setting:`settings.LOGIN_URL <LOGIN_URL>`. For example, using the defaults, add
the following line to your URLconf::

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

.. function:: views.login(request, [template_name, redirect_field_name, authentication_form])

    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
          :setting:`settings.LOGIN_REDIRECT_URL <LOGIN_REDIRECT_URL>` (which
          defaults to ``/accounts/profile/``). 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 four
    template context variables:

        * ``form``: A :class:`~django.forms.Form` object representing the login
          form. See the :ref:`forms documentation <topics-forms-index>` for
          more on ``Form`` objects.

        * ``next``: The URL to redirect to after successful login. This may
          contain a query string, too.

        * ``site``: The current :class:`~django.contrib.sites.models.Site`,
          according to the :setting:`SITE_ID` setting. If you don't have the
          site framework installed, this will be set to an instance of
          :class:`~django.contrib.sites.models.RequestSite`, which derives the
          site name and domain from the current
          :class:`~django.http.HttpRequest`.

        * ``site_name``: An alias for ``site.name``. If you don't have the site
          framework installed, this will be set to the value of
          :attr:`request.META['SERVER_NAME'] <django.http.HttpRequest.META>`.
          For more on sites, see :ref:`ref-contrib-sites`.

    If you'd prefer not to call the template :file:`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
    :file:`myapp/login.html` instead::

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

    You can also specify the name of the ``GET`` field which contains the URL
    to redirect to after login by passing ``redirect_field_name`` to the view.
    By default, the field is called ``next``.

    Here's a sample :file:`registration/login.html` template you can use as a
    starting point. It assumes you have a :file:`base.html` template that
    defines a ``content`` block:

    .. code-block:: html

        {% extends "base.html" %}

        {% block content %}

        {% if form.errors %}
        <p>Your username and password didn't match. Please try again.</p>
        {% endif %}

        <form method="post" action="{% url django.contrib.auth.views.login %}">{% csrf_token %}
        <table>
        <tr>
            <td>{{ form.username.label_tag }}</td>
            <td>{{ form.username }}</td>
        </tr>
        <tr>
            <td>{{ form.password.label_tag }}</td>
            <td>{{ form.password }}</td>
        </tr>
        </table>

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

        {% endblock %}

    .. versionadded:: 1.2

    If you are using alternate authentication (see
    :ref:`authentication-backends`) you can pass a custom authentication form
    to the login view via the ``authentication_form`` parameter. This form must
    accept a ``request`` keyword argument in its ``__init__`` method, and
    provide a ``get_user`` argument which returns the authenticated user object
    (this method is only ever called after successful form validation).

    .. _forms documentation: ../forms/
    .. _site framework docs: ../sites/

Other built-in views
--------------------

In addition to the :func:`~views.login` view, the authentication system
includes a few other useful built-in views located in
:mod:`django.contrib.auth.views`:

.. function:: views.logout(request, [next_page, template_name, redirect_field_name])

    Logs a user out.

    **Optional arguments:**

        * ``next_page``: The URL to redirect to after logout.

        * ``template_name``: The full name of a template to display after
          logging the user out. This will default to
          :file:`registration/logged_out.html` if no argument is supplied.

        * ``redirect_field_name``: The name of a ``GET`` field containing the
          URL to redirect to after log out. Overrides ``next_page`` if the given
          ``GET`` parameter is passed.

    **Template context:**

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

.. function:: views.logout_then_login(request[, login_url])

    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 :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.

.. function:: views.password_change(request[, template_name, post_change_redirect, password_change_form])

    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
          :file:`registration/password_change_form.html` if not supplied.

        * ``post_change_redirect``: The URL to redirect to after a successful
          password change.

        * .. versionadded:: 1.2

          ``password_change_form``: A custom "change password" form which must
          accept a ``user`` keyword argument. The form is responsible for
          actually changing the user's password.


    **Template context:**

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

.. function:: views.password_change_done(request[, template_name])

    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 :file:`registration/password_change_done.html` if not
          supplied.

.. function:: views.password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect])

    Allows a user to reset their password, and sends them the new password
    in an e-mail.

    **Optional arguments:**

        * ``template_name``: The full name of a template to use for
          displaying the password reset form. This will default to
          :file:`registration/password_reset_form.html` if not supplied.

        * ``email_template_name``: The full name of a template to use for
          generating the e-mail with the new password. This will default to
          :file:`registration/password_reset_email.html` if not supplied.

        * ``password_reset_form``: Form that will be used to set the password.
          Defaults to :class:`~django.contrib.auth.forms.PasswordResetForm`.

        * ``token_generator``: Instance of the class to check the password. This
          will default to ``default_token_generator``, it's an instance of
          ``django.contrib.auth.tokens.PasswordResetTokenGenerator``.

        * ``post_reset_redirect``: The URL to redirect to after a successful
          password change.

    **Template context:**

        * ``form``: The form for resetting the user's password.

.. function:: views.password_reset_done(request[, template_name])

    The page shown after a user has reset their password.

    **Optional arguments:**

        * ``template_name``: The full name of a template to use. This will
          default to :file:`registration/password_reset_done.html` if not
          supplied.

.. function:: views.redirect_to_login(next[, login_url, redirect_field_name])

{'fraction_non_alphanumeric': 0.11091746545499813, 'fraction_numerical': 0.002697207353002199, 'mean_word_length': 3.1160261884429263, 'pattern_counts': {'":': 0, '<': 94, '<?xml version=': 0, '>': 142, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '193340', 'n_tokens_mistral': 20063, 'n_tokens_neox': 19009, 'n_words': 7508}