Django 自带一个用户认证系统，这个系统处理用户帐户、组、权限和基于 cookie 的 会话。本文说明这个系统是如何工作的。

API 手册

myuser.groups = [group_list] myuser.groups.add(group, group, ...) myuser.groups.remove(group, group, ...) myuser.groups.clear() myuser.user_permissions = [permission_list] myuser.user_permissions.add(permission, permission, ...) myuser.user_permissions.remove(permission, permission, ...) myuser.user_permissions.clear() 

基本用法

>>> from django.contrib.auth.models import User >>> user = User.objects.create_user(‘john‘, ‘lennon@thebeatles.com‘, ‘johnpassword‘) # 到这里， user 是一个已存入数据库的 User 对象。如果要改变其它字段可以继续 # 改变这个对象的属性。 >>> user.is_staff = True >>> user.save() 

>>> from django.contrib.auth.models import User >>> u = User.objects.get(username__exact=‘john‘) >>> u.set_password(‘new password‘) >>> u.save() 

密码

User 对象的 password 属性是一个如下格式的字符串:

hashtype$salt$hash

由哈希类型、盐值和哈希值组成，用美元符合分隔。

哈希类型可以是 sha1 （缺省值）、 md5 或 crypt ，表明使用哪种单向 哈希算法来处理密码。盐值是一个随机字符串，用于在哈希过程中加盐。注意 crypt 方法只适用于装有标准 Python crypt 模块的平台下。

密码例子:

sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4

set_password() 方法和 check_password() 函数用于设置和检查 密码。

以前版本的 Django ，如 0.90 版，只是简单使用 MD5 哈希，并且不使用盐值。为了向后 兼容，这些密码还是被支持的，指定用户的密码在第一次正常使用 check_password() 后，会自动转换为新的 形式。

匿名用户

django.contrib.auth.models.AnonymousUser 是一个 django.contrib.auth.models.User 接口实现的类，区别如下：

• id 总是 None 。
• is_staff 和 is_superuser 都总是 False 。
• is_active 总是 False 。
• groups 和 user_permissions 都总是空的。
• is_anonymous() 返回 True ， 而不是 False 。
• is_authenticated() 返回 False ，而不是 True 。
• set_password() 、 check_password() 、 save() 、 delete() 、 set_groups() 和set_permissions() 引发 NotImplementedError 。

在实践中，你一般不会自己使用 AnonymousUser 对象，但是 Web 请求会使用， 在下节会详述。

创建超级用户

在 INSTALLED_APPS 中添加 ‘django.contrib.auth‘ 后第一次运行 manage.py syncdb 会提示你创建一个超级用户。如何在以后单独 创建可以使用以下命令行工具:

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

运行后会提供输入密码。输入密码后，用户会被立即创建。如果没有写明 --username 或 --email ，会提示你输入这两个值。

如果你使用的是老版本的 Django ，则可以使用如下命令:

python /path/to/django/contrib/auth/create_superuser.py 

...这里的 /path/to 是你系统中 Django 代码所在路径。推荐使用 manage.py 命令，因为它为你提供了恰当的路径和环境。

为用户储存额外的信息

如果要储存用户相关的额外信息， Django 提供了一个方法来定义一个站点相关模型，称 之为“用户概况（ user profile ）”。

具体实现的方式是定义一个用于储存额外信息或附加方法的模型，同时在模型中添加一个 OneToOneField 关联到 User模型。这样就可以保证每个 User 只能创建唯一的模型实例。

为了使定义的模型成为站点的用户概况模型，必须有 AUTH_PROFILE_MODULE 设置中定义一个包含以下条目的字符串，条目间以点号分隔：

1. 使用用户概况模型的应用名称（大小写敏感）。亦即用来创建应用而传递给 manage.py startapp 的名称。
2. 模型的名称（大小写不敏感）。

例如，如果用户概况模型名称为 UserProfile 且定义在一个名称为 accounts 的 应用中，那么正确的设置是:

AUTH_PROFILE_MODULE = ‘accounts.UserProfile‘ 

当一个用户概况模型定义好并按上述方法指定之后，每个 User 对象就会有一个 get_profile() 方法，这个方法可以返回 与 User 相关联的用户概况模型。

