{% raw %}

使用Django认证系统

这篇文档解释默认配置下Django认证系统的使用。这些配置已经逐步可以满足大部分常见项目对的需要，可以处理范围非常广泛的任务，且具有一套细致的密码和权限实现。对于需要与默认配置不同需求的项目，Django支持扩展和自定义认证。

Django的认证同时提供认证和授权，并通常统一称为认证系统，因为这些功能某些地方是耦合的。

User对象

User对象是认证系统的核心。它们通常表示与你的站点进行交互的用户，并用于启用限制访问、注册用户信息和关联内容给创建者等。在Django的认证框架中只存在一种类型的用户，因此诸如'superusers'或管理员'staff'用户只是具有特殊属性集的user对象，而不是不同类型的user对象。

默认user的基本属性有：

完整的参考请参阅full API documentation，该文档更偏重特定的任务。

创建users

创建users最直接的方法是使用create_user()辅助函数：

  1. >>> from django.contrib.auth.models import User
  2. >>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword')
  4. # At this point, user is a User object that has already been saved
  5. # to the database. You can continue to change its attributes
  6. # if you want to change other fields.
  7. >>> user.last_name = 'Lennon'
  8. >>> user.save()

如果你已经安装了Django admin，你也可以间接地创建users.

创建superusers

使用createsuperuser命令创建superusers：

  1. $ python manage.py createsuperuser --username=joe --email=joe@example.com

将会提示你输入一个密码。在你输入一个密码后，该user将会立即创建。如果不带--username和--email选项，将会提示你输入这些值。

修改密码

Django不会在user模型上存储原始的（明文）密码，而只是一个哈希（完整的细节参见文档：密码是如何管理的）。因为这个原因，不要尝试直接操作user的password属性。这也是为什么创建一个user时要使用辅助函数。

若要修改一个用户的密码，你有几种选择：

manage.py changepassword *username*提供一种从命令行修改User密码的方法。它提示你修改一个给定user的密码，你必须输入两次。如果它们匹配，新的密码将会立即修改。如果你没有提供user，命令行将尝试修改与当前系统用户匹配的用户名的密码。

你也可以通过程序修改密码，使用set_password()：

  1. >>> from django.contrib.auth.models import User
  2. >>> u = User.objects.get(username='john')
  3. >>> u.set_password('new password')
  4. >>> u.save()

如果你安装了Django admin，你还可以在认证系统的admin页面修改user的密码。

Django还提供views和forms用于允许user修改他们自己密码。

New in Django 1.7.

如果启用了SessionAuthenticationMiddleware，修改user的密码将会登出他们所有的会话。 详细信息请参阅密码修改后会话失效。

认证Users

authenticate(**credentials)[source]

认证一个给定用户名和密码，请使用authenticate()。它以关键字参数形式接收凭证，对于默认的配置它是username和password，如果密码对于给定的用户名有效它将返回一个User对象。如果密码无效，authenticate()返回None。例子：

  1. from django.contrib.auth import authenticate
  2. user = authenticate(username='john', password='secret')
  3. if user is not None:
  4.     # the password verified for the user
  5.     if user.is_active:
  6.         print()
  7.     else:
  8.         print()
  9. else:
  10.     # the authentication system was unable to verify the username and password
  11.     print()

注

这是认证一系列凭证的低级的方法；例如，它被RemoteUserMiddleware使用。除非你正在编写你自己的认证系统，你可能不会使用到它。当然如果你在寻找一种登录user的方法，请参见login_required()装饰器。

权限和授权

Django从开始就带有一个简单的权限系统。它提供一种分配权限给特定的用户和用户组的方法。

它被Django的admin站点使用，但欢迎你在你自己的代码中使用。

Django admin 站点使用如下的权限：

  • 查看”add”表单并添加一个只限具有该类型对象的“add”权限的用户对象。
  • 查看修改列表、查看“change”表单以及修改一个只限具有该类型对象的“change”权限的用户对象。
  • 删除一个只限具有该类型对象的“delete”权限的用户对象。

权限不但可以根据每个对象的类型，而且可以根据特定的对象实例设置。通过使用ModelAdmin类提供的has_add_permission()、has_change_permission()和has_delete_permission()方法，可以针对相同类型的不同对象实例自定义权限。

