3.1   API 参考

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

3.2   基本用法

>>> from django.contrib.auth.models import User
>>> user = User.objects.create_user('john', 'lennon@thebeatles.com', 'johnpassword')

# 在这里，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()

3.3   密码

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

hashtype$salt$hash

它们是 hashtype, salt 和 hash, 用一个美元符号来分隔的。

Hashtype是 sha1 (默认) 或 md5 -- 单向加密的方法。Salt 是一个随机字符串用来为密码的原文创建hash。

例如:

sha1$a1976$a36cc8cbf81742a8fb52e221aaeab48ed7f58ab4

User.set_password() 和 User.check_password() 函数负责处理设置和检测这些密码。

在Django先前的版本中, 例如 0.90, 仅使用MD5而不使用salt。 为了向后兼容，这些依然被支持。他们会在第一次使用 check_password() 来成功检测用户密码的时候自动将其 转换为新的格式。

3.4   匿名用户

django.contrib.auth.models.AnonymousUser 是一个类，它实现了 django.contrib.auth.models.User 接口, 有如下的不同点:

• id 总是 None.
• is_anonymous() 返回 True 而不是 False.
• is_authenticated() 返回 False 而不是 True.
• has_perm() 总是返回 False.
• set_password(), check_password(), save(), delete(), set_groups() and set_permissions() 抛出 NotImplementedError 异常.

在实际应用中，你可能并不需要 AnonymousUser 对象。 但是他们被应用到网络请求(Web request)中，这将在下面的章节中讲述。

3.5   创建超级用户

在你将 'django.contrib.auth' 添加到 INSTALLED_APPS 中之后，并且第一次 运行 manage.py syncdb 命令时，它将提示你创建一个超级用户。 但是如果你需要在之后的操作过程中用命令行创建超级用户的话，你可以使用 create_superuser.py 。 命令如下:

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

请确认你已经将 /path/to/ 加入到PYTHON_PATH中。

4.1   如何登录一个用户

Django 在 django.contrib.auth 提供了2个函数: authenticate() 和 login() 。

如果通过给定的用户名和密码做认证，请使用 authenticate() 函数。 他接收2个参数，一个是 username 一个是 password 。 如果认证成功，它返回一个 User 对象。 如果密码无效，它返回一个 None 。 例如:

from django.contrib.auth import authenticate
user = authenticate(username='john', password='secret')
if user is not None:
    print "用户名、密码正确！"
else:
    print "用户名、密码错误！"

在视图中登录一个用户的话，使用 login() 函数。 它接收 HttpRequest 对象和一个 User 对象。 login() 通过Django的session框架把用户的ID保存到session中。 所以，你要确认你已经安装了session中间件。

下面是合用 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:
        login(request, user)
        # 转到成功页面
    else:
        # 返回错误信息

4.2   如何登出用户

要登出使用 django.contrib.auth.login() 登录的用户的话，可以在视图中使用 django.contrib.auth.logout() 。 它接收一个 HttpRequest 参数，没有返回值。 例如:

from django.contrib.auth import logout

def logout_view(request):
    logout(request)
    # 转到成功页面

请注意：如果用户没有登录的话， logout() 也不会抛出任何异常的。

4.3   限制已登录用户的访问

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

def my_view(request):
    # ...
my_view = login_required(my_view)

from django.contrib.auth.decorators import login_required

@login_required
def my_view(request):
    # ...

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

* 如果通过 ``GET`` 方式调用的话, 它显示一个登录表单并通过POST的方式登录。

* 如果通过 ``POST`` 方式调用的话，它试图把用户登录进去。 如果登录成功，
  视图(view)重定向到 ``/accounts/profile/`` (目前是硬性编码的，就是写死的。)。
  如果登录失败，则继续显示登录表单。

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

{% extends "base.html" %}

{% block content %}

{% if form.has_errors %}
<p>用户名和密码不匹配。请重试。</p>
{% endif %}

<form method="post" action=".">
<table>
<tr><td><label for="id_username">用户名:</label></td><td>{{ form.username }}</td></tr>
<tr><td><label for="id_password">密码:</label></td><td>{{ form.password }}</td></tr>
</table>

<input type="submit" value="登录" />
<input type="hidden" name="next" value="{{ next }}" />
</form>

{% endblock %}

4.4   已登录用户通过通行测试(pass test)来限制访问

为了实现基于特定的权限或其他的测试的访问限制，你应该做同上一节一样的基本事情。 To limit access based on certain permissions or some other test, you'd do essentially the same thing as described in the previous section.

简单的方法是在view中直接运行测试 request.user 的代码。 例如，这个view检测并确认用户已经登陆并且拥有 polls.can_vote 的权限。

def my_view(request):
    if not (request.user.is_authenticated() and request.user.has_perm('polls.can_vote')):
        return HttpResponse("你不能投票。")
    # ...

你可以使用 user_passes_test 作为快捷方式

from django.contrib.auth.decorators import user_passes_test

def my_view(request):
    # ...
my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'))(my_view)

Python 2.4的写法

from django.contrib.auth.decorators import user_passes_test

@user_passes_test(lambda u: u.has_perm('polls.can_vote'))
def my_view(request):
    # ...

