使用 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 里自由地重新映射你的登录视图，而不需更新配置文件。

The LoginRequiredMixin 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_nameLink to this definition#

The name of a template to display for the view used to log the user in. Defaults to registration/login.html.

next_pageLink to this definition#

The URL to redirect to after login. Defaults to LOGIN_REDIRECT_URL.

redirect_field_nameLink to this definition#

The name of a GET field containing the URL to redirect to after login. Defaults to next. Overrides the get_default_redirect_url() URL if the given GET parameter is passed.

authentication_formLink to this definition#

A callable (typically a form class) to use for authentication. Defaults to AuthenticationForm.

extra_contextLink to this definition#

A dictionary of context data that will be added to the default context data passed to the template.

redirect_authenticated_userLink to this definition#

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.

success_url_allowed_hostsLink to this definition#

A set of hosts, in addition to request.get_host(), that are safe for redirecting after login. Defaults to an empty set.

get_default_redirect_url()Link to this definition#

Returns the URL to redirect to after login. The default implementation resolves and returns next_page if set, or LOGIN_REDIRECT_URL otherwise.

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'] 的值。更多关于站点信息，请参考 “站点”框架 。

如果你不愿意调用模板 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 set up 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#

Logs a user out on POST requests.

URL name: logout

属性：

next_pageLink to this definition#

The URL to redirect to after logout. Defaults to LOGOUT_REDIRECT_URL.

template_nameLink to this definition#

The full name of a template to display after logging the user out. Defaults to registration/logged_out.html.

redirect_field_nameLink to this definition#

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_contextLink to this definition#

A dictionary of context data that will be added to the default context data passed to the template.

success_url_allowed_hostsLink to this definition#

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 ：字符串 "已注销"，已本地化。

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

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

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

Logs a user out on POST requests, then redirects to the login page.

URL name: 没有提供默认的 URL

可选参数：

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

class PasswordChangeViewLink to this definition#

URL name: password_change

允许用户修改密码。

属性：

template_nameLink to this definition#

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_urlLink to this definition#

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

form_classLink to this definition#

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_contextLink to this definition#

A dictionary of context data that will be added to the default context data passed to the template.

Template context:

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

class PasswordChangeDoneViewLink to this definition#

URL name: password_change_done

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

属性：

template_nameLink to this definition#

The full name of a template to use. Defaults to registration/password_change_done.html if not supplied.

extra_contextLink to this definition#

A dictionary of context data that will be added to the default context data passed to the template.

class PasswordResetViewLink to this definition#

URL name: password_reset

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

This view will send an email if the following conditions are met:

• 提供的电子邮件地址存在于系统中。

• The requested user is active (User.is_active is True).

• The requested user has a usable password. 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.

If any of these conditions are not met, no email will be sent, 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.

属性：

template_nameLink to this definition#

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_classLink to this definition#

Form that will be used to get the email of the user to reset the password for. Defaults to PasswordResetForm.

email_template_nameLink to this definition#

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_nameLink to this definition#

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_generatorLink to this definition#

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_urlLink to this definition#

The URL to redirect to after a successful password reset request. Defaults to 'password_reset_done'.

from_emailLink to this definition#

一个合法的邮件地址。默认情况下，Django 使用 DEFAULT_FROM_EMAIL 。

extra_contextLink to this definition#

A dictionary of context data that will be added to the default context data passed to the template.

html_email_template_nameLink to this definition#

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_contextLink to this definition#

A dictionary of context data that will be available in the email template. It can be used to override default template context values listed below e.g. domain.

Template context:

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

电子邮件模板上下文:

• email ：user.email 的别名。

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

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

• 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_nameLink to this definition#

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

extra_contextLink to this definition#

A dictionary of context data that will be added to the default context data passed to the template.

class PasswordResetConfirmViewLink to this definition#

URL name: password_reset_confirm

提供输入新密码的表单。

URL 的关键参数

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

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

属性：

template_nameLink to this definition#

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

token_generatorLink to this definition#

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

post_reset_loginLink to this definition#

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

post_reset_login_backendLink to this definition#

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

form_classLink to this definition#

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

success_urlLink to this definition#

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

extra_contextLink to this definition#

A dictionary of context data that will be added to the default context data passed to the template.

reset_url_tokenLink to this definition#

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

Template context:

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

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

class PasswordResetCompleteViewLink to this definition#

URL name: password_reset_complete

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

属性：

template_nameLink to this definition#

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

extra_contextLink to this definition#

A dictionary of context data that will be added to the default context data passed to the template.

用户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 %}