使用 Django 的验证系统Link to this heading#

选择验证后端Link to this heading#

当用户登录时，用户 ID 和用于身份验证的后端会被保存在用户会话中。允许相同的 authentication backend 在未来的请求中获取用户详情。选择要在会话中保存的验证后端如下：

1. 使用提供了的可选 backend 参数值。

2. 使用 user.backend  的值。允许配对 authenticate()  和 login() ：当返回用户对象时 authenticate() 设置 user.backend 属性。

3. 使用 AUTHENTICATION_BACKENDS 存在的 backend 。

4. 否则，抛出一个异常。

在1和2中，backend 参数和 user.backend 属性应该是完整的导入路径（像 AUTHENTICATION_BACKENDS 里的路径一样），而不是真实的后端类。

原始方式Link to this heading#

限制访问页面最原始的办法就是检查 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 装饰器Link to this heading#

login_required(redirect_field_name='next', login_url=None)Link to this definition#

作为快捷方式，你可以使用 login_required() 装饰器:

Code

from django.contrib.auth.decorators import login_required

@login_required
def my_view(request):
    ...

login_required() 会执行以下操作：

• 如果用户没有登录，会重定向到 settings.LOGIN_URL ，并传递绝对路径到查询字符串中。例如： /accounts/login/?next=/polls/3/ 。

• 如果用户已经登录，则正常执行视图。视图里的代码可以假设用户已经登录了。

默认情况下，成功验证时用户跳转的路径保存在名为 "next" 的查询字符串参数中。如果你希望这个参数使用不同名称，请在 login_required() 中传递可选参数 redirect_field_name ：

Code

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 。例如：

Code

from django.contrib.auth.decorators import login_required

@login_required(login_url='/accounts/login/')
def my_view(request):
    ...

注意，如果你没有指定参数 login_url ，你需要确认 settings.LOGIN_URL  和登录视图是正确关联的。例如，使用默认方式，在 URL 配置文件里添加下面这行：

Code

from django.contrib.auth import views as auth_views

path('accounts/login/', auth_views.LoginView.as_view()),

settings.LOGIN_URL 也接受视图方法名和 named URL patterns 。这样你可以在 URLconf 里自由地重新映射你的登录视图，而不需更新配置文件。

LoginRequired MixinLink to this heading#

使用基于类的视图时，可以使用 LoginRequiredMixin 实现和 login_required 相同的行为。这个 Mixin 应该在继承列表中最左侧的位置。

class LoginRequiredMixinLink to this definition#

如果一个视图使用 Mixin ，那么未经验证用户的所有请求都会被重定向到登录页面或者显示 HTTP 403 Forbidden 错误，这取决于 raise_exception 参数。

你可以设置 AccessMixin 的任何参数来自定义未验证用户的处理：

Code

from django.contrib.auth.mixins import LoginRequiredMixin

class MyView(LoginRequiredMixin, View):
    login_url = '/login/'
    redirect_field_name = 'redirect_to'

限制对通过测试的登录用户的访问Link to this heading#

根据某些权限或者其他测试来限制访问，你基本上可以执行和上一节所述同样的操作。

可以在视图里直接对 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')Link to this definition#

作为快捷方式，你可以方便的调用 user_passes_test 装饰器，当调用返回 False 时会执行重定向。

Code

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() 接受一个必要的参数：一个带有:class:~django.contrib.auth.models.User 对象的调用，如果允许用户访问这个页面，则返回 True 。注意，user_passes_test() 不会自动检查用户是否匿名。

user_passes_test() 可以传递两个可选参数：

login_url

允许你指定用户没有通过测试时跳转的地址。它可能是一个登录页面，如果你没指定，默认是 settings.LOGIN_URL 。

redirect_field_name

与 login_required() 相同。如果你想把没通过检查的用户重定向到没有 "next page" 的非登录页面时，把它设置为 None ，这样它会在 URL 中移除。

例如:

Code

@user_passes_test(email_check, login_url='/login/')
def my_view(request):
    ...

class UserPassesTestMixinLink to this definition#