User对象具有两个多对多的字段：groups和user_permissions。User对象可以用和其它Django 模型一样的方式访问它们相关的对象：

  1. myuser.groups = [group_list]
  2. myuser.groups.add(group, group, ...)
  3. myuser.groups.remove(group, group, ...)
  4. myuser.groups.clear()
  5. myuser.user_permissions = [permission_list]
  6. myuser.user_permissions.add(permission, permission, ...)
  7. myuser.user_permissions.remove(permission, permission, ...)
  8. myuser.user_permissions.clear()

默认的权限

当django.contrib.auth在你的INSTALLED_APPS设置中列出时，它将确保为你安装的应用中的每个Django模型创建3个默认的权限 – add、change和delete。

这些权限将在你运行manage.py migrate时创建；在添加django.contrib.auth到INSTALLED_APPS中之后，当你第一次运行migrate时，将会为之前安装的模型创建默认的权限，包括与其同时正在安装的新的模型。之后，每当你运行manage.py migrate时，它都将为新的模型创建默认的权限。

假设你有个应用的app_label是foo和一个名为Bar的模型，要测试基本的权限，你应该使用：

  • add: user.has_perm('foo.add_bar')
  • change: user.has_perm('foo.change_bar')
  • delete: user.has_perm('foo.delete_bar')

很少直接访问Permission模型。

组

django.contrib.auth.models.Group模型是用户分类的一种通用的方式，通过这种方式你可以应用权限或其它标签到这些用户。一个用户可以属于任意多个组。

组中某个用户自动具有赋给那个组的权限。例如，如果组Site editors具有权限 can_edit_home_page，那么该组中的任何用户都具有该权限。

出权限之外，组还是给用户分类的一种方便的方法以给他们某些标签或扩展的功能。例如，你可以创建一个组'Special users'，然后你可以这样写代码，给他们访问你的站点仅限会员的部分，或者给他们发仅限于会员的邮件。

用程序创建权限

虽然custom permissions可以定义在Meta类中，你还可以直接创建权限。例如，你可以为myapp中的BlogPost 创建can_publish权限：

  1. from myapp.models import BlogPost
  2. from django.contrib.auth.models import Group, Permission
  3. from django.contrib.contenttypes.models import ContentType
  5. content_type = ContentType.objects.get_for_model(BlogPost)
  6. permission = Permission.objects.create(codename='can_publish',
  7.                                        name='Can Publish Posts',
  8.                                        content_type=content_type)

然后该权限可以通过user_permissions属性分配给一个User，或者通过permissions属性分配给Group。

权限的缓存

ModelBackend在第一次需要访问User对象来检查权限时会缓存它们的权限。这对于请求-响应循环还是比较好的，因为在权限添加进来之后并不会立即检查（例如在admin中）。如果你正在添加权限并需要立即检查它们，例如在一个测试或视图中，最简单的解决办法是从数据库中重新获取User。 例如：

  1. from django.contrib.auth.models import Permission, User
  2. from django.shortcuts import get_object_or_404
  4. def user_gains_perms(request, user_id):
  5.     user = get_object_or_404(User, pk=user_id)
  6.     # any permission check will cache the current set of permissions
  7.     user.has_perm('myapp.change_bar')
  9.     permission = Permission.objects.get(codename='change_bar')
  10.     user.user_permissions.add(permission)
  12.     # Checking the cached permission set
  13.     user.has_perm('myapp.change_bar')  # False
  15.     # Request new instance of User
  16.     user = get_object_or_404(User, pk=user_id)
  18.     # Permission cache is repopulated from the database
  19.     user.has_perm('myapp.change_bar')  # True
  21.     ...

Web请求中的认证

Django使用会话和中间件来拦截request 对象到认证系统中。

它们在每个请求上提供一个request.user属性，表示当前的用户。如果当前的用户没有登入，该属性将设置成AnonymousUser的一个实例，否则它将是User的实例。

你可以通过is_authenticated()区分它们，像这样：

  1. if request.user.is_authenticated():
  2.     # Do something for authenticated users.
  3.     ...
  4. else:
  5.     # Do something for anonymous users.
  6.     ...

如何登入一个用户

如果你有一个认证了的用户，你想把它附带到当前的会话中 - 这可以通过login()函数完成。

