mirror of
https://github.com/django/django.git
synced 2024-11-18 07:26:04 +00:00
9baf692a58
Thanks Tim Graham for polishing the patch, updating the tests, and writing documentation. Thanks Carl Meyer for shepherding the DEP.
89 lines
3.1 KiB
Plaintext
89 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)
|
|
|
|
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:
|
|
|
|
1. :class:`~django.contrib.sessions.middleware.SessionMiddleware` manages
|
|
:doc:`sessions </topics/http/sessions>` across requests.
|
|
2. :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>`
|