Django 中的自定义验证

指定认证后端

在幕后，Django 维护了一个 “认证后端” 列表，用于检查认证。当有人调用 django.contrib.auth.authenticate() ——就像 如何登录用户 中描述的那样——Django 会尝试对所有的认证后端进行认证。如果第一个认证方法失败，Django 就尝试第二个，以此类推，直到所有后端都尝试过。

要使用的认证后端列表在 AUTHENTICATION_BACKENDS 配置中指定。这应该是一个指向知道如何验证的 Python 类的 Python 路径名列表。这些类可以是 Python 路径上的任何地方。

默认情况下，AUTHENTICATION_BACKENDS 配置为：

['django.contrib.auth.backends.ModelBackend']

That's the basic authentication backend that checks the Django users database and queries the built-in permissions. It does not provide protection against brute force attacks via any rate limiting mechanism. You may either implement your own rate limiting mechanism in a custom auth backend, or use the mechanisms provided by most web servers.

AUTHENTICATION_BACKENDS 的顺序很重要，所以如果同一个用户名和密码在多个后端都有效，Django 会在第一个正向匹配时停止处理。

如果一个后端抛出 PermissionDenied 异常，则验证流程立马终止，Django 不会继续检查其后的后端。

编写一个认证后端

认证后端是一个类，它实现了两个必要的方法：get_user(user_id) 和 authenticate(request, **credentials)，以及一组可选的与权限相关的 认证方法。

get_user 方法接收一个 user_id ——可以是用户名、数据库 ID 或其他什么，但必须是用户对象的主键——然后返回一个用户对象或 None。

authenticate 方法采用 request 参数和证书作为关键字参数。大多数情况下，它看起来像这样：

from django.contrib.auth.backends import BaseBackend

class MyBackend(BaseBackend):
    def authenticate(self, request, username=None, password=None):
        # Check the username/password and return a user.
        ...

但它也可以认证一个令牌，比如：

from django.contrib.auth.backends import BaseBackend

class MyBackend(BaseBackend):
    def authenticate(self, request, token=None):
        # Check the token and return a user.
        ...

无论哪种方式，authenticate() 应该检查它所得到的凭证，如果凭证有效，则返回一个与这些凭证相匹配的用户对象。如果无效，则应返回 None。

request 是一个 HttpRequest，如果没有提供给 authenticate() （将其传递给后端），则可能是 None。

Django admin 与 Django User 对象 紧密耦合。处理这个问题的最好方法是为每个存在于后台的用户创建一个 Django User 对象（例如，在你的 LDAP 目录中，你的外部 SQL 数据库中，等等），你可以提前写一个脚本来完成这个任务，或者你的 authenticate 方法可以在用户第一次登录时完成。

下面是一个后端实例，它可以根据 settings.py 文件中定义的用户名和密码变量进行验证，并在用户第一次验证时创建一个 Django User 对象：

from django.conf import settings
from django.contrib.auth.backends import BaseBackend
from django.contrib.auth.hashers import check_password
from django.contrib.auth.models import User