login()[source]

从视图中登入一个用户，请使用login()。它接受一个HttpRequest对象和一个User对象。login()使用Django的会话框架保存用户的ID在会话中。

注意任何在匿名会话中设置的数据都会在用户登入后的会话中都会记住。

这个例子展示你可能如何使用authenticate()和 login()：

  1. from django.contrib.auth import authenticate, login
  3. def my_view(request):
  4.     username = request.POST['username']
  5.     password = request.POST['password']
  6.     user = authenticate(username=username, password=password)
  7.     if user is not None:
  8.         if user.is_active:
  9.             login(request, user)
  10.             # Redirect to a success page.
  11.         else:
  12.             # Return a 'disabled account' error message
  13.             ...
  14.     else:
  15.         # Return an 'invalid login' error message.
  16.         ...

先调用authenticate()：

当你是手工登入一个用户时，你必须在调用login()之前通过authenticate()成功地认证该用户。authenticate()在User上设置一个属性标识哪种认证后台成功认证了该用户（细节参见后台的文档），且该信息在后面登录的过程中是需要的。如果你视图登入一个直接从数据库中取出的用户，将会抛出一个错误。

如何登出一个用户

logout()[source]

若要登出一个已经通过django.contrib.auth.login()登入的用户，可以在你的视图中使用django.contrib.auth.logout()。 它接收一个HttpRequest对象且没有返回值。例如：

  1. from django.contrib.auth import logout
  3. def logout_view(request):
  4.     logout(request)
  5.     # Redirect to a success page.

注意，即使用户没有登入logout()也不会抛出任何错误。

当你调用logout()时，当前请求的会话数据将被完全清除。所有存在的数据都将清除。这是为了防止另外一个人使用相同的Web浏览器登入并访问前一个用户的会话数据。如果你想在用户登出之后>可以立即访问放入会话中的数据，请在调用django.contrib.auth.logout()之后放入。

限制访问给登陆后的用户

原始的方法

限制页面访问的简单、原始的方法是检查request.user.is_authenticated()并重定向到一个登陆页面：

  1. from django.conf import settings
  2. from django.shortcuts import redirect
  4. def my_view(request):
  5.     if not request.user.is_authenticated():
  6.         return redirect('%s?next=%s' % (settings.LOGIN_URL, request.path))
  7.     # ...

…或者显示一个错误信息：

  1. from django.shortcuts import render
  3. def my_view(request):
  4.     if not request.user.is_authenticated():
  5.         return render(request, 'myapp/login_error.html')
  6.     # ...

login_required 装饰器

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

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

  1. from django.contrib.auth.decorators import login_required
  3. @login_required
  4. def my_view(request):
  5.     ...

login_required()完成下面的事情：

  • 如果用户没有登入，则重定向到settings.LOGIN_URL，并传递当前查询字符串中的绝对路径。例如：/accounts/login/?next=/polls/3/。
  • 如果用户已经登入，则正常执行视图。视图的代码可以安全地假设用户已经登入。