使用基于类的视图时，可以使用 UserPassesTestMixin 执行此操作。

test_func()Link to this definition#

你必须覆盖类方法 test_func() 以提供执行的测试。此外，还可以设置 AccessMixin 的任何参数来自定义处理未授权用户：

Code

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()Link to this definition#

你也可以覆盖 get_test_func() 方法，以使 mixin 对其检查使用不同名称的函数（而不是 test_func() ）。

permission_required 装饰器Link to this heading#

permission_required(perm, login_url=None, raise_exception=False)Link to this definition#

检查用户是否拥有特定的权限是一个相对常见的任务。出于这个原因，Django 提供了一个快捷方式：permission_required() 装饰器：

Code

from django.contrib.auth.decorators import permission_required

@permission_required('polls.add_choice')
def my_view(request):
    ...

就像 has_perm() 方法一样，权限名称采用 "<app label>.<permission codename>" 形式（比如 polls.polls.add_choice 就是 polls 应用程序下的模型的权限）。

装饰器也可以接受可迭代权限，在这种情况下，用户必须拥有所有权限才能访问视图。

注意， permission_required() 也可以接受可选的 login_url 参数：

Code

from django.contrib.auth.decorators import permission_required

@permission_required('polls.add_choice', login_url='/loginpage/')
def my_view(request):
    ...

和 login_required() 装饰器一样， login_url 默认是:setting:settings.LOGIN_URL <LOGIN_URL>。

如果有 raise_exception 参数，那么装饰器将引发 PermissionDenied 错误，提示 the 403 (HTTP Forbidden) view 而不是跳转到登录页面。

如果你想使用 raise_exception 但也想给用户登录的机会，那需要添加 login_required() 装饰器：

Code

from django.contrib.auth.decorators import login_required, permission_required

@login_required
@permission_required('polls.add_choice', raise_exception=True)
def my_view(request):
    ...

当 LoginView 的 redirect_authenticated_user=True 并且已登录用户没有所有必须的权限时，这避免了重定向循环。

PermissionRequiredMixin MixinLink to this heading#

在 class-based views 中应用权限检查，你可以使用 PermissionRequiredMixin ：

class PermissionRequiredMixinLink to this definition#

和 permission_required 装饰器一样，Mixin 检查用户访问的视图是否拥有全部的权限。你应该使用 permission_required 指定权限（或者可迭代权限）：

Code

from django.contrib.auth.mixins import PermissionRequiredMixin

class MyView(PermissionRequiredMixin, View):
    permission_required = 'polls.add_choice'
    # Or multiple of permissions:
    permission_required = ('polls.view_choice', 'polls.change_choice')

你可以设置 AccessMixin 的任意参数来自定义处理没有权限的用户。

你可能同样需要重写这些方法：

get_permission_required()Link to this definition#

返回 Mixin 使用的可迭代权限的名称。默认为 permission_required 属性，如果需要可以转化为元组。

has_permission()Link to this definition#

返回布尔值，表示当前用户是否拥有权限执行装饰器视图。默认情况下，这将返回调用 has_perms() 的结果，其中包括返回 get_permission_required() 的权限列表。

密码更改时会话失效Link to this heading#

如果 AUTH_USER_MODEL 继承自 AbstractBaseUser 或实现了自己的 get_session_auth_hash() 方法，已验证的会话将包含这个函数返回的哈希值。在 AbstractBaseUser 的情况下，这是密码字段的 HMAC 。Django 验证每个请求的会话中的哈希是否与请求期间计算的哈希相匹配。这允许用户修改密码来注销所有会话。

Django 包含默认的密码修改视图，PasswordChangeView 和 user_change_password 视图在 django.contrib.auth admin 中，将使用新密码的哈希更新会话，因此用户修改密码后不会被注销。如果你有自定义的密码修改视图，并期望有同样的行为，可以使用 update_session_auth_hash() 函数。

update_session_auth_hash(request, user)Link to this definition#

这个函数接受当前请求和从新会话哈希派生时更新的用户对象，并会更新哈希值。它也会替换哈希值因此被盗用的会话cookie会无效。

