<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" lang=""> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>User authentication in Django — Django 1.8.19 documentation</title> <link rel="stylesheet" href="../../_static/default.css" type="text/css" /> <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '../../', VERSION: '1.8.19', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="../../_static/jquery.js"></script> <script type="text/javascript" src="../../_static/underscore.js"></script> <script type="text/javascript" src="../../_static/doctools.js"></script> <link rel="index" title="Index" href="../../genindex.html" /> <link rel="search" title="Search" href="../../search.html" /> <link rel="top" title="Django 1.8.19 documentation" href="../../contents.html" /> <link rel="up" title="Using Django" href="../index.html" /> <link rel="next" title="Using the Django authentication system" href="default.html" /> <link rel="prev" title="Advanced testing topics" href="../testing/advanced.html" /> <script type="text/javascript" src="../../templatebuiltins.js"></script> <script type="text/javascript"> (function($) { if (!django_template_builtins) { // templatebuiltins.js missing, do nothing. return; } $(document).ready(function() { // Hyperlink Django template tags and filters var base = "../../ref/templates/builtins.html"; if (base == "#") { // Special case for builtins.html itself base = ""; } // Tags are keywords, class '.k' $("div.highlight\\-html\\+django span.k").each(function(i, elem) { var tagname = $(elem).text(); if ($.inArray(tagname, django_template_builtins.ttags) != -1) { var fragment = tagname.replace(/_/, '-'); $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>"); } }); // Filters are functions, class '.nf' $("div.highlight\\-html\\+django span.nf").each(function(i, elem) { var filtername = $(elem).text(); if ($.inArray(filtername, django_template_builtins.tfilters) != -1) { var fragment = filtername.replace(/_/, '-'); $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>"); } }); }); })(jQuery); </script> </head> <body role="document"> <div class="document"> <div id="custom-doc" class="yui-t6"> <div id="hd"> <h1><a href="../../index.html">Django 1.8.19 documentation</a></h1> <div id="global-nav"> <a title="Home page" href="../../index.html">Home</a> | <a title="Table of contents" href="../../contents.html">Table of contents</a> | <a title="Global index" href="../../genindex.html">Index</a> | <a title="Module index" href="../../py-modindex.html">Modules</a> </div> <div class="nav"> « <a href="../testing/advanced.html" title="Advanced testing topics">previous</a> | <a href="../index.html" title="Using Django" accesskey="U">up</a> | <a href="default.html" title="Using the Django authentication system">next</a> »</div> </div> <div id="bd"> <div id="yui-main"> <div class="yui-b"> <div class="yui-g" id="topics-auth-index"> <div class="section" id="s-user-authentication-in-django"> <span id="user-authentication-in-django"></span><h1>User authentication in Django<a class="headerlink" href="#user-authentication-in-django" title="Permalink to this headline">¶</a></h1> <div class="toctree-wrapper compound"> </div> <span class="target" id="module-django.contrib.auth"></span><p>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 <a class="reference internal" href="customizing.html"><span class="doc">extend and customize</span></a> it to suit your project’s needs.</p> <div class="section" id="s-overview"> <span id="overview"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2> <p>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.</p> <p>The auth system consists of:</p> <ul class="simple"> <li>Users</li> <li>Permissions: Binary (yes/no) flags designating whether a user may perform a certain task.</li> <li>Groups: A generic way of applying labels and permissions to more than one user.</li> <li>A configurable password hashing system</li> <li>Forms and view tools for logging in users, or restricting content</li> <li>A pluggable backend system</li> </ul> <p>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:</p> <ul class="simple"> <li>Password strength checking</li> <li>Throttling of login attempts</li> <li>Authentication against third-parties (OAuth, for example)</li> </ul> </div> <div class="section" id="s-installation"> <span id="installation"></span><h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2> <p>Authentication support is bundled as a Django contrib module in <code class="docutils literal"><span class="pre">django.contrib.auth</span></code>. By default, the required configuration is already included in the <code class="file docutils literal"><span class="pre">settings.py</span></code> generated by <a class="reference internal" href="../../ref/django-admin.html#django-admin-startproject"><code class="xref std std-djadmin docutils literal"><span class="pre">django-admin</span> <span class="pre">startproject</span></code></a>, these consist of two items listed in your <a class="reference internal" href="../../ref/settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a> setting:</p> <ol class="arabic simple"> <li><code class="docutils literal"><span class="pre">'django.contrib.auth'</span></code> contains the core of the authentication framework, and its default models.</li> <li><code class="docutils literal"><span class="pre">'django.contrib.contenttypes'</span></code> is the Django <a class="reference internal" href="../../ref/contrib/contenttypes.html"><span class="doc">content type system</span></a>, which allows permissions to be associated with models you create.</li> </ol> <p>and these items in your <a class="reference internal" href="../../ref/settings.html#std:setting-MIDDLEWARE_CLASSES"><code class="xref std std-setting docutils literal"><span class="pre">MIDDLEWARE_CLASSES</span></code></a> setting:</p> <ol class="arabic simple"> <li><a class="reference internal" href="../../ref/middleware.html#django.contrib.sessions.middleware.SessionMiddleware" title="django.contrib.sessions.middleware.SessionMiddleware"><code class="xref py py-class docutils literal"><span class="pre">SessionMiddleware</span></code></a> manages <a class="reference internal" href="../http/sessions.html"><span class="doc">sessions</span></a> across requests.</li> <li><a class="reference internal" href="../../ref/middleware.html#django.contrib.auth.middleware.AuthenticationMiddleware" title="django.contrib.auth.middleware.AuthenticationMiddleware"><code class="xref py py-class docutils literal"><span class="pre">AuthenticationMiddleware</span></code></a> associates users with requests using sessions.</li> <li><a class="reference internal" href="../../ref/middleware.html#django.contrib.auth.middleware.SessionAuthenticationMiddleware" title="django.contrib.auth.middleware.SessionAuthenticationMiddleware"><code class="xref py py-class docutils literal"><span class="pre">SessionAuthenticationMiddleware</span></code></a> logs users out of their other sessions after a password change.</li> </ol> <p>With these settings in place, running the command <code class="docutils literal"><span class="pre">manage.py</span> <span class="pre">migrate</span></code> creates the necessary database tables for auth related models and permissions for any models defined in your installed apps.</p> </div> <div class="section" id="s-usage"> <span id="usage"></span><h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2> <p><a class="reference internal" href="default.html"><span class="doc">Using Django’s default implementation</span></a></p> <ul class="simple"> <li><a class="reference internal" href="default.html#user-objects"><span class="std std-ref">Working with User objects</span></a></li> <li><a class="reference internal" href="default.html#topic-authorization"><span class="std std-ref">Permissions and authorization</span></a></li> <li><a class="reference internal" href="default.html#auth-web-requests"><span class="std std-ref">Authentication in web requests</span></a></li> <li><a class="reference internal" href="default.html#auth-admin"><span class="std std-ref">Managing users in the admin</span></a></li> </ul> <p><a class="reference internal" href="../../ref/contrib/auth.html"><span class="doc">API reference for the default implementation</span></a></p> <p><a class="reference internal" href="customizing.html"><span class="doc">Customizing Users and authentication</span></a></p> <p><a class="reference internal" href="passwords.html"><span class="doc">Password management in Django</span></a></p> </div> </div> </div> </div> </div> <div class="yui-b" id="sidebar"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h3><a href="../../contents.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">User authentication in Django</a><ul> <li><a class="reference internal" href="#overview">Overview</a></li> <li><a class="reference internal" href="#installation">Installation</a></li> <li><a class="reference internal" href="#usage">Usage</a></li> </ul> </li> </ul> <h3>Browse</h3> <ul> <li>Prev: <a href="../testing/advanced.html">Advanced testing topics</a></li> <li>Next: <a href="default.html">Using the Django authentication system</a></li> </ul> <h3>You are here:</h3> <ul> <li> <a href="../../index.html">Django 1.8.19 documentation</a> <ul><li><a href="../index.html">Using Django</a> <ul><li>User authentication in Django</li></ul> </li></ul> </li> </ul> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../../_sources/topics/auth/index.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <form class="search" action="../../search.html" method="get"> <div><input type="text" name="q" /></div> <div><input type="submit" value="Go" /></div> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <h3>Last update:</h3> <p class="topless">Mar 10, 2018</p> </div> </div> <div id="ft"> <div class="nav"> « <a href="../testing/advanced.html" title="Advanced testing topics">previous</a> | <a href="../index.html" title="Using Django" accesskey="U">up</a> | <a href="default.html" title="Using the Django authentication system">next</a> »</div> </div> </div> <div class="clearer"></div> </div> </body> </html>