user_passes_test() 需要一个必须的参数: 一个包含 User 的可调用的对象，如果 用户被允许察看这个页面的话，返回 True 。 注意，如果 User 不是匿名的话， user_passes_test 并不自动监测。

user_passes_test() 需要一个可选的 login_url 参数, 它可以让你指定登录表单 的URL(默认是 /accounts/login/ )。

例子，Python 2.3写法

from django.contrib.auth.decorators import user_passes_test

def my_view(request):
    # ...
my_view = user_passes_test(lambda u: u.has_perm('polls.can_vote'), login_url='/login/')(my_view)

例子，Python 2.4写法

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

4.5   限制访问 generic views

为了限制访问 generic view, 可以为view写一个包装器，并且在URLconf中指定为它。

例如

from django.views.generic.date_based import object_detail

@login_required
def limited_object_detail(*args, **kwargs):
    return object_detail(*args, **kwargs)

5.1   默认权限

3个基本的权限 -- 添加(add)，创建(create)和删除(delete) -- 在创建包含有 class Admin 的Django模型的时候都自动被创建好了。 在表面现象的后面，当你运行 manage.py syncdb 的时候，这些权限被添加到了 auth_permission 数据表中。

请注意，如果你的模型里没有 class Admin 的话，当你运行 manage.py syncdb 的时候 这些权限不会被创建出来。如果你初始化数据库之后还想添加这些权限，可以在模型中加入 class Admin 然后再运行一次 manage.py syncdb 。

5.2   自定义权限

为了给指定的模型自定义权限，可以使用 权限(permissions) 的 model Meta attribute 。

这个例子创建了3个自定义的权限

class USCitizen(models.Model):
    # ...
    class Meta:
        permissions = (
            ("can_drive", "Can drive"),
            ("can_vote", "Can vote in elections"),
            ("can_drink", "Can drink alcohol"),
        )

接下来的事情就是运行 syncdb 来创建这些权限。

5.3   API参考

就像用户对象，权限也是实现自Django的模型 django/contrib/auth/models.py.

6.1   用户(Users)

当前登录的用户，不管是否是匿名的，存储在模版变量 {{ user }} 中。

{% if user.is_authenticated %}
    <p>欢迎, {{ user.username }}。谢谢您的来访。</p>
{% else %}
    <p>欢迎，请登录。</p>
{% endif %}

6.2   权限(Permissions)

当前登录用户的权限存储在模版变量 {{ perms }} 中。 他是 django.core.context_processors.PermWrapper 的实例。

在 {{ perms }} 对象中，单个属性的查找是使用 User.has_module_perms 的。 下面这个例子中，如果用户对 foo 这个app有任何权限的话，它就返回True。

{{ perms.foo }}

二级属性查找是使用 User.has_perm 。 下面这个例子中，如果用户有 foo.can_vote 权限的话，它就返回True。

{{ perms.foo.can_vote }}

因此，你可以在模板中用 {% if %} 语句来判断权限

{% if perms.foo %}
    <p>你有操作foo的权限。</p>
    {% if perms.foo.can_vote %}
        <p>你可以投票。</p>
    {% endif %}
    {% if perms.foo.can_drive %}
        <p>你可以开车。</p>
    {% endif %}
{% else %}
    <p>你没有操作foo的权限。</p>
{% endif %}

9.1   指定认证后端

在暗中，Django维护一个"authentication backends"的列表用来测试认证。 当某人调用 django.contrib.auth.authenticate() -- 上面提到的"如何登录一个用户" -- Django将尝试所有的认证后端。 如果第一个认证方法失败了，Django将会继续尝试第二个，直到所有的都被尝试过。

认证后端的列表在 AUTHENTICATION_BACKENDS 设置。 内容应该是包含Python路径的元组。

默认情况下， AUTHENTICATION_BACKENDS 设置为

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

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

按照 AUTHENTICATION_BACKENDS 的排列顺序, 如果同样的用户名和密码在第一次就匹配了，那么Django将停止处理后面的东西。

9.2   编写一个认证后端

一个认证后端是一个类，实现了2个方法: get_user(id) 和 authenticate(**credentials) 。

get_user 方法接受一个 id -- 可以是用户名，数据库ID或者其他的什么 -- 并且返回一个 User 对象。

authenticate 方法接受字典型认证信息的参数。大多情况下是如下样子的

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

他也可以处理一个代号(token)，像这样

class MyBackend:
    def authenticate(token=None):
        # 检测并返回User。

当 authenticate 接受的参数被验证为有效的时候，应该返回一个 User 对象； 如果无效的时候，应该返回 None 。

在本文当开头提到，Django的admin系统紧密地与 User 对象绑定在一起。 目前，最好的处理方法就是为你每一个现存的后端(例如，你的LDAP目录或者你的外部SQL数据库等等。) 数据创建一个Django的 User 对象。 你可以预先写一个脚本来做这些事情，或者在用户第一次登录的时候在你的 authenticate 方法中做这些事情。

下面是一个例子，使用在 settings.py 文件里定义的用户名和密码 并且在用户第一次登录的时候创建一个Django的 User 对象。

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'
    """
    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:
                # 创建新用户。
                # 我们可以设置任何新的密码，因为它不会被检测。
                # 在这里我们使用"get from settings.py"。
                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