Debian Codegraph @

docs/topics/auth/index.txt

raw
1 =============================
2 User authentication in Django
3 =============================
4
5 .. toctree::
6 :hidden:
7
8 default
9 passwords
10 customizing
11
12 .. module:: django.contrib.auth
13 :synopsis: Django's authentication framework.
14
15 Django comes with a user authentication system. It handles user accounts,
16 groups, permissions and cookie-based user sessions. This section of the
17 documentation explains how the default implementation works out of the box, as
18 well as how to :doc:`extend and customize </topics/auth/customizing>` it to
19 suit your project's needs.
20
21 Overview
22 ========
23
24 The Django authentication system handles both authentication and authorization.
25 Briefly, authentication verifies a user is who they claim to be, and
26 authorization determines what an authenticated user is allowed to do. Here the
27 term authentication is used to refer to both tasks.
28
29 The auth system consists of:
30
31 * Users
32 * Permissions: Binary (yes/no) flags designating whether a user may perform
33 a certain task.
34 * Groups: A generic way of applying labels and permissions to more than one
35 user.
36 * A configurable password hashing system
37 * Forms and view tools for logging in users, or restricting content
38 * A pluggable backend system
39
40 The authentication system in Django aims to be very generic and doesn't provide
41 some features commonly found in web authentication systems. Solutions for some
42 of these common problems have been implemented in third-party packages:
43
44 * Password strength checking
45 * Throttling of login attempts
46 * Authentication against third-parties (OAuth, for example)
47 * Object-level permissions
48
49 Installation
50 ============
51
52 Authentication support is bundled as a Django contrib module in
53 ``django.contrib.auth``. By default, the required configuration is already
54 included in the :file:`settings.py` generated by :djadmin:`django-admin
55 startproject <startproject>`, these consist of two items listed in your
56 :setting:`INSTALLED_APPS` setting:
57
58 1. ``'django.contrib.auth'`` contains the core of the authentication framework,
59 and its default models.
60 2. ``'django.contrib.contenttypes'`` is the Django :doc:`content type system
61 </ref/contrib/contenttypes>`, which allows permissions to be associated with
62 models you create.
63
64 and these items in your :setting:`MIDDLEWARE` setting:
65
66 #. :class:`~django.contrib.sessions.middleware.SessionMiddleware` manages
67 :doc:`sessions </topics/http/sessions>` across requests.
68 #. :class:`~django.contrib.auth.middleware.AuthenticationMiddleware` associates
69 users with requests using sessions.
70
71 With these settings in place, running the command ``manage.py migrate`` creates
72 the necessary database tables for auth related models and permissions for any
73 models defined in your installed apps.
74
75 Usage
76 =====
77
78 :doc:`Using Django's default implementation <default>`
79
80 * :ref:`Working with User objects <user-objects>`
81 * :ref:`Permissions and authorization <topic-authorization>`
82 * :ref:`Authentication in web requests <auth-web-requests>`
83 * :ref:`Managing users in the admin <auth-admin>`
84
85 :doc:`API reference for the default implementation </ref/contrib/auth>`
86
87 :doc:`Customizing Users and authentication <customizing>`
88
89 :doc:`Password management in Django <passwords>`