如果用户概况不存在，则 get_profile() 方法不会创建用户概况。你必需在用户模型中为django.db.models.signals.post_save 信号注册一个句柄，并且在句柄中，如果 created=True ，则创建相关的用户概况。

更多信息，参见 Django 之书第十二章.

if request.user.is_authenticated():
    # 做一些已登录用户的事。
else:
    # 做一些匿名用户的事。

如何登录一个用户

Django 在 django.contrib.auth 模型中提供两个函数: authenticate() 和 login() .

authenticate() 用于验证指定用户的用户名和 密码。这个函数有两个关键字参数， username 和 password ，如果密码与 用户匹配则返回一个 User 对象。否则返回 None 。例如:

from django.contrib.auth import authenticate user = authenticate(username=‘john‘, password=‘secret‘) if user is not None: if user.is_active: print "你提供了一个正确的用户名和密码！" else: print "帐户已禁用！" else: print "用户名或密码不正确。" 

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(username=username, password=password)
    if user is not None:
        if user.is_active:
            login(request, user)
            # 重定向到一个登录成功页面。
        else:
            # 返回一个“帐户已禁用”错误信息。
    else:
        # 返回一个“非法用户名或密码”错误信息。

手动检查一个用户的密码

如果要通过比较明文密码和数据库中的哈希密码来手动认证用户，可以使用便捷的django.contrib.auth.models.check_password() 函数。它带有两个参数：要 比较的明文密码和被比较的数据库中用户 密码 字段的完整值。如果匹配则返回 True ，否则返回 False 。

如何登出一个用户

在视图中可以使用 django.contrib.auth.logout() 来登出通过 django.contrib.auth.login() 登录的用户。它带有一个 HttpRequest 对象，没有返回值。 例如:

from django.contrib.auth import logout def logout_view(request): logout(request) # 重定向到一个登出成功页面。 

注意当用户没有登录时，调用 logout() 函数不会 引发任何错误。

当调用 logout() 时，当前请求的会话数据会清空。 这是为了防止另一个用户使用同一个浏览器登录时会使用到前一个用户的会话数据。 如果要在用户登出后有会话中储存一些数据，那么得在 django.contrib.auth.logout() 之后 储存。

登录和登出信号

当一个用户登录或登出时认证框架使用两个用于通知的 信号 。

成功登录时所发的信号。

这个信号的参数：

调用登出方法时发的信号。

控制非登录用户的页面权限

from django.http import HttpResponseRedirect def my_view(request): if not request.user.is_authenticated(): return HttpResponseRedirect(‘/login/?next=%s‘ % request.path) # ... 

def my_view(request): if not request.user.is_authenticated(): return render_to_response(‘myapp/login_error.html‘) # ... 

from django.contrib.auth.decorators import login_required @login_required def my_view(request): ... 

from django.contrib.auth.decorators import login_required @login_required(redirect_field_name=‘my_redirect_field‘) def my_view(request): ... 

from django.contrib.auth.decorators import login_required @login_required(login_url=‘/accounts/login/‘) def my_view(request): ... 

(r‘^accounts/login/$‘, ‘django.contrib.auth.views.login‘), 

(r‘^accounts/login/$‘, ‘django.contrib.auth.views.login‘, {‘template_name‘: ‘myapp/login.html‘}), 

{% extends "base.html" %} {% load url from future %} {% block content %} {% if form.errors %} 

 {% endif %}  method="post" action="{% url ‘django.contrib.auth.views.login‘ %}"> {% csrf_token %} 

  type="submit" value=http://www.mamicode.com/"login" />  type="hidden" name="next" value=http://www.mamicode.com/"{{ next }}" />  {% endblock %} 

其他内建视图

除了 login() 视图外，认证系统还有其他一些有用的内建视图。这些 视图都在 django.contrib.auth.views 中:

登出用户。

可选参数：

• next_page: 登出后转向的 URL 。
• template_name: 登出后要显示的模板的全名。如果没有提供这个参数， 缺省为registration/logged_out.html 。
• redirect_field_name: 包含登出后转向的 URL 的 GET 字段的名称。 如果给出则覆盖 next_page 。

模板语境：

• title: 本地化的 "Logged out" 字符串。

