原始的方法

限制页面访问的简单、原始的方法是检查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 装饰器

login_required([redirect_field_name=REDIRECT_FIELD_NAME, login_url=None])[source]?

作为一个快捷方式，你可以使用便捷的login_required()装饰器：

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参数：

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

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

url(r‘^accounts/login/$‘, auth_views.login),

settings.LOGIN_URL同时还接收视图函数名和命名的URL模式。这允许你自由地重新映射你的URLconf中的登录视图而不用更新设置。

给已验证登录的用户添加访问限制

基于特定的权限和其他方式来限制访问，你最好按照前面描述的那样操作。

简单的方法就是在视图中直接运行你对request.user的测试。例如，视图检查用户的邮件属于特定的地址（例如@example.com），若不是，则重定向到登录页面。

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(func[, login_url=None, redirect_field_name=REDIRECT_FIELD_NAME])[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 对象为参数的回调函数，若用户允许访问此视图，返回 True。注意，user_passes_test() 不会自动检查 User 是否为匿名对象。

user_passes_test()接收两个额外的参数：

login_url

让你指定那些没有通过检查的用户要重定向至哪里。若不指定其值，它可能是默认的 settings.LOGIN_URL。

redirect_field_name

与login_required()的参数相同。把它设置为 None 来把它从 URL 中移除，当你想把通不过检查的用户重定向到没有next page 的非登录页面时。

例如：

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

permission_required 装饰器

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 应用下一个模块的权限。

要注意permission_required() 也接受一个可选的login_url参数。例如：

from django.contrib.auth.decorators import permission_required

@permission_required(‘polls.can_vote‘, login_url=‘/loginpage/‘)
def my_view(request):
    ...

在 login_required() 装饰器中， login_url默认为settings.LOGIN_URL。

如果提供了 raise_exception 参数，装饰器抛出PermissionDenied异常，使用 the 403 (HTTP Forbidden) 视图而不是重定向到登录页面。

Changed in Django 1.7:

permission_required()装饰器既可以接收一个权限序列也可以接收一个单个的权限。

对普通的视图使用权限?

若要对一个基于类的普通视图使用权限，可以在该类上装饰View.dispatch方法。详细细节参见Decorating the class。 另外一个方法是编写一个封装as_view()的mixin。

密码更改后的会话失效

如果你的AUTH_USER_MODEL继承自AbstractBaseUser，或者实现了它自己的get_session_auth_hash()方法，验证后的会话会包含这个函数返回的哈希值。在AbstractBaseUser的情况中，这是密码字段的HMAC。如果开启了SessionAuthenticationMiddleware ，Django会验证每个请求带有的哈希值是否匹配服务端计算出来的哈希值。这允许用户通过修改密码来登出所有的会话。

Django中包含的默认的密码修改视图，以及django.contrib.auth中的 django.contrib.auth.views.password_change()和user_change_password视图 ，会使用新的密码哈希值升级会话，以便用户在修改密码时不会登出。如果你拥有自定义的密码修改视图，并且希望具有相似的行为，使用这个函数：

update_session_auth_hash(request, user)

这个函数接受当前请求，并且会在会话哈希值得到的地方升级用户对象，也会适当地升级会话哈希值。使用示例：

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

如果你在升级一个现存的站点，并且希望开启这一中间件，而不希望你的所有用户之后重新登录，你可以首先升级到DJango1.7并且运行它一段时间，以便所有会话在用户登录时自然被创建，它们包含上面描述的会话哈希。一旦你使用SessionAuthenticationMiddleware开始运行你的站点，任何没有登录并且会话使用验证哈希值升级过的用户的现有会话都会失效，并且需要重新登录。

使用视图

有几种不同的方法在你的项目中使用这些视图。最简单的方法是包含django.contrib.auth.urls 中提供的URLconf到你自己的URLconf中，例如

urlpatterns = [
    url(‘^‘, include(‘django.contrib.auth.urls‘))
]

这将包含进下面的URL模式：

^login/$ [name=‘login‘]
^logout/$ [name=‘logout‘]
^password_change/$ [name=‘password_change‘]
^password_change/done/$ [name=‘password_change_done‘]
^password_reset/$ [name=‘password_reset‘]
^password_reset/done/$ [name=‘password_reset_done‘]
^reset/(?P<uidb64>[0-9A-Za-z_\-]+)/(?P<token>[0-9A-Za-z]{1,13}-[0-9A-Za-z]{1,20})/$ [name=‘password_reset_confirm‘]
^reset/done/$ [name=‘password_reset_complete‘]

这些视图提供了一个简单易记的URL名称。使用命名URL模式的细节请参见URL文档。

如果你想更多地控制你的URL，你可以在你的URLconf中引用一个特定的视图：

urlpatterns = [
    url(‘^change-password/‘, ‘django.contrib.auth.views.password_change‘)
]

这些视图具有可选的参数，你可以用来改变视图的行为。例如，如果你想修改一个视图使用的模板名称，你可以提供template_name 参数。一种方法是在URLconf 中提供关键字参数，它们将被传递到视图中。例如：

urlpatterns = [
    url(
        ‘^change-password/‘,
        ‘django.contrib.auth.views.password_change‘,
        {‘template_name‘: ‘change-password.html‘}
    )
]

所有的视图都返回一个TemplateResponse 实例，这让你在渲染前自定义响应很容易。一种方法是在你自己的视图中封装一个视图：

from django.contrib.auth import views

def change_password(request):
    template_response = views.password_change(request)
    # Do something with `template_response`
    return template_response

更多的细节，参见TemplateResponse文档。

所有的认证视图

下面列出了django.contrib.auth提供的所有视图。实现细节参见使用视图。

login(request[, template_name, redirect_field_name, authentication_form, current_app, extra_context])[source]?

URL 名称： login

关于使用命名URL模式的细节参见URL 文档。

可选的参数：

• template_name: 用于用户登录视图的模板名。默认为registration/login.html。
• redirect_field_name: GET字段的名称，包含登陆后重定向URL。默认为next。
• authentication_form: 用于认证的可调用对象（通常只是一个表单类）。默认为AuthenticationForm。
• current_app: 指示包含当前视图的是哪个应用。更多信息参见命名URL的解析策略。
• extra_context: 一个上下文数据的字典，将被添加到传递给模板的默认上下文数据中。

下面是django.contrib.auth.views.login所做的事情：

• 如果通过 GET调用，它显示一个POST给相同URL的登录表单。后面有更多这方面的信息。
• 如果通过POST调用并带有用户提交的凭证，它会尝试登入该用户。如果登入成功，该视图重定向到next中指定的URL。如果next没有提供，它重定向到settings.LOGIN_REDIRECT_URL（默认为/accounts/profile/）。如果登入不成功，则重新显示登录表单。

你需要提供html模板给login，默认调用registration/login.html。模板会得到4个模板上下文变量：

• form: 一个表示AuthenticationForm的Form对象。
• next: 登入成功之后重定向的URL。它还可能包含一个查询字符串。
• site: 如果你没有安装site框架，这将被设置成RequestSite的一个实例，它从当前的HttpRequest获得site名称和域名。
• site_name: site.name的别名。如果你没有安装site框架，这将被设置成request.META[‘SERVER_NAME‘]的值。关于site 的更多信息，参见“sites” 框架。

如果你不喜欢调用registration/login.html，你可以通过额外的参数传递template_name参数给你URLconf中的视图。例如，下面URLconf中的行将使用myapp/login.html：

url(r‘^accounts/login/$‘, auth_views.login, {‘template_name‘: ‘myapp/login.html‘}),

通过传递redirect_field_name给视图，你还可以指定GET字段的值，它包含登入成功后的重定向的URL。默认情况下，该字段叫做next。

下面是一个registration/login.html模板的示例，你可以用它来作为起点。它假设你有一个定义了content块的base.html模板：

{% extends "base.html" %}

{% block content %}

{% if form.errors %}
<p>Your username and password didn‘t match. Please try again.</p>
{% endif %}

<form method="post" action="{% url ‘django.contrib.auth.views.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>

{% endblock %}

如果你自定义认证（参见Customizing Authentication），你可以通过authentication_form参数传递一个自定义的认证表单给登录视图。该表单必须在它的__init__方法中接收一个request关键字参数，并提供一个get_user方法，此方法返回认证过的用户对象（这个方法永远只在表单验证成功后调用）。

logout(request[, next_page, template_name, redirect_field_name, current_app, extra_context])[source]?

登出一个用户。

URL名称： logout

可选的参数：

• next_page: 登出之后要重定向的URL。
• template_name: 用户登出之后，要展示的模板的完整名称。如果不提供任何参数，默认为registration/logged_out.html。
• redirect_field_name: 包含登出之后所重定向的URL的GET字段的名称。默认为 next。如果提供了GET参数，会覆盖next_page URL。
• current_app: 一个提示，表明哪个应用含有了当前视图。 详见 命名空间下的URL解析策略 。
• extra_context: 一个上下文数据的字典，会被添加到向模板传递的默认的上下文数据中。

模板上下文：

• title: 本地化的字符串“登出”。
• site: 根据SITE_ID 设置的当前站点。如果你并没有安装站点框架，会设置为 RequestSite的示例，它从当前HttpRequest来获取站点名称和域名。
• site_name: site.name的别名。如果没有安装站点框架，会设置为request.META[‘SERVER_NAME‘]。站点的更多信息请见“站点”框架。
• current_app: 一个提示，表明哪个应用含有了当前视图。 详见 命名空间下的URL解析策略 。
• extra_context: 一个上下文数据的字典，会被添加到向模板传递的默认的上下文数据中。

logout_then_login(request[, login_url, current_app, extra_context])[source]?

登出一个用户，然后重定向到登录页面。

URL 名称： 没有提供默认的URL

可选的参数：

• login_url: 登录页面要重定向的URL。如果没有提供，默认为settings.LOGIN_URL。
• current_app: 一个提示，表明哪个应用含有了当前视图。详见 命名空间下的URL解析策略 。
• extra_context: 一个上下文数据的字典，会被添加到向模板传递的默认的上下文数据中。

password_change(request[, template_name, post_change_redirect, password_change_form, current_app, extra_context])[source]?

允许一个用户修改他的密码。

URL 名称： password_change

可选的参数：

• template_name: 用来显示修改密码表单的template的全名。如果没有提供，默认为registration/password_change_form.html 。
• post_change_redirect: 密码修改成功后重定向的URL。
• password_change_form: 一个自定义的“修改密码”表单，必须接受user 关键词参数。表单用于实际修改用户密码。默认为 PasswordChangeForm。
• current_app: 一个提示，暗示哪个应用包含当前的视图。详见 命名空间下的URL解析策略 。
• extra_context: 上下文数据的字典，会添加到传递给模板的默认的上下文数据中。

模板上下文：

• form: 密码修改表单（请见上面的password_change_form）。

password_change_done(request[, template_name, current_app, extra_context])[source]?

这个页面在用户修改密码之后显示。

URL 名称： password_change_done

可选参数：

• template_name: 所使用模板的完整名称。如果没有提供，默认为registration/password_change_done.html。
• current_app: 一个提示，暗示哪个应用包含当前的视图。 详见 命名空间下的URL解析策略 。
• extra_context: 上下文数据的字典，会添加到传递给模板的默认的上下文数据中。

password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect, from_email, current_app, extra_context, html_email_template_name])[source]?