class SettingsBackend(BaseBackend):
    """
    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 = 'pbkdf2_sha256$30000$Vo0VlMnkR4Bk$qEvtdyZRWTcOsCnI/oQ7fVOu1XAURIZYoOZ3iq8Dr4M='
    """

    def authenticate(self, request, 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. There's no need to set a password
                # because only the password from settings.py is checked.
                user = User(username=username)
                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

启动项目时使用自定义用户模型

如果你准备启动一个新的项目，强烈推荐你设置一个自定义的用户模型，即使默认的用户模型对你来说已经足够了。这个模型的行为与默认用户模型相通，但是你能在未来需要的时候自定义它：

from django.contrib.auth.models import AbstractUser

class User(AbstractUser):
    pass

不要忘记将 AUTH_USER_MODEL 指向它。在创建任何迁移或者首次运行 manage.py migrate 之前执行这个操作。

同样的，在 app 中的 admin.py 中注册模型。

from django.contrib import admin
from django.contrib.auth.admin import UserAdmin
from .models import User

admin.site.register(User, UserAdmin)

在项目中更改为自定义用户模型。

在你已经建立数据库表之后再去修改 AUTH_USER_MODEL 要困难的多，因为它会影响外键和多对多关系。

这个改动并不能自动完成，需要手动修复你的架构，将数据从旧的用户表移出，并有可能需要手动执行一些迁移操作。查看步骤概述，请查看 #25313。

由于 Django 对可交换模型的动态依赖特性的限制，AUTH_USER_MODEL 所引用的模型必须在其应用的第一次迁移中创建（通常称为 0001_initial）；否则，你会出现依赖问题。

此外，当你运行迁移时，你可能会遇到一个 CircularDependencyError，因为 Django 不会因为动态依赖而自动打破依赖循环。如果你看到这个错误，你应该通过将你的用户模型所依赖的模型移动到第二个迁移中来打破这个循环。（如果你想看看通常是怎么做的，你可以尝试做两个正常的模型，它们之间有一个 ForeignKey，看看 makemigrations 是如何解决这个循环依赖的。）

可重用应用和 AUTH_USER_MODEL

可重用应用不应该实现自定义用户模型。一个项目可能会使用很多应用，两个实现了自定义用户模型的可重用应用不能一起使用。如果你需要在你的应用中存储每个用户的信息，可以使用一个 ForeignKey 或 OneToOneField 到 settings.AUTH_USER_MODEL，如下所述。

引用 User 模型

如果你直接引用 User （例如，通过在一个外键中引用它），你的代码将无法在 AUTH_USER_MODEL 配置已被更改为不同用户模型的项目中工作。

get_user_model()

与其直接引用 User，不如使用 django.contrib.auth.get_user_model() 引用用户模型。这个方法将返回当前活动的用户模型——如果指定了自定义用户模型，则返回自定义用户模型，否则返回 User。

在定义用户模型的外键或多对多关系时，应使用 AUTH_USER_MODEL 配置指定自定义模型。例如：

from django.conf import settings
from django.db import models

class Article(models.Model):
    author = models.ForeignKey(
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
    )

连接用户模型发送的信号时，应使用 AUTH_USER_MODEL 配置指定自定义模型。例如：

from django.conf import settings
from django.db.models.signals import post_save

def post_save_receiver(sender, instance, created, **kwargs):
    pass

post_save.connect(post_save_receiver, sender=settings.AUTH_USER_MODEL)

一般来说，在导入时执行的代码中，用 AUTH_USER_MODEL 配置来引用用户模型是最简单的，不过，也可以在 Django 导入模型时调用 get_user_model()，所以可以使用 models.ForeignKey(get_user_model()，...)。

例如，如果你的应用是用多个用户模型进行测试的，使用 @override_settings(AUTH_USER_MODEL=...)，并且你把 get_user_model() 的结果缓存在模块级变量中，你可能需要监听 setting_changed 信号来清除缓存。例如：

from django.apps import apps
from django.contrib.auth import get_user_model
from django.core.signals import setting_changed
from django.dispatch import receiver

@receiver(setting_changed)
def user_model_swapped(*, setting, **kwargs):
    if setting == 'AUTH_USER_MODEL':
        apps.clear_cache()
        from myapp import some_module
        some_module.UserModel = get_user_model()

为自定义的用户模型编写一个管理器

你也该为你的用户模型定义一个自定义管理器。如果你的用户模型定义了和默认用户相同的 username, email, is_staff, is_active, is_superuser, last_login, 和 ``date_joined`等字段，你可以安装 UserManager ；但是，如果你的用户模型还定义了其他字段，那么就需要定义一个自定义管理器，它扩展了 BaseUserManager ，提供了两个额外的方法：

class models.CustomUserManager

create_user(username_field, password=None, **other_fields)

create_user() 的原型应该接受username字段，加上其他所有必须的字段作为参数。举例，如果你的用户模型使用 email 作为用户名字段，date_of_birth  字段作为必填字段，那么 create_user 应该如下定义：

def create_user(self, email, date_of_birth, password=None):
    # create user here
    ...

create_superuser(username_field, password=None, **other_fields)

create_superuser() 的原型应该接受username字段，加上其他所有必须的字段作为参数。举例，如果你的用户模型使用 email 作为用户名字段，date_of_birth 字段作为必填字段，那么 create_superuser 应该如下定义：

def create_superuser(self, email, date_of_birth, password=None):
    # create superuser here
    ...

对于 USERNAME_FIELD 或 REQUIRED_FIELDS 中的 ForeignKey ，这些方法接收现有实例的:attr:~.ForeignKey.to_field （默认为 primary_key ）的值。

BaseUserManager 提供以下实用方法：

class models.BaseUserManager

classmethod normalize_email(email)

通过降低电子邮件地址的域部分来规范化电子邮件地址。

get_by_natural_key(username)

使用 USERNAME_FIELD 指定的字段的内容检索用户实例。

make_random_password(length=10, allowed_chars='abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789')

返回具有给定长度和给定字符串的随机密码。请注意， allowed_chars 的默认值不包含可能导致用户混淆的字母，包括：

• i, l, I, 和 1 (小写i, 小写L, 大写i和数字1)
• o, O, 和 0 (小写 o, 大写 o, 和数字0 )

扩展Django的默认用户模型

If you're entirely happy with Django's User model, but you want to add some additional profile information, you could subclass django.contrib.auth.models.AbstractUser and add your custom profile fields, although we'd recommend a separate model as described in 指定自定义用户模型. AbstractUser provides the full implementation of the default User as an abstract model.

自定义用户和 django.contrib.admin

如果你希望自定义的用户模型也与管理后台一起使用，那么你的用户模型必须定义一些额外的属性和方法。这些方法允许管理员控制用户对管理后台内容的访问：

class models.CustomUser

is_staff

如果允许用户有访问 admin 页面就返回 True。

is_active

返回``True``，如果该用户的账号当前是激活状态

has_perm(perm, obj=None):

如果用户有指定的权限，则返回 True 。如果提供了参数 obj  ，则需要对指定的对象实例进行权限检查。

has_module_perms(app_label):

如果用户有权限访问指定 app 里的模型，那么返回 True 。

你也需要在 admin 文件里注册自定义的用户模型。如果自定义的用户模型扩展了 django.contrib.auth.models.AbstractUser ，你可以直接使用Django已有的类 django.contrib.auth.admin.UserAdmin 。如果你的用户模型扩展了 AbstractBaseUser ，你将需要定义一个自定义的类 ModelAdmin 。不管怎样，你都将需要重写任何引用 django.contrib.auth.models.AbstractUser 上的字段的定义，这些字段不在你自定义的用户类中。

from django.contrib.auth.admin import UserAdmin

class CustomUserAdmin(UserAdmin):
    ...
    fieldsets = UserAdmin.fieldsets + (
        (None, {'fields': ('custom_field',)}),
    )
    add_fieldsets = UserAdmin.add_fieldsets + (
        (None, {'fields': ('custom_field',)}),
    )

自定义用户和权限。

为了便于将Django的权限框架引入到你自己的用户类中，Django提供了 PermissionsMixin 。这是一个抽象模型，可以包含在用户模型的类层次结构中，为你提供支持Django权限模型所需的所有方法和数据库字段。

PermissionsMixin 提供下列方法和属性：

class models.PermissionsMixin

is_superuser

布尔值。指定该用户拥有所有权限，而不用一个个开启权限。

get_user_permissions(obj=None)

返回用户本身就自带的权限字符串集合。

如果传入了 obj ，则只返回指定对象的用户权限。

get_group_permissions(obj=None)

返回用户拥有权限的字符串集合，从用户所属组的权限中获取。

如果传入 obj 参数，则只返回指定对象所属组的权限。

get_all_permissions(obj=None)

返回用户拥有权限的字符串集合，同时从用户所属组及用户本身的权限中获取。

如果传入 ``obj``参数，则只返回指定对象和所属组的权限。

has_perm(perm, obj=None)

如果用户具有指定的权限，则返回 True ，其中 perm 的格式为 "<app label>.<permission codename>" (see permissions)。如果 User.is_active 和 is_superuser 都为 True，则这个方法一直返回 True 。

如果传入 obj 参数，则这个方法不会检查该模型权限，而只会检查这个出传入对象的权限。

has_perms(perm_list, obj=None)

如果用户具有指定权限列表里的每个权限，则返回 True ，其中perm的格式为 "<app label>.<permission codename>" 。如果 User.is_active 和 is_superuser 都返回 True ，则这个方法一直返回 True 。

如果传入参数 obj  ，则这个方法不会检查指定的权限列表，只检查指定对象的权限。

has_module_perms(package_name)

如果用户拥有所给的 Django app 标签 (the Django app label) 里的任何权限，则会返回 True 。如果 User.is_active 和 is_superuser 都为 True ，则该方法一直返回 True 。

自定义用户和代理模型

自定义用户模型的一个限制是安装自定义用户模型将破坏任何扩展 User 的代理模型。代理模型必须基于具体的基类；通过定义自定义用户模型，你就移除了Django可靠地识别基类的功能。

如果你的项目正在使用代理模型，你必须修改扩展用户模型的代理，或者把代理的行为都合并到 User 子类里去。