登出用户，并重定向到登录页面。

可选参数：

• login_url: 要重定向到的登录页面的 URL 。如果没有给出这个参数，则 缺省为 settings.LOGIN_URL 。

允许一个用户更改自己的密码。

可选参数：

• template_name: 显示用户更改页面的模板全名。如果没有给出，则缺省为registration/password_change_form.html 。

• post_change_redirect: 成功更改密码后要转向到的 URL 。

• New in Django 1.2: Please, see the release notes

  password_change_form: 一个自定义的“更改密码”的表单，必须接受一个 user 关键字参数。这个表单负责改变用户密码。

模板语境：

• form: 密码变更表单。

用户变更密码后要显示的页面。

可选参数：

• template_name: 模板的全名。缺省为 registration/password_change_done.html 。

生成一个用于用户重置密码的一次性链接，并通过电子邮件发送这个链接。

可选参数：

• template_name: 用于显示密码重置页面的模板全名。如果没有给出，则 缺省为registration/password_reset_form.html 。
• email_template_name: 用于生成包含新密码的电子邮件的页面的模板 全名。如果没有给出，则缺省为registration/password_reset_email.html 。
• password_reset_form: 用于设置密码的表单。缺省为 PasswordResetForm 。
• token_generator: 检查密码的类的实例。缺省为 default_token_generator ，它是一个django.contrib.auth.tokens.PasswordResetTokenGenerator 的实例。
• post_reset_redirect: 成功变更密码后要转向的 URL 。
• from_email: 一个可用的电子邮件地址。缺省情况下 Django 使用 DEFAULT_FROM_EMAIL 。

模板语境：

• form: 用于重置密码的表单。

重置密码显示的页面。

可选参数：

• template_name: 模板的全名。缺省为 registration/password_reset_done.html 。

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

必选参数：

• next: 成功登录后到转向的 URL 。

可选参数：

• login_url: 登录页面的 URL 。缺省为 settings.LOGIN_URL 。
• redirect_field_name: 包含登录后要转向的 URL 的 GET 字段的 名称。如果给出则覆盖 next 。

给出一个输入新密码的表单。

可选参数：

• uidb36: 用户的 id 以 base 36 方式编码。缺省为 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: 重置密码的要转向的 URL 。缺省为 None 。

展现一个通知用户密码已成功变更的视图。

可选参数：

• template_name: 显示视图的模板的全名。缺省为 registration/password_reset_complete.html 。

内建表单

如果你不想使用内建的视图，但是想自己写表单，那么认证系统在 django.contrib.auth.forms 中提供了一些内建的表单：

在管理接口中改变用户密码的表单。

登录表单。

变更密码表单。

生成重置密码链接并通过电子邮件发送链接的表单。

不需要输入旧密码就可以变更用户密码的表单。

在管理接口中变更用户信息和权限的表单。

创建新用户的表单。

通过测试来限制页面操作

要基于一定的权限或测试来限制页面的操作，其本质上和上一节的内容相同。

最简单的方式是在社图中直接在 request.user 上直接运行你的测试。例如，这个视图调试用户是否 已登录并拥有polls.can_vote 权限:

def my_view(request): if not request.user.has_perm(‘polls.can_vote‘): return HttpResponse("在这个选举中你不能投票。") # ... 

作为一个捷径，你可使用方便的 user_passes_test 装饰件:

from django.contrib.auth.decorators import user_passes_test @user_passes_test(lambda u: u.has_perm(‘polls.can_vote‘)) def my_view(request): ... 

我们使用这个特定的测试作为一个相关的简单的例子。然而，如果你只要测试一个 用户是否有一个权限，那么你可以使用 permission_required() 装饰件，稍后 会谈到这个装饰件。

user_passes_test() 有一个必选参数： 带有一个 User 对象的可调用的函数，并且 如果用户被允许查看页面时返回 True 。注意 user_passes_test() 不自动检查 User 是否是匿名用户。

user_passes_test() 有一个可选的 login_url 参数，这个参数让你指定登录页面的 URL （缺省为settings.LOGIN_URL ）。

例如:

from django.contrib.auth.decorators import user_passes_test @user_passes_test(lambda u: u.has_perm(‘polls.can_vote‘), login_url=‘/login/‘) def my_view(request): ... 

