本文档解释Django的身份验证系统在其默认配置中的用法。 这种配置已经发展到满足最常见的项目需求，处理合理范围广泛的任务，并且有谨慎的密码和权限的实现。 对于认证需求与默认不同的项目，Django支持广泛的扩展和自定义认证。
Django认证同时提供认证和授权，通常被称为认证系统，因为这些功能有耦合。
User objects¶用户对象是认证系统的核心。 它们通常代表与您的站点交互的人员，用于启用限制访问，注册用户配置文件，将内容与创建者关联等内容.Django的身份验证框架中只存在一类用户，即'superusers'或管理员用户'staff'只是具有特殊属性集的用户对象，而不是不同类别的用户对象。
默认用户的主要属性是：
完整参考请参阅 full API documentation，以下文档是任务导向型的。
创建用户最直接的方法是使用包含的create_user()辅助函数：
>>> from django.contrib.auth.models import User
>>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword')
# 此时，user是User对象，已经保存到
# 到数据库。 你可以继续改变其属性
# 如果你想改变其他字段。
>>> user.last_name = 'Lennon'
>>> user.save()
如果你安装了Django admin，你也可以以交互方式创建用户。
使用createsuperuser命令创建超级用户：
$ python manage.py createsuperuser --username=joe --email=joe@example.com
系统会提示您输入密码。 一旦输入密码，就会创建用户。 如果您不填--username或--email选项，系统会在控制台提示您输入这些值。
Django不会在用户模型上存储原始（纯文本）密码，而只存储一个哈希值（有关详细信息，请参阅密码管理方式的文档）。 因此，请勿尝试直接操作用户的密码属性。 这就是创建用户时使用帮助函数的原因。
要更改用户的密码，您有几个选择：
manage.py changepassword *username* 提供了一种从命令行更改用户密码的方法。 它会提示您必须输入两次的给定用户的密码来进行更改。 如果两者都匹配，则新密码将立即更改。 如果您不提供用户，则该命令将尝试更改与当前系统用户匹配的用户的密码。
您还可以使用set_password()以编程方式更改密码：
>>> from django.contrib.auth.models import User
>>> u = User.objects.get(username='john')
>>> u.set_password('new password')
>>> u.save()
如果您安装了Django Admin，则还可以在身份验证系统的管理页面上更改用户的密码。
Django还提供了可用于允许用户更改自己的密码的views和forms。
更改用户的密码将注销其所有会话。 有关详细信息，请参阅密码更改注销会话。
authenticate(request=None, **credentials)[source]¶使用authenticate()验证一组凭据。 它将凭证作为关键字参数（username和password为其默认值）来针对每个认证后端进行检查，并在凭证在后台验证为合法时返回一个User对象。 如果凭证在所有后端验证为无效，或者后端抛出PermissionDenied异常，则返回None。 例如：
from django.contrib.auth import authenticate
user = authenticate(username='john', password='secret')
if user is not None:
# A backend authenticated the credentials
else:
# No backend authenticated the credentials
request是在认证后端的authenticate()方法中传递的可选的HttpRequest对象。
添加了可选的request参数。
Note
这是验证一组凭据的低级方法；例如，它由RemoteUserMiddleware使用。 除非您正在编写自己的身份验证系统，否则您可能不会使用它。 相反，如果您正在寻找登录用户的方法，请使用LoginView。
Django带有一个简单的权限系统。 它提供了一种为特定用户和用户组分配权限的方法。
它被Django管理站点使用，但欢迎您在自己的代码中使用它。
Django管理站点使用如下权限：
权限不仅可以针对每种类型的对象进行设置，还可以针对特定对象实例进行设置。 通过使用ModelAdmin类提供的has_add_permission()，has_change_permission()和has_delete_permission()方法，可以自定义相同类型的不同对象实例的权限。
User对象有两个多对多字段：groups和user_permissions。
User对象可以像访问任何其他Django模型一样访问其相关对象：
myuser.groups.set([group_list])
myuser.groups.add(group, group, ...)
myuser.groups.remove(group, group, ...)
myuser.groups.clear()
myuser.user_permissions.set([permission_list])
myuser.user_permissions.add(permission, permission, ...)
myuser.user_permissions.remove(permission, permission, ...)
myuser.user_permissions.clear()
如果INSTALLED_APPS中有django.contrib.auth，这将确保为每个定义的Django模型创建三个默认权限 - add，change和delete 。
这些权限将在您运行manage.py migrate时创建。在将django.contrib.auth添加到INSTALLED_APPS之后，第一次运行migrate时，将为所有先前安装的模型创建默认权限，以及当时正在安装的任何新model。 之后，每次运行manage.py migrate时，它都会为新模型创建默认权限（创建权限的函数连接到 post_migrate信号）。
假设你有一个app_label为foo模型名为Bar的应用程序，想测试基本权限，你应该使用：
user.has_perm('foo.add_bar')user.has_perm('foo.change_bar')user.has_perm('foo.delete_bar')很少直接访问Permission模型。
django.contrib.auth.models.Group模型是对用户进行分类的通用方法，因此您可以将权限或其他标签应用于这些用户。 用户可以属于任意数量的组。
组中的用户自动拥有该组被授予的权限。 例如，如果组Site editors具有权限can_edit_home_page，则该组中的任何用户都将具有该权限。
除权限外，组是一种方便的对用户进行分类的方法，可以以此为用户提供一些标签或扩展功能。 例如，您可以创建一个组'Special users'，您可以授权他们访问你的网站中仅限会员的部分，或向其发送仅限会员的电子邮件。
虽然可以在模型的Meta类中定义自定义权限，但您也可以直接创建权限。 例如，您可以在myapp中为BlogPost模型创建can_publish权限：
from myapp.models import BlogPost
from django.contrib.auth.models import Permission
from django.contrib.contenttypes.models import ContentType
content_type = ContentType.objects.get_for_model(BlogPost)
permission = Permission.objects.create(
codename='can_publish',
name='Can Publish Posts',
content_type=content_type,
)
然后可以通过其user_permissions属性将权限分配给某个User，或通过其permissions属性将权限分配给Group。
ModelBackend在第一次需要获取用户对象以进行权限检查后，缓存对用户对象的权限。 这通常适用于请求 - 响应周期，因为通常不会在添加权限后立即检查权限（例如，在管理员中）。 如果要添加权限并在之后立即检查它们，例如，在测试或视图中，最简单的解决方案是从数据库中重新获取用户。 例如：
from django.contrib.auth.models import Permission, User
from django.contrib.contenttypes.models import ContentType
from django.shortcuts import get_object_or_404
from myapp.models import BlogPost
def user_gains_perms(request, user_id):
user = get_object_or_404(User, pk=user_id)
# any permission check will cache the current set of permissions
user.has_perm('myapp.change_blogpost')
content_type = ContentType.objects.get_for_model(BlogPost)
permission = Permission.objects.get(
codename='change_blogpost',
content_type=content_type,
)
user.user_permissions.add(permission)
# Checking the cached permission set
user.has_perm('myapp.change_blogpost') # False
# Request new instance of User
# Be aware that user.refresh_from_db() won't clear the cache.
user = get_object_or_404(User, pk=user_id)
# Permission cache is repopulated from the database
user.has_perm('myapp.change_blogpost') # True
...
Django使用会话和中间件将身份验证系统挂载到request 对象。
它们在代表当前用户的每个请求上提供request.user属性。 如果当前用户尚未登录，则此属性将设置为AnonymousUser的实例，否则它将是User的实例。
您可以通过is_authenticated区分它们，如下所示：
if request.user.is_authenticated:
# Do something for authenticated users.
...
else:
# Do something for anonymous users.
...
如果你有一个认证用户你想附加到当前会话 - 这是通过login()函数完成的。
login(request, user, backend=None)[source]¶要从视图中登录用户，请使用login()。 它需要一个HttpRequest对象和一个User对象。
login()使用Django的会话框架将用户的ID保存在会话中。
请注意，匿名会话期间的任何数据集在用户登录后都会保留在会话中。
这个例子展示了如何使用authenticate()和login()：
from django.contrib.auth import authenticate, login
def my_view(request):
username = request.POST['username']
password = request.POST['password']
user = authenticate(request, username=username, password=password)
if user is not None:
login(request, user)
# 重定向至一个成功页面。
...
else:
# 返回一个'无效登录'的错误信息。
...
当用户登录时，用户的ID和用于身份验证的后端将保存在用户的会话中。 这允许相同的身份验证后端在将来的请求中获取用户的详细信息。 要在会话中保存的身份验证后端选择如下：
backend参数的值。user.backend属性的值（如果存在）。 这允许配对authenticate()和login()：authenticate()会为它返回的用户对象设置user.backend属性。AUTHENTICATION_BACKENDS中的backend。在情况1和2中，backend参数或user.backend属性的值应该是点式导入路径字符串（类似于AUTHENTICATION_BACKENDS ），而不是实际的后端类。
logout(request)[source]¶要注销通过django.contrib.auth.login()登录的用户，请在视图中使用django.contrib.auth.logout()。 它需要一个HttpRequest对象并且没有返回值。
例：
from django.contrib.auth import logout
def logout_view(request):
logout(request)
# Redirect to a success page.
请注意，如果用户未登录，logout()不会引发任何错误。
当您调用logout()时，将完全清除当前请求的会话数据。 所有数据都会被删除。 这是为了防止其他人使用相同的Web浏览器登录并访问以前用户的会话数据。 如果要在注销后立即将任何内容放入用户可用的会话中，请在调用django.contrib.auth.logout()之后执行。
限制对页面访问的简单原始方法是检查request.user.is_authenticated并重定向到登录页面：
from django.conf import settings
from django.shortcuts import redirect
def my_view(request):
if not request.user.is_authenticated:
return redirect('%s?next=%s' % (settings.LOGIN_URL, request.path))
# ...
...或显示错误消息：
from django.shortcuts import render
def my_view(request):
if not request.user.is_authenticated:
return render(request, 'myapp/login_error.html')
# ...
login_required decorator¶login_required(redirect_field_name='next', login_url=None)[source]¶作为一种快捷方式，您可以使用方便的login_required()装饰器：
from django.contrib.auth.decorators import login_required
@login_required
def my_view(request):
...
login_required() does the following:
settings.LOGIN_URL，并在查询字符串中传递当前绝对路径。 Example: /accounts/login/?next=/polls/3/.默认情况下，成功验证时用户应重定向到的路径存储在名为“next”的查询字符串参数中。 如果您希望为此参数使用其他名称，login_required()将采用可选的redirect_field_name参数：
from django.contrib.auth.decorators import login_required
@login_required(redirect_field_name='my_redirect_field')
def my_view(request):
...
请注意，如果您为redirect_field_name提供值，则您很可能也需要自定义登录模板，因为存储重定向路径的模板上下文变量将使用redirect_field_name的值作为其键而不是“next”（默认值）。
login_required()还采用可选的login_url参数。 Example:
from django.contrib.auth.decorators import login_required
@login_required(login_url='/accounts/login/')
def my_view(request):
...
请注意，如果未指定login_url参数，则需要确保settings.LOGIN_URL和登录视图正确关联。 例如，使用默认值，将以下行添加到URLconf：
from django.contrib.auth import views as auth_views
path('accounts/login/', auth_views.LoginView.as_view()),
settings.LOGIN_URL还接受视图函数名称和命名的URL模式。 这使您可以在URLconf中自由重新映射登录视图，而无需更新设置。
Note
login_required装饰器不检查用户的is_active标志，但默认的AUTHENTICATION_BACKENDS会拒绝非激活用户。
See also
如果您正在为Django的管理员编写自定义视图（或者需要内置视图使用的相同授权检查），您会发现django.contrib.admin.views.decorators.staff_member_required()装饰器可替代login_required()方法。
LoginRequired mixin¶使用基于类的视图时，可以使用LoginRequiredMixin实现与login_required相同的行为。 这个mixin应该位于继承列表中最左边的位置。
LoginRequiredMixin¶如果视图正在使用此mixin，则未经过身份验证的用户的所有请求都将重定向到登录页面或显示HTTP 403 Forbidden错误，具体取决于raise_exception参数。
您可以设置AccessMixin的任何参数来自定义未授权用户的处理：
from django.contrib.auth.mixins import LoginRequiredMixin
class MyView(LoginRequiredMixin, View):
login_url = '/login/'
redirect_field_name = 'redirect_to'
Note
就像login_required装饰器一样，这个mixin不检查用户的is_active标志，但默认AUTHENTICATION_BACKENDS拒绝非活动用户。
要根据某些权限或某些其他测试来限制访问，您基本上可以执行与上一节中所述相同的操作。
简单的方法是直接在视图中的request.user上运行测试。 例如，此视图会检查以确保用户在所需的域中有电子邮件，如果没有，则重定向到登录页面：
from django.shortcuts import redirect
def my_view(request):
if not request.user.email.endswith('@example.com'):
return redirect('/login/?next=%s' % request.path)
# ...
user_passes_test(test_func, login_url=None, redirect_field_name='next')[source]¶作为一种快捷方式，您可以使用方便的user_passes_test装饰器，当回调返回False时执行重定向：
from django.contrib.auth.decorators import user_passes_test
def email_check(user):
return user.email.endswith('@example.com')
@user_passes_test(email_check)
def my_view(request):
...
user_passes_test()接受一个必需的参数：一个带有User对象的callable，如果允许用户查看该页面，则返回True。 Note that
user_passes_test() does not
automatically check that the User is
not anonymous.
user_passes_test()有两个可选参数：
login_urlsettings.LOGIN_URL。redirect_field_namelogin_required().
将其设置为None将其从URL中删除，如果您将未通过测试的用户重定向到没有“下一页”的非登录页面，则可能需要执行此操作。For example:
@user_passes_test(email_check, login_url='/login/')
def my_view(request):
...
UserPassesTestMixin¶使用基于类的视图时，可以使用UserPassesTestMixin来执行此操作。
test_func()¶您必须覆盖类的test_func()方法以提供要执行的测试。 此外，您可以设置AccessMixin的任何参数来自定义未授权用户的处理：
from django.contrib.auth.mixins import UserPassesTestMixin
class MyView(UserPassesTestMixin, View):
def test_func(self):
return self.request.user.email.endswith('@example.com')
get_test_func()¶您还可以覆盖get_test_func()方法，让mixin使用不同名称的函数进行检查（而不是test_func()）。
Stacking UserPassesTestMixin
由于UserPassesTestMixin的实现方式，您无法将它们堆叠在继承列表中。 以下不起作用：
class TestMixin1(UserPassesTestMixin):
def test_func(self):
return self.request.user.email.endswith('@example.com')
class TestMixin2(UserPassesTestMixin):
def test_func(self):
return self.request.user.username.startswith('django')
class MyView(TestMixin1, TestMixin2, View):
...
如果TestMixin1将调用super()并将该结果考虑在内，TestMixin1将不再独立运行。
permission_required decorator¶permission_required(perm, login_url=None, raise_exception=False)[source]¶检查用户是否具有特定权限是一项相对常见的任务。 出于这个原因，Django为这种情况提供了一个快捷方式：permission_required()装饰器。:
from django.contrib.auth.decorators import permission_required
@permission_required('polls.can_vote')
def my_view(request):
...
就像has_perm()方法一样，权限名称采用"<app label>.<permission codename>"的形式(例如polls.can_vote 为polls应用的一个模型的权限)
The decorator may also take an iterable of permissions, in which case the user must have all of the permissions in order to access the view.
Note that permission_required()
also takes an optional login_url parameter:
from django.contrib.auth.decorators import permission_required
@permission_required('polls.can_vote', login_url='/loginpage/')
def my_view(request):
...
As in the login_required() decorator,
login_url defaults to settings.LOGIN_URL.
If the raise_exception parameter is given, the decorator will raise
PermissionDenied, prompting the 403
(HTTP Forbidden) view instead of redirecting to the
login page.
If you want to use raise_exception but also give your users a chance to
login first, you can add the
login_required() decorator:
from django.contrib.auth.decorators import login_required, permission_required
@login_required
@permission_required('polls.can_vote', raise_exception=True)
def my_view(request):
...
PermissionRequiredMixin mixin¶要将权限检查应用于基于类的视图，可以使用PermissionRequiredMixin：
PermissionRequiredMixin¶这个mixin就像permission_required装饰器一样，检查访问视图的用户是否具有所有给定的权限。 您应该使用permission_required参数指定权限（或权限的可迭代）：
from django.contrib.auth.mixins import PermissionRequiredMixin
class MyView(PermissionRequiredMixin, View):
permission_required = 'polls.can_vote'
# Or multiple of permissions:
permission_required = ('polls.can_open', 'polls.can_edit')
您可以设置AccessMixin的任何参数来自定义未授权用户的处理。
您也可以覆盖这些方法：
get_permission_required()¶返回mixin使用的可迭代权限名称。 默认为permission_required属性，必要时转换为元组。
has_permission()¶返回一个布尔值，表示当前用户是否有权执行装饰视图。 默认情况下，这将返回使用get_permission_required()返回的权限列表调用has_perms()的结果。
为了简化基于类的视图中访问限制的处理，可以使用AccessMixin将用户重定向到登录页面或发出HTTP 403 Forbidden响应。
AccessMixin¶login_url¶Default return value for get_login_url(). Defaults to None
in which case get_login_url() falls back to
settings.LOGIN_URL.
permission_denied_message¶Default return value for get_permission_denied_message().
Defaults to an empty string.
redirect_field_name¶Default return value for get_redirect_field_name(). Defaults to
"next".
raise_exception¶If this attribute is set to True, a
PermissionDenied exception will be
raised instead of the redirect. Defaults to False.
get_login_url()¶Returns the URL that users who don’t pass the test will be redirected
to. Returns login_url if set, or settings.LOGIN_URL otherwise.
get_permission_denied_message()¶When raise_exception is True, this method can be used to
control the error message passed to the error handler for display to
the user. Returns the permission_denied_message attribute by
default.
get_redirect_field_name()¶Returns the name of the query parameter that will contain the URL the
user should be redirected to after a successful login. If you set this
to None, a query parameter won’t be added. Returns the
redirect_field_name attribute by default.
handle_no_permission()¶Depending on the value of raise_exception, the method either raises
a PermissionDenied exception or
redirects the user to the login_url, optionally including the
redirect_field_name if it is set.
如果AUTH_USER_MODEL继承自AbstractBaseUser或实现其自己的get_session_auth_hash()方法，则经过身份验证的会话将包含此函数返回的哈希。
在AbstractBaseUser的情况下，这是密码字段的HMAC。 Django验证每个请求的会话中的散列是否与请求期间计算的散列相匹配。 这允许用户通过更改其密码来注销所有会话。
Django，PasswordChangeView中包含的默认密码更改视图和django.contrib.auth admin中的user_change_password视图，使用新的更新会话密码哈希，以便用户更改自己的密码不会自行登出。 如果您有自定义密码更改视图并希望具有类似行为，请使用update_session_auth_hash()功能。
update_session_auth_hash(request, user)[source]¶This function takes the current request and the updated user object from which the new session hash will be derived and updates the session hash appropriately. It also rotates the session key so that a stolen session cookie will be invalidated.
Example usage:
from django.contrib.auth import update_session_auth_hash
def password_change(request):
if request.method == 'POST':
form = PasswordChangeForm(user=request.user, data=request.POST)
if form.is_valid():
form.save()
update_session_auth_hash(request, form.user)
else:
...
Rotating of the session key was added.
Note
Since
get_session_auth_hash()
is based on SECRET_KEY, updating your site to use a new secret
will invalidate all existing sessions.
Django提供了几个可用于处理登录，注销和密码管理的视图。 这些使用股票认证表格，但您也可以传递自己的表格。
Django没有为身份验证视图提供默认模板。 您应该为要使用的视图创建自己的模板。 每个视图中都记录了模板上下文，请参阅所有身份验证视图。
在项目中实现这些视图有不同的方法。 最简单的方法是在您自己的URLconf中的django.contrib.auth.urls中包含提供的URLconf，例如：
urlpatterns = [
path('accounts/', include('django.contrib.auth.urls')),
]
这将包括以下URL模式：
accounts/login/ [name='login']
accounts/logout/ [name='logout']
accounts/password_change/ [name='password_change']
accounts/password_change/done/ [name='password_change_done']
accounts/password_reset/ [name='password_reset']
accounts/password_reset/done/ [name='password_reset_done']
accounts/reset/<uidb64>/<token>/ [name='password_reset_confirm']
accounts/reset/done/ [name='password_reset_complete']
视图提供URL名称以便于参考。 有关使用命名URL模式的详细信息，请参阅URL文档。
如果您想要更好地控制URL，可以在URLconf中引用特定视图：
from django.contrib.auth import views as auth_views
urlpatterns = [
path('change-password/', auth_views.PasswordChangeView.as_view()),
]
视图具有可用于更改视图行为的可选参数。 例如，如果要更改视图使用的模板名称，可以提供template_name参数。 一种方法是在URLconf中提供关键字参数，这些参数将传递给视图。 例如：
urlpatterns = [
path(
'change-password/',
auth_views.PasswordChangeView.as_view(template_name='change-password.html'),
),
]
所有视图都是基于类的，它允许您通过子类化轻松地自定义它们。
这是一个包含django.contrib.auth提供的所有视图的列表。 有关实现的详细信息，请参阅使用视图。
login(request, template_name=`registration/login.html`, redirect_field_name='next', authentication_form=AuthenticationForm, extra_context=None, redirect_authenticated_user=False)¶Deprecated since version 1.11: login基于函数的视图应该替换为基于类的LoginView。
The optional arguments of this view are similar to the class-based
LoginView attributes.
LoginView¶URL name: login
有关使用命名URL模式的详细信息，请参阅URL文档。
Attributes:
template_name：要为用户登录的视图显示的模板名称。 Defaults to registration/login.html.
redirect_field_name：GET字段的名称，包含登录后重定向到的URL。 Defaults to next.
authentication_form：用于身份验证的可调用（通常只是表单类）。 Defaults to
AuthenticationForm.
extra_context: A dictionary of context data that will be added to the
default context data passed to the template.
redirect_authenticated_user: A boolean that controls whether or not
authenticated users accessing the login page will be redirected as if
they had just successfully logged in. Defaults to False.
Warning
If you enable redirect_authenticated_user, other websites will be
able to determine if their visitors are authenticated on your site by
requesting redirect URLs to image files on your website. To avoid
this “social media fingerprinting” information
leakage, host all images and your favicon on a separate domain.
success_url_allowed_hosts: A set of hosts, in addition to
request.get_host(), that are
safe for redirecting after login. Defaults to an empty set.
这是LoginView的作用：
GET调用，它将显示一个POST到同一URL的登录表单。 更多关于这一点。POST使用用户提交的凭据进行调用，则会尝试将用户登录。 如果登录成功，视图将重定向到next中指定的URL。 如果未提供next，则会重定向到settings.LOGIN_REDIRECT_URL（默认为/ accounts / profile /）。 如果登录失败，则会重新显示登录表单。您有责任为登录模板提供html，默认情况下名为registration / login.html。 这个模版接受以下四个模版上下文变量：
form: 一个AuthenticationForm类的Form对象.next：成功登录后的跳转URL。 这可能包含一个query string。site: The current Site,
according to the SITE_ID setting. If you don’t have the
site framework installed, this will be set to an instance of
RequestSite, which derives the
site name and domain from the current
HttpRequest.site_name: An alias for site.name. If you don’t have the site
framework installed, this will be set to the value of
request.META['SERVER_NAME'].
For more on sites, see The “sites” framework.If you’d prefer not to call the template registration/login.html,
you can pass the template_name parameter via the extra arguments to
the as_view method in your URLconf. For example, this URLconf line would
use myapp/login.html instead:
path('accounts/login/', auth_views.LoginView.as_view(template_name='myapp/login.html')),
You can also specify the name of the GET field which contains the URL
to redirect to after login using redirect_field_name. By default, the
field is called next.
Here’s a sample registration/login.html template you can use as a
starting point. It assumes you have a base.html template that
defines a content block:
{% extends "base.html" %}
{% block content %}
{% if form.errors %}
<p>Your username and password didn't match. Please try again.</p>
{% endif %}
{% if next %}
{% if user.is_authenticated %}
<p>Your account doesn't have access to this page. To proceed,
please login with an account that has access.</p>
{% else %}
<p>Please login to see this page.</p>
{% endif %}
{% endif %}
<form method="post" action="{% url 'login' %}">
{% csrf_token %}
<table>
<tr>
<td>{{ form.username.label_tag }}</td>
<td>{{ form.username }}</td>
</tr>
<tr>
<td>{{ form.password.label_tag }}</td>
<td>{{ form.password }}</td>
</tr>
</table>
<input type="submit" value="login" />
<input type="hidden" name="next" value="{{ next }}" />
</form>
{# Assumes you setup the password_reset view in your URLconf #}
<p><a href="{% url 'password_reset' %}">Lost password?</a></p>
{% endblock %}
If you have customized authentication (see Customizing Authentication) you can use a custom authentication form by
setting the authentication_form attribute. This form must accept a
request keyword argument in its __init__() method and provide a
get_user() method which returns the authenticated user object (this
method is only ever called after successful form validation).
logout(request, next_page=None, template_name='registration/logged_out.html', redirect_field_name='next', extra_context=None)¶Deprecated since version 1.11: The logout function-based view should be replaced by the
class-based LogoutView.
The optional arguments of this view are similar to the class-based
LogoutView attributes.
LogoutView¶Logs a user out.
URL name: logout
Attributes:
next_page: The URL to redirect to after logout. Defaults to
settings.LOGOUT_REDIRECT_URL.template_name: The full name of a template to display after
logging the user out. Defaults to registration/logged_out.html.redirect_field_name: The name of a GET field containing the
URL to redirect to after log out. Defaults to next. Overrides the
next_page URL if the given GET parameter is passed.extra_context: A dictionary of context data that will be added to the
default context data passed to the template.success_url_allowed_hosts: A set of hosts, in addition to
request.get_host(), that are
safe for redirecting after logout. Defaults to an empty set.Template context:
title: The string “Logged out”, localized.site: The current Site,
according to the SITE_ID setting. If you don’t have the
site framework installed, this will be set to an instance of
RequestSite, which derives the
site name and domain from the current
HttpRequest.site_name: An alias for site.name. If you don’t have the site
framework installed, this will be set to the value of
request.META['SERVER_NAME'].
For more on sites, see The “sites” framework.logout_then_login(request, login_url=None, extra_context=None)¶Logs a user out, then redirects to the login page.
URL name: No default URL provided
Optional arguments:
login_url: The URL of the login page to redirect to.
Defaults to settings.LOGIN_URL if not supplied.extra_context: A dictionary of context data that will be added to the
default context data passed to the template.Deprecated since version 1.11: The unused extra_context parameter is deprecated and will be
removed in Django 2.1.
password_change(request, template_name='registration/password_change_form.html', post_change_redirect=None, password_change_form=PasswordChangeForm, extra_context=None)¶Deprecated since version 1.11: The password_change function-based view should be replaced by the
class-based PasswordChangeView.
The optional arguments of this view are similar to the class-based
PasswordChangeView attributes, except the post_change_redirect and
password_change_form arguments which map to the success_url and
form_class attributes of the class-based view.
PasswordChangeView¶URL name: password_change
Allows a user to change their password.
Attributes:
template_name: The full name of a template to use for
displaying the password change form. Defaults to
registration/password_change_form.html if not supplied.success_url: The URL to redirect to after a successful password
change.form_class: A custom “change password” form which must accept a
user keyword argument. The form is responsible for actually changing
the user’s password. Defaults to
PasswordChangeForm.extra_context: A dictionary of context data that will be added to the
default context data passed to the template.Template context:
form: The password change form (see form_class above).password_change_done(request, template_name='registration/password_change_done.html', extra_context=None)¶Deprecated since version 1.11: The password_change_done function-based view should be replaced by
the class-based PasswordChangeDoneView.
The optional arguments of this view are similar to the class-based
PasswordChangeDoneView attributes.
PasswordChangeDoneView¶URL name: password_change_done
The page shown after a user has changed their password.
Attributes:
template_name: The full name of a template to use.
Defaults to registration/password_change_done.html if not
supplied.extra_context: A dictionary of context data that will be added to the
default context data passed to the template.password_reset(request, template_name='registration/password_reset_form.html', email_template_name='registration/password_reset_email.html', subject_template_name='registration/password_reset_subject.txt', password_reset_form=PasswordResetForm, token_generator=default_token_generator, post_reset_redirect=None, from_email=None, extra_context=None, html_email_template_name=None, extra_email_context=None)¶Deprecated since version 1.11: The password_reset function-based view should be replaced by the
class-based PasswordResetView.
The optional arguments of this view are similar to the class-based
PasswordResetView attributes, except the post_reset_redirect and
password_reset_form arguments which map to the success_url and
form_class attributes of the class-based view.
PasswordResetView¶URL name: password_reset
Allows a user to reset their password by generating a one-time use link that can be used to reset the password, and sending that link to the user’s registered email address.
If the email address provided does not exist in the system, this view
won’t send an email, but the user won’t receive any error message either.
This prevents information leaking to potential attackers. If you want to
provide an error message in this case, you can subclass
PasswordResetForm and use the
form_class attribute.
Users flagged with an unusable password (see
set_unusable_password() aren’t
allowed to request a password reset to prevent misuse when using an
external authentication source like LDAP. Note that they won’t receive any
error message since this would expose their account’s existence but no
mail will be sent either.
Attributes:
template_name: The full name of a template to use for
displaying the password reset form. Defaults to
registration/password_reset_form.html if not supplied.form_class: Form that will be used to get the email of
the user to reset the password for. Defaults to
PasswordResetForm.email_template_name: The full name of a template to use for
generating the email with the reset password link. Defaults to
registration/password_reset_email.html if not supplied.subject_template_name: The full name of a template to use for
the subject of the email with the reset password link. Defaults
to registration/password_reset_subject.txt if not supplied.token_generator: Instance of the class to check the one time link.
This will default to default_token_generator, it’s an instance of
django.contrib.auth.tokens.PasswordResetTokenGenerator.success_url: The URL to redirect to after a successful password reset
request.from_email: A valid email address. By default Django uses
the DEFAULT_FROM_EMAIL.extra_context: A dictionary of context data that will be added to the
default context data passed to the template.html_email_template_name: The full name of a template to use
for generating a text/html multipart email with the password reset
link. By default, HTML email is not sent.extra_email_context: A dictionary of context data that will be
available in the email template.Template context:
form: The form (see form_class above) for resetting the user’s
password.Email template context:
email: An alias for user.emailuser: The current User,
according to the email form field. Only active users are able to
reset their passwords (User.is_active is True).site_name: An alias for site.name. If you don’t have the site
framework installed, this will be set to the value of
request.META['SERVER_NAME'].
For more on sites, see The “sites” framework.domain: An alias for site.domain. If you don’t have the site
framework installed, this will be set to the value of
request.get_host().protocol: http or httpsuid: The user’s primary key encoded in base 64.token: Token to check that the reset link is valid.Sample registration/password_reset_email.html (email body template):
Someone asked for password reset for email {{ email }}. Follow the link below:
{{ protocol}}://{{ domain }}{% url 'password_reset_confirm' uidb64=uid token=token %}
The same template context is used for subject template. Subject must be single line plain text string.
password_reset_done(request, template_name='registration/password_reset_done.html', extra_context=None)¶Deprecated since version 1.11: The password_reset_done function-based view should be replaced by
the class-based PasswordResetDoneView.
The optional arguments of this view are similar to the class-based
PasswordResetDoneView attributes.
PasswordResetDoneView¶URL name: password_reset_done
The page shown after a user has been emailed a link to reset their
password. This view is called by default if the PasswordResetView
doesn’t have an explicit success_url URL set.
Note
If the email address provided does not exist in the system, the user is inactive, or has an unusable password, the user will still be redirected to this view but no email will be sent.
Attributes:
template_name: The full name of a template to use.
Defaults to registration/password_reset_done.html if not
supplied.extra_context: A dictionary of context data that will be added to the
default context data passed to the template.password_reset_confirm(request, uidb64=None, token=None, template_name='registration/password_reset_confirm.html', token_generator=default_token_generator, set_password_form=SetPasswordForm, post_reset_redirect=None, extra_context=None)¶Deprecated since version 1.11: The password_reset_confirm function-based view should be replaced by
the class-based PasswordResetConfirmView.
The optional arguments of this view are similar to the class-based
PasswordResetConfirmView attributes, except the post_reset_redirect
and set_password_form arguments which map to the success_url and
form_class attributes of the class-based view.
PasswordResetConfirmView¶URL name: password_reset_confirm
Presents a form for entering a new password.
Keyword arguments from the URL:
uidb64: The user’s id encoded in base 64.token: Token to check that the password is valid.Attributes:
template_name: The full name of a template to display the confirm
password view. Default value is
registration/password_reset_confirm.html.token_generator: Instance of the class to check the password. This
will default to default_token_generator, it’s an instance of
django.contrib.auth.tokens.PasswordResetTokenGenerator.post_reset_login: A boolean indicating if the user should be
automatically authenticated after a successful password reset. Defaults
to False.post_reset_login_backend: A dotted path to the authentication
backend to use when authenticating a user if post_reset_login is
True. Required only if you have multiple
AUTHENTICATION_BACKENDS configured. Defaults to None.form_class: Form that will be used to set the password. Defaults to
SetPasswordForm.success_url: URL to redirect after the password reset done. Defaults
to 'password_reset_complete'.extra_context: A dictionary of context data that will be added to the
default context data passed to the template.Template context:
form: The form (see set_password_form above) for setting the
new user’s password.validlink: Boolean, True if the link (combination of uidb64 and
token) is valid or unused yet.password_reset_complete(request, template_name='registration/password_reset_complete.html', extra_context=None)¶Deprecated since version 1.11: The password_reset_complete function-based view should be replaced
by the class-based PasswordResetCompleteView.
The optional arguments of this view are similar to the class-based
PasswordResetCompleteView attributes.
PasswordResetCompleteView¶URL name: password_reset_complete
Presents a view which informs the user that the password has been successfully changed.
Attributes:
template_name: The full name of a template to display the view.
Defaults to registration/password_reset_complete.html.extra_context: A dictionary of context data that will be added to the
default context data passed to the template.redirect_to_login(next, login_url=None, redirect_field_name='next')¶Redirects to the login page, and then back to another URL after a successful login.
Required arguments:
next: The URL to redirect to after a successful login.Optional arguments:
login_url: The URL of the login page to redirect to.
Defaults to settings.LOGIN_URL if not supplied.redirect_field_name: The name of a GET field containing the
URL to redirect to after log out. Overrides next if the given
GET parameter is passed.If you don’t want to use the built-in views, but want the convenience of not
having to write forms for this functionality, the authentication system
provides several built-in forms located in django.contrib.auth.forms:
Note
The built-in authentication forms make certain assumptions about the user model that they are working with. If you’re using a custom user model, it may be necessary to define your own forms for the authentication system. For more information, refer to the documentation about using the built-in authentication forms with custom user models.
AdminPasswordChangeForm¶A form used in the admin interface to change a user’s password.
Takes the user as the first positional argument.
AuthenticationForm¶A form for logging a user in.
Takes request as its first positional argument, which is stored on the
form instance for use by sub-classes.
confirm_login_allowed(user)¶By default, AuthenticationForm rejects users whose is_active
flag is set to False. You may override this behavior with a custom
policy to determine which users can log in. Do this with a custom form
that subclasses AuthenticationForm and overrides the
confirm_login_allowed() method. This method should raise a
ValidationError if the given user may
not log in.
For example, to allow all users to log in regardless of “active” status:
from django.contrib.auth.forms import AuthenticationForm
class AuthenticationFormWithInactiveUsersOkay(AuthenticationForm):
def confirm_login_allowed(self, user):
pass
(In this case, you’ll also need to use an authentication backend that
allows inactive users, such as as
AllowAllUsersModelBackend.)
Or to allow only some active users to log in:
class PickyAuthenticationForm(AuthenticationForm):
def confirm_login_allowed(self, user):
if not user.is_active:
raise forms.ValidationError(
_("This account is inactive."),
code='inactive',
)
if user.username.startswith('b'):
raise forms.ValidationError(
_("Sorry, accounts starting with 'b' aren't welcome here."),
code='no_b_users',
)
PasswordChangeForm¶A form for allowing a user to change their password.
PasswordResetForm¶A form for generating and emailing a one-time use link to reset a user’s password.
send_mail(subject_template_name, email_template_name, context, from_email, to_email, html_email_template_name=None)¶Uses the arguments to send an EmailMultiAlternatives.
Can be overridden to customize how the email is sent to the user.
| Parameters: |
|
|---|
By default, save() populates the context with the
same variables that
PasswordResetView passes to its
email context.
SetPasswordForm¶A form that lets a user change their password without entering the old password.
UserChangeForm¶A form used in the admin interface to change a user’s information and permissions.
UserCreationForm¶A ModelForm for creating a new user.
It has three fields: username (from the user model), password1,
and password2. It verifies that password1 and password2 match,
validates the password using
validate_password(), and
sets the user’s password using
set_password().
The currently logged-in user and their permissions are made available in the
template context when you use
RequestContext.
Technicality
Technically, these variables are only made available in the template
context if you use RequestContext and the
'django.contrib.auth.context_processors.auth' context processor is
enabled. It is in the default generated settings file. For more, see the
RequestContext docs.
When rendering a template RequestContext, the
currently logged-in user, either a User
instance or an AnonymousUser instance, is
stored in the template variable {{ user }}:
{% if user.is_authenticated %}
<p>Welcome, {{ user.username }}. Thanks for logging in.</p>
{% else %}
<p>Welcome, new user. Please log in.</p>
{% endif %}
This template context variable is not available if a RequestContext is not
being used.
The currently logged-in user’s permissions are stored in the template variable
{{ perms }}. This is an instance of
django.contrib.auth.context_processors.PermWrapper, which is a
template-friendly proxy of permissions.
Evaluating a single-attribute lookup of {{ perms }} as a boolean is a proxy
to User.has_module_perms(). For example, to check if
the logged-in user has any permissions in the foo app:
{% if perms.foo %}
Evaluating a two-level-attribute lookup as a boolean is a proxy to
User.has_perm(). For example,
to check if the logged-in user has the permission foo.can_vote:
{% if perms.foo.can_vote %}
Here’s a more complete example of checking permissions in a template:
{% if perms.foo %}
<p>You have permission to do something in the foo app.</p>
{% if perms.foo.can_vote %}
<p>You can vote!</p>
{% endif %}
{% if perms.foo.can_drive %}
<p>You can drive!</p>
{% endif %}
{% else %}
<p>You don't have permission to do anything in the foo app.</p>
{% endif %}
It is possible to also look permissions up by {% if in %} statements.
For example:
{% if 'foo' in perms %}
{% if 'foo.can_vote' in perms %}
<p>In lookup works, too.</p>
{% endif %}
{% endif %}
When you have both django.contrib.admin and django.contrib.auth
installed, the admin provides a convenient way to view and manage users,
groups, and permissions. Users can be created and deleted like any Django
model. Groups can be created, and permissions can be assigned to users or
groups. A log of user edits to models made within the admin is also stored and
displayed.
You should see a link to “Users” in the “Auth” section of the main admin index page. The “Add user” admin page is different than standard admin pages in that it requires you to choose a username and password before allowing you to edit the rest of the user’s fields.
Also note: if you want a user account to be able to create users using the Django admin site, you’ll need to give them permission to add users and change users (i.e., the “Add user” and “Change user” permissions). If an account has permission to add users but not to change them, that account won’t be able to add users. Why? Because if you have permission to add users, you have the power to create superusers, which can then, in turn, change other users. So Django requires add and change permissions as a slight security measure.
Be thoughtful about how you allow users to manage permissions. If you give a non-superuser the ability to edit users, this is ultimately the same as giving them superuser status because they will be able to elevate permissions of users including themselves!
User passwords are not displayed in the admin (nor stored in the database), but the password storage details are displayed. Included in the display of this information is a link to a password change form that allows admins to change user passwords.
Jan 17, 2018