允许用户通过生成一次性的连接并发送到用户注册的邮箱地址中来重置密码。

如果提供的邮箱地址不在系统中存在，这个视图不会发送任何邮件，但是用户也不会收到任何错误信息。这会阻止数据泄露给潜在的攻击者。如果你打算在这种情况提供错误信息，你可以继承PasswordResetForm，并使用password_reset_form 参数。

用无效密码标记的用户（参见set_unusable_password()）不允许请求重置密码，为了防止使用类似于LDAP的外部验证资源时的滥用。注意它们不会收到任何错误信息，因为这会暴露它们的账户，也不会发送任何邮件。

URL 名称： password_reset

可选参数：

• 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，它是 django.contrib.auth.tokens.PasswordResetTokenGenerator 的一个实例。
• post_reset_redirect: 密码重置请求成功后，将重定向到的URL。
• from_email: 一个有效的电子邮件地址。默认情况下Django 使用DEFAULT_FROM_EMAIL。
• current_app: 指示哪个应用程序包含当前视图的提示。有关详细信息，请参阅namespaced URL resolution strategy。
• extra_context: 将添加到传递给模板的默认上下文数据的上下文数据字典。
• html_email_template_name: 用于使用密码重置链接生成text/html多部分电子邮件的模板的全名。默认情况下，不发送HTML电子邮件。