用法示例：

Code

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:
        ...

使用视图Link to this heading#

在项目中可以使用不同方法来实现这些视图。最简单的方法就是在 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 模式的使用详情参考 the URL documentation 。

如果你想更好的控制 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'),
    ),
]

所有视图都是基于类的，这就允许你通过子类去方便地自定义它们。

所有的验证视图Link to this heading#

这是一个 django.contrib.auth 提供的所有视图列表。有关实现细节可参考 使用视图 。

class LoginViewLink to this definition#

URL name: login

有关使用命名 URL 模式的细节可参考 the URL documentation 。

属性：

• template_name ：用户登录的视图所使用的模板名称。默认指向 registration/login.html 。

• redirect_field_name ： GET 字段包含的登录后跳转 URL 的参数名称。默认是 next 。

• authentication_form ：用于验证的调用（通常是一个表单类）。默认是 AuthenticationForm 。

• extra_context ：上下文数据字典，通过模板添加到默认上下文数据中。

• redirect_authenticated_user ：布尔值，用来控制已验证的用户访问登录页面是否被重定向，就像他们刚刚成功登录一样。默认是 False 。

• success_url_allowed_hosts ：除了 request.get_host() 之外的主机集合，登录后能安全地重定向。默认是空集。

LoginView 能做什么：

• 如果通过 GET 调用，它将显示 POST 到同一 URL 地址的登录表单。稍后会详细介绍。

• 如果用户提交的数据通过 POST 调用，那它将试着让用户登录。如果登录成功，那么视图将重定向到 next 指定的 URL 。如果没有提供 next ，它将重定向到 settings.LOGIN_REDIRECT_URL （默认 /accounts/profile/ ）。如果登录没有成功，它将重新显示登录表单。

你需要提供登录模板，默认调用 registration/login.html 。这个模板传递四个模板上下文变量：

• form ：一个代表 AuthenticationForm 的 Form 对象。

• next ：登录成功后跳转的网址。这可能包含查询字段。

• site ：根据 SITE_ID 设置的当前站点。如果你还没有安装站点框架，会将其设置为 RequestSite 实例，该实例从当前 HttpRequest 中派生出站点名和域名。

• site_name ：site.name 的别名。如果你还没有按照站点框架，它将设置为 request.META['SERVER_NAME'] 的值。更多关于站点信息，请参考 The "sites" framework 。

如果你不愿意调用模板 registration/login.html ，你可以通过附加参数的形式传递 template_name 参数给你的 URLconf 中的 as_view 方法。比如，这行 URLconf 将使用 myapp/login.html 代替：

Code

path('accounts/login/', auth_views.LoginView.as_view(template_name='myapp/login.html')),

你也可以使用 redirect_field_name 指定 GET 字段的名称，这个字段包含登陆后跳转的 URL 地址。默认情况下，这个字段为 next 。

下面是一个简单的 registration/login.html 模板。它假设你有 base.html 模板，并且已经定义了 content 块：

Django template

{% 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 %}

如果你具有自定义身份验证（查看 Customizing Authentication ），可以通过设置 authentication_form 属性来使用自定义的验证码模板。此表单必须在它的 __init__() 方法中接受 request 关键字参数，并且提供一个返回已验证用户对象的 get_user() 方法（这个方法只会在表单成功验证后调用）。

class LogoutViewLink to this definition#

注销用户

URL name: logout

属性：

• next_page ：注销后将要跳转的 URL 。默认是 settings.LOGOUT_REDIRECT_URL 。

• template_name ：用户注销后显示的模板地址。默认是 registration/logged_out.html 。

• redirect_field_name ：注销后包含重定向 URL 的 GET 字段名称。默认是 next 。如果传递给定的 GET 参数，将会覆盖 next_page URL。

• extra_context ：上下文数据字典，通过模板添加到默认上下文数据中。

• success_url_allowed_hosts ：除了 request.get_host() 之外的主机集合，在注销后可以安全地重定向。默认是空集。

Template context:

• title ：字符串 "已注销"，已本地化。

