<!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="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>User authentication in Django — Django 1.11.20 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" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></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>
<script type="text/javascript" src="../../_static/language_data.js"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.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>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../index.html">Django 1.11.20 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 notranslate"><span class="pre">django.contrib.auth</span></code>. By default, the required configuration is already
included in the <code class="file docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">INSTALLED_APPS</span></code></a> setting:</p>
<ol class="arabic simple">
<li><code class="docutils literal notranslate"><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 notranslate"><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"><code class="xref std std-setting docutils literal notranslate"><span class="pre">MIDDLEWARE</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 notranslate"><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 notranslate"><span class="pre">AuthenticationMiddleware</span></code></a> associates
users with requests using sessions.</li>
</ol>
<p>With these settings in place, running the command <code class="docutils literal notranslate"><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>
<h4>Previous topic</h4>
<p class="topless"><a href="../testing/advanced.html"
title="previous chapter">Advanced testing topics</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="default.html"
title="next chapter">Using the Django authentication system</a></p>
<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>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Feb 11, 2019</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>