New in Django 1.7:

添加了html_email_template_name。

自1.8版起已弃用：is_admin_site参数已被废弃，将在Django2.0中被移除。

模板上下文：

• form: 用于重置用户密码的表单（请参阅上面的password_reset_form）。

Email模板上下文：

• email: user.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: 用户的主键编码在base 64中。
• token: 令牌检查重置链接是否有效。

registration/password_reset_email.html样例（邮件正文模板）：

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

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

password_reset_done(request[, template_name, current_app, extra_context])[source]?

这个页面在向用户发送重置密码的邮件后展示。如果password_reset()视图没有显式设置 post_reset_redirectURL，默认会调用这个视图。

URL名称： password_reset_done

注意

如果提供的email地址在系统中不存在，用户未激活，或者密码不可用，用户仍然会重定向到这个视图，但是不会发送邮件。

可选参数：

• template_name: 所使用模板的全名如果未提供，默认为registration/password_reset_done.html。
• current_app: 指示哪个应用程序包含当前视图的提示。有关详细信息，请参阅命名空间网址解析策略。
• extra_context: 将添加到传递给模板的默认上下文数据的上下文数据字典。

password_reset_confirm(request[, uidb64, token, template_name, token_generator, set_password_form, post_reset_redirect, current_app, extra_context])[source]?