• site ：根据 SITE_ID 设置的当前站点。如果你还没有安装站点框架，会将其设置为 RequestSite 实例，该实例从当前 HttpRequest 中派生出站点名和域名。

• site_name ：site.name 的别名。如果你还没有按照站点框架，它将设置为 request.META['SERVER_NAME'] 的值。更多关于站点信息，请参考 The "sites" framework 。

logout_then_login(request, login_url=None)Link to this definition#

用户注销，然后重定向到登录页面。

URL name: 没有提供默认的 URL

可选参数：

• login_url ：要重定向到登录页面的 URL 。如果没有提供，默认是 settings.LOGIN_URL 。

class PasswordChangeViewLink to this definition#

URL name: password_change

允许用户修改密码。

属性：

• template_name ：用于显示密码修改表单的模板全称。如果没提供则默认 registration/password_change_form.html 。

• success_url ：密码修改成功后跳转的 URL 。默认是 'password_change_done' 。

• form_class ：一个自定义修改密码的表单，此表单必须接收 user 关键字参数。表单负责实际修改用户密码。默认是 PasswordChangeForm 。

• extra_context ：上下文数据字典，通过模板添加到默认上下文数据中。

Template context:

• form ：密码修改表单（参考上面的 form_class ）

class PasswordChangeDoneViewLink to this definition#

URL name: password_change_done

用户修改密码之后显示的页面。

属性：

• template_name ：所使用模板的全称。如果没有提供，则默认 registration/password_change_done.html 。

• extra_context ：上下文数据字典，通过模板添加到默认上下文数据中。

class PasswordResetViewLink to this definition#

URL name: password_reset

允许用户通过生成的一次性链接来重置密码，并把一次性链接发到用户注册邮箱中。

如果邮箱地址并不存在，视图不会发送邮件，但用户也不会受到任何错误信息。这是为了防止信息泄露给潜在的攻击者。如果你想提供错误信息，你可以成为继承 PasswordResetForm ，并使用 form_class 属性。

不可使用密码的用户 （查看 set_unusable_password() ）不能请求重置密码，以防止在使用类似 LDAP 等外部验证源时滥用。注意，它们将无法收到错误信息，因为这将暴露用户账号是否存在，并且也不会发送邮件。

属性：

• template_name ：用来显示密码重置表单的模板全称。如果没提供，则默认 registration/password_reset_form.html 。

• form_class ：用于获取用户的重置密码的电子邮件的表单。默认是 PasswordResetForm 。

• email_template_name ：用来生成重置密码链接的电子邮件模板。如果没有提供，默认是 registration/password_reset_email.html 。

• subject_template_name ：重置密码电子邮件主题的模板全称。如果没有提供，则是 registration/password_reset_subject.txt 。

• token_generator ：检测一次性链接的类实例。默认是 default_token_generator ，这是 django.contrib.auth.tokens.PasswordResetTokenGenerator 的一个实例。

• success_url: 密码重置请求成功后跳转的 URL 。默认是 'password_reset_done' 。

• from_email ：合法邮件地址。默认情况下，Django 使用 DEFAULT_FROM_EMAIL 。

• extra_context ：上下文数据字典，通过模板添加到默认上下文数据中。

• html_email_template_name ：用来生成带有密码重置链接的 text/html 多用途电子邮件。默认情况下，HTML 单子邮件不会被发送。

• extra_email_context: 在邮件模板提供上下文数据字典。它被用来覆盖下面列出的默认模板上下文值，比如 domain。

Template context:

• form ：重置用户密码的表单（可参考上面的 form_class ）。

电子邮件模板上下文:

• email ：user.email 的别名。

• user ：根据电子邮件表单字段指定的当前用户。只有活动用户才可以重置密码（ User.is_active 为 True ）。

• site_name ：site.name 的别名。如果你还没有按照站点框架，它将设置为 request.META['SERVER_NAME'] 的值。更多关于站点信息，请参考 The "sites" framework 。

• domain ：site.domain 的别名。如果你还没有安装网站框架，它会被设置为 request.get_host() 的值。

• protocol ：http 或 https

• uid ：使用 Base64 编码过的用户主键。

