mirror of https://github.com/django/django.git
90 lines
3.1 KiB
Plaintext
90 lines
3.1 KiB
Plaintext
=============================
|
|
User authentication in Django
|
|
=============================
|
|
|
|
.. toctree::
|
|
:hidden:
|
|
|
|
default
|
|
passwords
|
|
customizing
|
|
|
|
.. 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 section of the
|
|
documentation explains how the default implementation works out of the box, as
|
|
well as how to :doc:`extend and customize </topics/auth/customizing>` it to
|
|
suit your project's needs.
|
|
|
|
Overview
|
|
========
|
|
|
|
The Django authentication system handles both authentication and authorization.
|
|
Briefly, authentication verifies a user is who they claim to be, and
|
|
authorization determines what an authenticated user is allowed to do. Here the
|
|
term authentication is used to refer to both tasks.
|
|
|
|
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.
|
|
* A configurable password hashing system
|
|
* Forms and view tools for logging in users, or restricting content
|
|
* A pluggable backend system
|
|
|
|
The authentication system in Django aims to be very generic and doesn't provide
|
|
some features commonly found in web authentication systems. Solutions for some
|
|
of these common problems have been implemented in third-party packages:
|
|
|
|
* Password strength checking
|
|
* Throttling of login attempts
|
|
* Authentication against third-parties (OAuth, for example)
|
|
* Object-level permissions
|
|
|
|
Installation
|
|
============
|
|
|
|
Authentication support is bundled as a Django contrib module in
|
|
``django.contrib.auth``. By default, the required configuration is already
|
|
included in the :file:`settings.py` generated by :djadmin:`django-admin
|
|
startproject <startproject>`, these consist of two items listed in your
|
|
:setting:`INSTALLED_APPS` setting:
|
|
|
|
1. ``'django.contrib.auth'`` contains the core of the authentication framework,
|
|
and its default models.
|
|
2. ``'django.contrib.contenttypes'`` is the Django :doc:`content type system
|
|
</ref/contrib/contenttypes>`, which allows permissions to be associated with
|
|
models you create.
|
|
|
|
and these items in your :setting:`MIDDLEWARE` setting:
|
|
|
|
#. :class:`~django.contrib.sessions.middleware.SessionMiddleware` manages
|
|
:doc:`sessions </topics/http/sessions>` across requests.
|
|
#. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` associates
|
|
users with requests using sessions.
|
|
|
|
With these settings in place, running the command ``manage.py migrate`` creates
|
|
the necessary database tables for auth related models and permissions for any
|
|
models defined in your installed apps.
|
|
|
|
Usage
|
|
=====
|
|
|
|
:doc:`Using Django's default implementation <default>`
|
|
|
|
* :ref:`Working with User objects <user-objects>`
|
|
* :ref:`Permissions and authorization <topic-authorization>`
|
|
* :ref:`Authentication in web requests <auth-web-requests>`
|
|
* :ref:`Managing users in the admin <auth-admin>`
|
|
|
|
:doc:`API reference for the default implementation </ref/contrib/auth>`
|
|
|
|
:doc:`Customizing Users and authentication <customizing>`
|
|
|
|
:doc:`Password management in Django <passwords>`
|