默认情况下，在成功认证后用户应该被重定向的路径存储在查询字符串的一个叫做)带有一个可选的redirect_field_name`参数：

  1. from django.contrib.auth.decorators import login_required
  3. @login_required(redirect_field_name='my_redirect_field')
  4. def my_view(request):
  5.     ...

注意，如果你提供一个值给redirect_field_name，你非常可能同时需要自定义你的登录模板，因为存储重定向路径的模板上下文变量将使用redirect_field_name值作为它的键，而不是默认的"next"。

login_required()还带有一个可选的login_url参数。例如：

  1. from django.contrib.auth.decorators import login_required
  3. @login_required(login_url='/accounts/login/')
  4. def my_view(request):
  5.     ...

注意，如果你没有指定login_url参数，你需要确保settings.LOGIN_URL并且你的登录视图正确关联。例如，使用默认值，可以添加下面几行到你的URLconf中：

  1. from django.contrib.auth import views as auth_views
  3. url(r'^accounts/login/$', auth_views.login),

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

注

login_required装饰器不检查user的is_active标志位。

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

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

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

  1. from django.shortcuts import redirect
  3. def my_view(request):
  4.     if not request.user.email.endswith('@example.com'):
  5.         return redirect('/login/?next=%s' % request.path)
  6.     # ...

user_passes_test(func[, login_url=None, redirect_field_name=REDIRECT_FIELD_NAME])[source]

你可以用方便的 user_passes_test 装饰器，当回掉函数返回 False 时会执行一个重定向操作：

  1. from django.contrib.auth.decorators import user_passes_test
  3. def email_check(user):
  4.     return user.email.endswith('@example.com')
  6. @user_passes_test(email_check)
  7. def my_view(request):
  8.     ...

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 的非登录页面时。

例如：

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

permission_required 装饰器

permission_required(perm[, login_url=None, raise_exception=False])[source]

检查一个用户是否有指定的权限是相对常见的需求。因此，Django 提供了一个快捷方式： permission_required() 装饰器：

  1. from django.contrib.auth.decorators import permission_required
  3. @permission_required('polls.can_vote')
  4. def my_view(request):
  5.     ...

has_perm() 方法, 权限名称采用如下方法 "<app label>.<permission codename>" (例如 polls.can_vote 表示在 polls 应用下一个模块的权限。

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

  1. from django.contrib.auth.decorators import permission_required
  3. @permission_required('polls.can_vote', login_url='/loginpage/')
  4. def my_view(request):
  5.     ...

在 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。

密码更改后的会话失效

New in Django 1.7.

警告

这种保护只在MIDDLEWARE_CLASSES中SessionAuthenticationMiddleware开启的情况下应用。如果settings.py由Django ≥ 1.7. 的startproject生成，它会被包含进来。

在Django 2.0中，会话验证会变成强制性的， 无论是否开启了SessionAuthenticationMiddleware 。 如果你拥有一个1.7之前的项目，或者使用不包含SessionAuthenticationMiddleware的模板生成的项目，考虑在阅读下面的升级说明之后开启它。

如果你的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)

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

  1. from django.contrib.auth import update_session_auth_hash
  3. def password_change(request):
  4.     if request.method == 'POST':
  5.         form = PasswordChangeForm(user=request.user, data=request.POST)
  6.         if form.is_valid():
  7.             form.save()
  8.             update_session_auth_hash(request, form.user)
  9.     else:
  10.         ...

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

注意

虽然get_session_auth_hash()给予SECRET_KEY，使用新的私钥升级你的站点会使所有现有会话失效。

认证的视图

Django提供一些视图，你可以用来处理登录、登出和密码管理。它们使用stock auth 表单，但你也可以传递你自己的表单。

Django没有为认证视图提供默认的模板。你应该为你想要使用的视图创建自己的模板。模板的上下文定义在每个视图中，参见所有的认证视图.

使用视图

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

  1. urlpatterns = [
  2.     url('^', include('django.contrib.auth.urls'))
  3. ]

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

  1. ^login/$ [name='login']
  2. ^logout/$ [name='logout']
  3. ^password_change/$ [name='password_change']
  4. ^password_change/done/$ [name='password_change_done']
  5. ^password_reset/$ [name='password_reset']
  6. ^password_reset/done/$ [name='password_reset_done']
  7. ^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']
  8. ^reset/done/$ [name='password_reset_complete']

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

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

  1. urlpatterns = [
  2.     url('^change-password/', 'django.contrib.auth.views.password_change')
  3. ]

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

  1. urlpatterns = [
  2.     url(
  3.         '^change-password/',
  4.         'django.contrib.auth.views.password_change',
  5.         {'template_name': 'change-password.html'}
  6.     )
  7. ]

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

  1. from django.contrib.auth import views
  3. def change_password(request):
  4.     template_response = views.password_change(request)
  5.     # Do something with `template_response`
  6.     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个模板上下文变量：

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

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

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

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

  1. {% extends "base.html" %}
  3. {% block content %}
  5. {% if form.errors %}
  6. <p>Your username and password didn't match. Please try again.</p>
  7. {% endif %}
  9. <form method="post" action="{% url 'django.contrib.auth.views.login' %}">
  10. {% csrf_token %}
  11. <table>
  12. <tr>
  13.     <td>{{ form.username.label_tag }}</td>
  14.     <td>{{ form.username }}</td>
  15. </tr>
  16. <tr>
  17.     <td>{{ form.password.label_tag }}</td>
  18.     <td>{{ form.password }}</td>
  19. </tr>
  20. </table>
  22. <input type="submit" value="login" />
  23. <input type="hidden" name="next" value="{{ next }}" />
  24. </form>
  26. {% 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: The full name of a template to use for
    displaying the password reset form. Defaults to
    registration/password_reset_form.html if not supplied.
  • 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.
  • password_reset_form: Form that will be used to get the email of
    the user to reset the password for. Defaults to
    {{s.379}}.
  • 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.
  • post_reset_redirect: 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.
  • current_app: A hint indicating which application contains the current
    view. See the {{s.385}} for more information.
  • 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.

New in Django 1.7:

添加了html_email_template_name。

Deprecated since version 1.8: is_admin_site参数已被废弃，将在Django2.0中被移除。

模板上下文：

  • form: The form (see password_reset_form above) for resetting
    the user’s password.

Email模板上下文：

  • email: An alias for user.email
  • user: 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 https
  • uid: The user’s primary key encoded in base 64.
  • token: Token to check that the reset link is valid.

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

  1. Someone asked for password reset for email {{ email }}. Follow the link below:
  2. {{ 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: The full name of a template to use.
    Defaults to registration/password_reset_done.html if not
    supplied.
  • current_app: A hint indicating which application contains the current
    view. See the {{s.393}} for more information.
  • 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, token, template_name, token_generator, set_password_form, post_reset_redirect, current_app, extra_context])[source]

为输入新密码展示表单。

URL名称：password_reset_confirm

可选参数：

  • uidb64: The user’s id encoded in base 64. Defaults to None.
  • token: Token to check that the password is valid. Defaults to
    None.
  • 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.
  • set_password_form: Form that will be used to set the password.
    Defaults to {{s.395}}
  • post_reset_redirect: URL to redirect after the password reset
    done. Defaults to None.
  • current_app: A hint indicating which application contains the current
    view. See the {{s.400}} for more information.
  • 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, current_app, extra_context])[source]

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

URL名称：password_reset_complete

可选参数：

  • template_name: The full name of a template to display the view.
    Defaults to registration/password_reset_complete.html.
  • current_app: A hint indicating which application contains the current
    view. See the {{s.403}} for more information.
  • 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, redirect_field_name])[source]

重定向到登录页面，然后在登入成功后回到另一个URL。

必需的参数：

  • next: The URL to redirect to after a successful login.

可选的参数：

  • login_url: The URL of the login page to redirect to.
    Defaults to {{s.411}} 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.

内建的表单

如果你不想用内建的视图，但是又不想编写针对该功能的表单，认证系统提供了几个内建的表单，位于django.contrib.auth.forms：

注

内建的验证表单对他们处理的用户模型做了特定假设。如果你使用了自定义的用户模型，可能需要为验证系统定义你自己的表单。更多信息请见 使用带有自定义用户模型的内建验证表单的文档。

class AdminPasswordChangeForm[source]

管理界面中使用的表单，用于修改用户密码。

接受user作为第一个参数。

class AuthenticationForm[source]

用于用户登录的表单。

接受request 作为第一个参数，它储存在表单实例中，被子类使用。

confirm_login_allowed(user)[source]

New in Django 1.7.

通常， AuthenticationForm会拒绝 is_active标志是False的用户。你可以使用自定义政策覆盖这一行为，来决定哪些用户可以登录。使用一个继承 AuthenticationForm并覆写confirm_login_allowed方法的自定义表单来实现它。如果提供的用户不能登录，这个方法应该抛出ValidationError异常。

例如，允许所有用户登录，不管“活动”状态如何：

  1. from django.contrib.auth.forms import AuthenticationForm
  3. class AuthenticationFormWithInactiveUsersOkay(AuthenticationForm):
  4.     def confirm_login_allowed(self, user):
  5.         pass

或者只允许一些活动用户登录进来：

  1. class PickyAuthenticationForm(AuthenticationForm):
  2.     def confirm_login_allowed(self, user):
  3.         if not user.is_active:
  4.             raise forms.ValidationError(
  5.                 _(),
  6.                 code='inactive',
  7.             )
  8.         if user.username.startswith('b'):
  9.             raise forms.ValidationError(
  10.                 _(),
  11.                 code='no_b_users',
  12.             )

class PasswordChangeForm[source]

一个表单，允许用户修改他们的密码。

class PasswordResetForm[source]

一个表单，用于生成和通过邮件发送一次性密码重置链接。

send_email(subject_template_name, email_template_name, context, from_email, to_email[, html_email_template_name=None])

New in Django 1.8.

使用参数来发送EmailMultiAlternatives。可以覆盖来自定义邮件如何发送给用户。

Parameters:

  • subject_template_name – the template for the subject.
  • email_template_name – the template for the email body.
  • context – context passed to the subject_template, email_template, and html_email_template (if it is not None).
  • from_email – the sender’s email.
  • to_email – the email of the requester.
  • html_email_template_name – the template for the HTML body; defaults to None, in which case a plain text email is sent.

通常， save() 位于context中，并带有 password_reset() 向它的email上下文传递的一些变量。

class SetPasswordForm[source]

允许用户不输入旧密码修改密码的表单。

class UserChangeForm[source]

用户管理界面中修改用户信息和许可的表单。

class UserCreationForm[source]

用于创建新用户的表单。

模板中的认证数据

当你使用RequestContext时，当前登入的用户和它们的权限在模板上下文中可以访问。

技术细节

技术上讲，这些变量只有在你使用RequestContext并启用了'django.contrib.auth.context_processors.auth'上下文处理器时才可以在模板上下文中访问到。它是默认产生的配置文件。更多信息，参见RequestContext 文档。

用户

当渲染RequestContext模板时，当前登录的用户，可能是User实例或者AnonymousUser实例，会存储在模板变量{{ user }}中：

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

如果使用的不是RequestContext，则不可以访问该模板变量：

权限

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

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

  1. {{ perms.foo }}

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

  1. {{ perms.foo.can_vote }}

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

  1. {% if perms.foo %}
  2.     <p>You have permission to do something in the foo app.</p>
  3.     {% if perms.foo.can_vote %}
  4.         <p>You can vote!</p>
  5.     {% endif %}
  6.     {% if perms.foo.can_drive %}
  7.         <p>You can drive!</p>
  8.     {% endif %}
  9. {% else %}
  10.     <p>You don't have permission to do anything in the foo app.</p>
  11. {% endif %}

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

  1. {% if 'foo' in perms %}
  2.     {% if 'foo.can_vote' in perms %}
  3.         <p>In lookup works, too.</p>
  4.     {% endif %}
  5. {% endif %}

在admin中管理用户

如果django.contrib.admin和django.contrib.auth这两个你都安装了，将可以通过admin方便地查看和管理用户、组和权限。可以像其它任何Django模型一样创建和删除用户。可以创建组，并分配权限给用户和组。admin中还会保存和显示对用户模型编辑的日志。

创建用户

在admin的主页，你应该可以在“Auth”部分看到“Users”链接。“Add user” 页面与标准admin页面不同点在于它要求你在编辑用户的其它字段之前先选择一个用户名和密码。

另请注意：如果你想使得一个用户能够使用Django的admin站点创建其它用户， 你需要给他添加用户和修改用户的权限（例如，”Add user” 和“Change user” 权限）。如果一个账号具有添加用户的权限但是没有权限修改他们，该账号将不能添加用户。为什么呢？因为如果你具有添加用户的权限，你将可以添加超级用户，这些超级用户将可以修改其他用户。所以Django同时要求添加权限和修改权限作为一种轻量的安全措施。

仔细考虑一下你是如何允许用户管理权限的。如果你了一个非超级用户编辑用户的能力，这和给他们超级用户的权限在最终效果上是一样的，因为他们将能够提升他们自己下面的用户的权限。

修改密码

用户密码不会显示在admin上（也不会存储在数据库中），但是会显示 密码存储的细节。 这个信息的显示中包含一条指向修改密码表单的链接，允许管理员修改用户的密码。

译者：Django 文档协作翻译小组，原文：Using the authentication system 。

本文以 CC BY-NC-SA 3.0 协议发布，转载请保留作者署名和文章出处。

Django 文档协作翻译小组人手紧缺，有兴趣的朋友可以加入我们，完全公益性质。交流群：467338606。

{% endraw %}