from django.contrib.auth.decorators import permission_required def my_view(request): ... my_view = permission_required(‘polls.can_vote‘)(my_view) 

from django.contrib.auth.decorators import permission_required def my_view(request): ... my_view = permission_required(‘polls.can_vote‘, login_url=‘/loginpage/‘)(my_view) 

限制通用视图的操作

要限制一个 通用视图 操作，可以写一个视图的薄包装， 然后把你的 URLconf 指向薄包装而不是通用视图本身。例如:

from django.views.generic.date_based import object_detail @login_required def limited_object_detail(*args, **kwargs): return object_detail(*args, **kwargs) 

缺省权限

当 django.contrib.auth 存在于你的 INSTALLED_APPS 设置中时，会 确保你安装的应用中每个 Django 模型在三个缺省的权限——增加、变更和删除。

当你运行 manage.py syncdb 时这些权限会被创建。在向 INSTALLED_APPS 增加 django.contrib.auth 后第一次运行 syncdb 时，会为以前已安装的模型和正在安装的模型创建缺省权限。以后每次运行 manage.py syncdb 都会为所有模型创建缺省权限。

假设你的应用有一个名为 foo 的 app_label 和一个名为 Bar 的模型，要测试基本的权限可以这样:

* add: ``user.has_perm(‘foo.add_bar‘)``
* change: ``user.has_perm(‘foo.change_bar‘)``
* delete: ``user.has_perm(‘foo.delete_bar‘)``

自定义权限

使用 权限 模型元属性 可以创建自定义权限。

下例中的 Task 模型创建了三个自定义权限:

class Task(models.Model): ... class Meta: permissions = ( ("can_view", "Can see available tasks"), ("can_change_status", "Can change the status of tasks"), ("can_close", "Can remove a task by setting its status as closed"), ) 

当运行 manage.py syncdb 时以上代码只做了一件事：创建了三个 额外的权限。当用户尝试操作应用提供的功能（查看任务、改变任务状态和关闭任务） 时，你的代码必须负责检查权限的值。

API 手册

和用户一样，权限也在 django/contrib/auth/models.py Django 模型中实现。

技术细节

在技术细节上，这些变量只有当你使用 RequestContext ， 并且 你的TEMPLATE_CONTEXT_PROCESSORS 设置中包含"django.contrib.auth.context_processors.auth" 时才在模板环境中可用，这是 缺省 情况。更多见容，详见 请求环境文档 。

用户

当渲染一个模板 RequestContext 时，当前已登录 的用户（要么是一个 User 实例，要么是一个 AnonymousUser 实例）被储存在模板变量 {{ user }} 中：

{% if user.is_authenticated %} 

 {% else %} 

 {% endif %} 

如果一个 RequestContext 未使用则这个模板环境变量不可用。

权限

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

在 {{ perms }} 对象中，单个属性的查找是 User.has_module_perms 方法的一个代理。

如果已登录用户在 foo 应用中有权限，那么以下例子会显示 True

{{ perms.foo }}

二维属性查找是 User.has_perm 方法的一个代理。如果已登录用户有 foo.can_vote 权限，那么以下例子会显示 True

{{ perms.foo.can_vote }}

然而，你可以在模板 {% if %} 语句中检查权限：

{% if perms.foo %} 

 {% if perms.foo.can_vote %} 

 {% endif %} {% if perms.foo.can_drive %} 

 {% endif %} {% else %} 

 {% endif %} 

指定认证后端

在后台， Django 维护着一个用于认证的“认证后端”列表。当象前文 如何登录一个用户 一节中提到的，使用django.contrib.auth.authenticate() 时， Django 会尝试列表中的所有 后端。如果第一个不行，则尝试第二个，以此类推，直到最后一个。

认证后端的列表中 AUTHENTICATION_BACKENDS 设置中定义。设置内容应当是 一个指向可以用于认证的 Python 类的路径名的元组。这些类可以放在 Python 路径下的 任意位置。

缺省情况下， AUTHENTICATION_BACKENDS 被设置为:

(‘django.contrib.auth.backends.ModelBackend‘,) 

这是检查 Django 用户数据库的基本认证方案。