• token ：检测重置密码链接是否有效的 Token 。

registration/password_reset_email.html 例子（电子邮件内容模板）

Django template

Someone asked for password reset for email {{ email }}. Follow the link below:
{{ protocol}}://{{ domain }}{% url 'password_reset_confirm' uidb64=uid token=token %}

相同的模板上下文用于主题模板。主题必须是单行纯文本字符串。

class PasswordResetDoneViewLink to this definition#

URL name: password_reset_done

发送重置密码邮件后显示的页面。如果 PasswordResetView 没有明确设置 success_url ，那么默认将该视图调用。

属性：

• template_name ：被使用模板的全称。如果没有提供，则默认是 registration/password_reset_done.html

• extra_context ：上下文数据字典，通过模板添加到默认上下文数据中。

class PasswordResetConfirmViewLink to this definition#

URL name: password_reset_confirm

提供输入新密码的表单。

URL 的关键参数

• uidb64 ：被Base64编码过的用户 id。

• token ：检查密码是否有效的 Token。

属性：

• template_name ：用于显示确认密码视图的模板全称。默认值是 registration/password_reset_confirm.html 。

• token_generator ：检查密码的类实例。默认是 default_token_generator，它是 django.contrib.auth.tokens.PasswordResetTokenGenerator 的实例。

• post_reset_login ：布尔值，用来标示用户成功重置密码后是否会被自动验证。默认是 False 。

• post_reset_login_backend ：验证后端的路径，用于当 post_reset_login 是 True 时验证用户使用。当拥有多个 AUTHENTICATION_BACKENDS 设置时才会用到。默认为 None 。

• form_class ：用来设置密码的表单。默认是 SetPasswordForm 。

• success_url ：重置密码完成后跳转的 URL 。默认 'password_reset_complete' 。

• extra_context ：上下文数据字典，通过模板添加到默认上下文数据中。

• reset_url_token: Token 参数为密码重置链接的组成部分。默认 'set-password' 。

Template context:

• form ：用来设置用户新密码的表单（查看上面的 form_class ）。

• validlink ：布尔值，如果链接（uidb64 和 token 的组合）有效且合法，则返回 True 。

class PasswordResetCompleteViewLink to this definition#

URL name: password_reset_complete

当密码已经被修改成功后通知用户的视图。

属性：

• template_name ：显示视图的模板全称。默认 registration/password_reset_complete.html 。

• extra_context ：上下文数据字典，通过模板添加到默认上下文数据中。

用户Link to this heading#

当渲染模板 RequestContext ，当前登录用户（User 实例或 AnonymousUser 实例）被保存在模板变量 {{ user }} 中：

{% if user.is_authenticated %}
    <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
{% else %}
    <p>Welcome, new user. Please log in.</p>
{% endif %}

如果没有使用 RequestContext ，那么这个模板上下文变量将不可用。

权限Link to this heading#

当前登录用户的权限保存在模板变量 {{ perms }} 中。这是 django.contrib.auth.context_processors.PermWrapper 的一个实例，它是一个对模板友好的权限代理。

将 {{ perms }} 的单属性查找作为布尔值为 User.has_module_perms() 的代理。比如，检测登录用户是否拥有一些权限：

{% if perms.foo %}

将两层属性查找作为布尔值是 User.has_perm() 的代理。比如，检测登录用户是否拥有 foo.add_vote 权限：

{% if perms.foo.add_vote %}

以下是一个在模板中检查权限的更完整的示例：

{% if perms.foo %}
    <p>You have permission to do something in the foo app.</p>
    {% if perms.foo.add_vote %}
        <p>You can vote!</p>
    {% endif %}
    {% if perms.foo.add_driving %}
        <p>You can drive!</p>
    {% endif %}
{% else %}
    <p>You don't have permission to do anything in the foo app.</p>
{% endif %}

也可以通过 {% if in %} 语句来查找权限。比如：

{% if 'foo' in perms %}
    {% if 'foo.add_vote' in perms %}
        <p>In lookup works, too.</p>
    {% endif %}
{% endif %}