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>`
About Sign Up Leave Feedback Contact