为输入新密码展示表单。

URL名称： password_reset_confirm

可选参数：

• uidb64: 用户的id以base 64编码。默认值为 None.
• token: 令牌检查密码是否有效。默认为None。
• template_name: 显示确认密码视图的模板的全名。默认值为registration/password_reset_confirm.html。
• token_generator: 实例的类检查密码。这将默认为default_token_generator，它是django.contrib.auth.tokens.PasswordResetTokenGenerator的一个实例。
• set_password_form: 将用于设置密码的表单。默认为SetPasswordForm
• post_reset_redirect: 重置密码后重定向的网址。默认为None。
• current_app: 指示哪个应用程序包含当前视图的提示。有关详细信息，请参阅命名空间网址解析策略。
• extra_context: 将添加到传递给模板的默认上下文数据的上下文数据字典。

模板上下文：

• form: 用于设置新用户密码的格式（参见上面的set_password_form）。
• validlink: Boolean，如果链接（uidb64和token的组合）有效或未使用，则为True。

password_reset_complete(request[, template_name, current_app, extra_context])[source]?

展示一个视图，它通知用户密码修改成功。

URL名称： password_reset_complete

可选参数：

• template_name: 显示视图的模板的全名。默认为registration/password_reset_complete.html。
• current_app: 指示哪个应用程序包含当前视图的提示。有关详细信息，请参阅命名空间网址解析策略。
• extra_context: 将添加到传递给模板的默认上下文数据的上下文数据字典。

用户

当渲染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，则不可以访问该模板变量：

权限

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

在{{ perms }} 对象中，单一属性的查找是 User.has_module_perms的代理。如果已登录的用户在foo 应用中拥有任何许可，这个例子会显示 True：

{{ perms.foo }}

二级属性的查找是User.has_perm的代理。如果已登录的用户拥有foo.can_vote的许可，这个示例会显示True：

{{ perms.foo.can_vote }}

所以，你可以用模板的{% if %}语句检查权限：

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

还可以通过{% if in %}语句查询权限。例如：

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