AUTHENTICATION_BACKENDS 的顺序是重要的，所以如果相同的用户名和密码在 多个后端中同时存在， Django 会在第一个匹配的地方停止。

编写一个认证后端

一个认证后端是一个执行两个方法的类： get_user(user_id) 和 authenticate(**credentials) 。

get_user 方法需要一个 user_id （可以是一个用户名、数据库 ID 或其他 东东），并且返回一个 用户 对象。

authenticate 方法有一个证书关键字参数。多数情况下看上去如下:

class MyBackend:
    def authenticate(self, username=None, password=None):
        # 检查用户名和密码并返回一个用户。

但是也可以认证一个标志，象下面这样:

class MyBackend:
    def authenticate(self, token=None):
        # 检查标志并返回一个用户。

不管怎样， authenticate 应当检查得到的材料。当材料有效时，返回一个符合条件 的 用户 对象，否则返回 None 。

Django 管理系统与本文开头所谈的 Django 用户 对象是紧密关联的。目前，最好的 办法是为你的认证后端中存在的每个用户创建一个 Django 用户 对象（例如，在你的 LDAP 目录中，你的 SQL 数据库中等等）。你要么写一个脚本，要么你的 认证 方法 在第一次用户登录时来创建 用户 对象。

以下是一个后端举例，它检查 settings.py 文件中定义的用户名和密码，并且在用户 第一次登录时创建一个 用户 对象:

from django.conf import settings from django.contrib.auth.models import User, check_password class SettingsBackend: """  Authenticate against the settings ADMIN_LOGIN and ADMIN_PASSWORD.  Use the login name, and a hash of the password. For example:  ADMIN_LOGIN = ‘admin‘  ADMIN_PASSWORD = ‘sha1$4e987$afbcf42e21bd417fb71db8c66b321e9fc33051de‘  """ supports_object_permissions = False supports_anonymous_user = False supports_inactive_user = False def authenticate(self, username=None, password=None): login_valid = (settings.ADMIN_LOGIN == username) pwd_valid = check_password(password, settings.ADMIN_PASSWORD) if login_valid and pwd_valid: try: user = User.objects.get(username=username) except User.DoesNotExist: # Create a new user. Note that we can set password # to anything, because it won‘t be checked; the password # from settings.py will. user = User(username=username, password=‘get from settings.py‘) user.is_staff = True user.is_superuser = True user.save() return user return None def get_user(self, user_id): try: return User.objects.get(pk=user_id) except User.DoesNotExist: return None 

在自定义后端中处理认证

自定义后端可以提供自己的权限。

用户模型会把权限查找函数 （:meth:~django.contrib.auth.models.User.get_group_permissions() 、get_all_permissions() 、 has_perm() 和 has_module_perms() ）委托给执行这些 函数的任何一个后端。

提供给用户的权限将会是所有后端返回的权限的超集。即 Django 会把任一个后端的权限 都提供给用户。

上面的简单的后端可以相当简单的执行神奇的权限管理:

class SettingsBackend: # ... def has_perm(self, user_obj, perm): if user_obj.username == settings.ADMIN_LOGIN: return True else: return False 

上例中通过验证的用户得到了所有权限。注意，后端认证函数都把用户对象作为一个参数 并且接受与django.contrib.auth.models.User 同样的参数。

一个完整的认证实现参见 django/contrib/auth/backends.py 。通常情况下这是缺省 后端，查询的是 auth_permission表。

处理对象权限

Django 的权限框架支持对象权限。但是不是在框架的核心中实现的，这就意味着在检查 对象权限时总是返回 False 或一个空列表（取决于如何检查）。

要在你自己的 认证后端 中使用对象权限，只要允许向权限 传递一个 obj 参数并且设置supports_object_permissions 类属性为 True 。

在 Django 1.2 中一个不存在的 supports_object_permissions 属性会引发一个隐藏 的PendingDeprecationWarning 。在 Django 1.3 中，这个警告会升级为一个 DeprecationWarning ，非常显眼。附加的 supports_object_permissions 会被 设置为 False 。 Django 1.4 会假设每一个后端都支持对象权限并且不会检查 supports_object_permissions 是否存在，意即不支持 obj 作为一个参数就会 引发一个 TypeError 。