django.contrib.auth

该文档提供了 Django 认证系统组件的 API 。有关更多这些组件的用例,或需要自定义认证与鉴权,请参阅 认证主题指南

User 模型

class models.``User

字段

class models.``User

User 对象有如下字段:

  • username

    必要的。150 个字符或以下。用户名可包含字母数字、_@+.- 字符。

    max_length 对许多使用情况来说应该是足够的。如果你需要更长的长度,请使用 自定义用户模型。如果你使用的 MySQL 是 utf8mb4 编码(推荐用于适当的 Unicode 支持),最多指定 max_length=191,因为在这种情况下,MySQL 默认只能创建 191 个字符的唯一索引。

  • first_name

    可选的(blank=True)。150 个字符或更少。

    Changed in Django 3.1:

    max_length 从 30 个字符增加到 150 个字符。

  • last_name

    可选的(blank=True)。150 个字符或更少。

  • email

    可选的(blank=True)。电子邮件地址。

  • password

    需要。一个密码的哈希值和元数据。(Django 不存储原始密码。)原始密码可以任意长,可以包含任何字符。参见 密码文档

  • groups

    多对多关系到 Group

  • user_permissions

    多对多关系到 Permission

  • is_staff

    布尔型。指定该用户是否可以访问管理站点。

  • is_active

    布尔值。指定该用户账户是否应该被视为活跃账户。我们建议你把这个标志设置为 False,而不是删除账户;这样,如果你的应用程序对用户有任何外键,外键就不会被破坏。

    这不一定能控制用户是否能登录。认证后端不一定需要检查 is_active 标志,但默认的后端(ModelBackend)和 RemoteUserBackend 会检查。如果你想允许不活跃的用户登录,你可以使用 AllowAllUsersModelBackend 或者 AllowAllUsersRemoteUserBackend。在这种情况下,你还需要自定义 AuthenticationForm 所使用的 LoginView,因为它拒绝非活动用户。需要注意的是, has_perm() 等权限检查方法,以及 Django 管理中的认证方法,都会对非活跃用户返回 False

  • is_superuser

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

  • last_login

    用户最后一次登录的日期时间。

  • date_joined

    指定账户创建时间的日期时间。帐户创建时,默认设置为当前日期/时间。

属性

class models.``User

  • is_authenticated

    只读属性,始终返回 True (匿名用户 AnonymousUser.is_authenticated 始终返回 False )。这是一种判断用户是否已通过身份认证的方法。这并不意味着任何权限,也不会检查用户是否处于活动状态或是否具有有效会话。即使通常你会根据 request.user 检查这个属性,以确定它是否被 AuthenticationMiddleware 填充(表示当前登录的用户),但是你应该知道该属性对于任何 User 实例都返回 True

  • is_anonymous

    只读属性,总是 False。这是区分 UserAnonymousUser 对象的一种方式。一般来说,你应该优先使用 is_authenticated 来代替这个属性。

方法

class models.``User

  • get_username()

    返回用户的用户名。由于 User 模型可以被替换,你应该使用这个方法而不是直接引用用户名属性。

  • get_full_name()

    返回 first_name 加上 last_name,中间有一个空格。

  • get_short_name()

    返回 first_name

  • set_password(raw_password)

    将用户的密码设置为给定的原始字符串,并进行密码哈希处理。不保存 User 对象。

    raw_passwordNone 时,密码将被设置为不可用的密码,就像 set_unusable_password() 一样。

  • check_password(raw_password)

    如果给定的原始字符串是用户的正确密码,返回 True。(密码哈希值用于比较)

  • set_unusable_password()

    标记该用户没有设置密码。 check_password() 对这个用户的检查永远不会返回 True。不会保存 User 对象。

    如果针对现有外部源(例如 LDAP 目录)进行应用程序的身份认证,则可能需要这个功能。

  • has_usable_password()

    如果 set_unusable_password() 被调用,返回 False

  • 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>"。(参见 权限 的文档)。如果用户是不活跃的,这个方法将总是返回 False。对于活跃的超级用户,本方法将始终返回 True

    如果传入了 obj,这个方法不会检查模型的权限,而是检查这个特定对象的权限。

  • has_perms(perm_list, obj=None)

    如果用户拥有指定的每个权限,返回 True,其中每个 perm 的格式为 "<app label>.<permission codename>"。如果用户不活跃,本方法将总是返回 False。对于活跃的超级用户,本方法将始终返回 True

    如果传入了 obj,这个方法不会检查模型的权限,而是检查这个特定对象的权限。

  • has_module_perms(package_name)

    如果用户在给定的包(Django 应用标签)中有任何权限,则返回 True。如果用户不活跃,本方法将总是返回 False。如果是活跃的超级用户,本方法将始终返回 True

  • email_user(subject, message, from_email=None, \*kwargs*)

    向用户发送邮件。如果 from_emailNone,Django 使用 DEFAULT_FROM_EMAIL。任何 **kwargs 都会传递给底层的 send_mail() 调用。

管理器方法

class models.``UserManager

User 模型有一个自定义管理器,它有以下辅助方法(除了 BaseUserManager 提供的方法外):

  • create_user(username, email=None, password=None, \*extra_fields*)

    创建、保存并返回一个 User

    usernamepassword 按给定设置。email 的域名部分会自动转换为小写,返回的 User 对象的 is_active 设置为 True

    如果没有提供密码, set_unusable_password() 将被调用。

    extra_fields 关键字参数被传递到 User__init__ 方法中,允许在 自定义用户模型 上设置任意字段。

    使用方法参见 创建用户

  • create_superuser(username, email=None, password=None, \*extra_fields*)

    create_user() 相同,但将 is_staffis_superuser 设置为 True

  • with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)

    返回拥有给定权限 perm 的用户,可以是 "<app label>.<permission codename>" 格式,也可以是 Permission 实例。如果没有找到拥有 perm 的用户,返回一个空的查询集。

    如果 is_activeTrue (默认),则只返回活跃用户,如果 False,则只返回非活跃用户。使用 None 返回所有用户,无论其是否处于活跃状态。

    如果 include_superusersTrue (默认),结果将包括超级用户。

    如果传入了 backend,并且在 AUTHENTICATION_BACKENDS 中定义了,那么本方法将使用它。否则,它将使用 AUTHENTICATION_BACKENDS 中的 backend,如果只有一个的话,或者引发一个异常。

AnonymousUser 对象

class models.``AnonymousUser

django.contrib.auth.models.AnonymousUser 是一个实现了 django.contrib.auth.models.User 接口的类,有这些区别:

在实践中,你可能不需要自己使用 AnonymousUser 对象,但它们会被 Web 请求使用,下一节会解释。

Permission 模型

class models.``Permission

字段

Permission 对象有以下字段:

class models.``Permission

  • name

    必要的。255 个字符或以下。例如:'Can vote'

  • content_type

    必要的。对 django_content_type 数据库表的引用,该表包含每个已安装模型的记录。

  • codename

    必要的。100 个字符或以下。例如:'can_vote'

方法

Permission 对象和其他 Django 模型 一样拥有标准的数据访问方法。

Group 模型

class models.``Group

字段

Group 对象有以下字段:

class models.``Group

  • name

    要求: 150 个字符或以下。允许使用任何字符。例如:'Awesome Users'

  • permissions

    多对多字段到 Permission

    1. group.permissions.set([permission_list])
    2. group.permissions.add(permission, permission, ...)
    3. group.permissions.remove(permission, permission, ...)
    4. group.permissions.clear()

验证器

class validators.``ASCIIUsernameValidator

除了 @.+-_ 之外,只允许使用 ASCII 字母和数字的字段验证器。

class validators.``UnicodeUsernameValidator

除了 @.+-_ 之外,还允许使用 Unicode 字符的字段验证器。User.username 的默认验证器。

登录和注销的信号

认证框架使用了以下的 信号,可以在用户登录或退出时用于通知。

user_logged_in()

当用户成功登录时发送。

用此信号发送的参数:

  • sender

    刚刚登录的用户的类。

    request

    当前的 HttpRequest 实例。

    user

    刚刚登录的用户的实例。

user_logged_out()

调用注销方法时发送。

  • sender

    如上所述:刚刚注销的用户的类,如果用户没有经过认证,则为 None

    request

    当前的 HttpRequest 实例。

    user

    刚刚注销的用户实例,如果用户没有经过认证,则为 None

user_login_failed()

当用户未能成功登录时发送

  • sender

    用于认证的模块名称。

    credentials

    一个包含关键字参数的字典,其中包含传递给 authenticate() 或你自己的自定义认证后端的用户凭证。匹配一组“敏感的”模式的凭证(包括密码)将不会作为信号的一部分被发送。

    request

    HttpRequest 对象,如果有提供给 authenticate() 对象的话。

认证后端

本节详细介绍了 Django 自带的认证后端。关于如何使用它们以及如何编写你自己的认证后端,请参阅 用户认证指南 中的 其他认证源 部分。

可用的认证后端

django.contrib.auth.backends 中可以找到以下后端:

class BaseBackend

一个为所有所需方法提供默认实现的基类。默认情况下,它将拒绝任何用户并不提供任何权限。

  • get_user_permissions(user_obj, obj=None)

    返回一个空集。

  • get_group_permissions(user_obj, obj=None)

    返回一个空集。

  • get_all_permissions(user_obj, obj=None)

    使用 get_user_permissions()get_group_permissions() 来获取 user_obj 所拥有的权限字符串。

  • has_perm(user_obj, perm, obj=None)

    使用 get_all_permissions() 检查 user_obj 是否有 perm 的权限字符串。

class ModelBackend

这是 Django 默认使用的认证后端。 它使用由用户标识符和密码组成的凭证进行认证。 对于 Django 的默认用户模型来说,用户标识符是用户名,对于自定义用户模型来说,它是 USERNAME_FIELD 指定的字段(参见 自定义用户和身份认证)。

它还处理了为 UserPermissionsMixin 定义的默认权限模型。

has_perm()get_all_permissions()get_user_permissions()get_group_permissions() 允许将对象作为参数传递给特定对象的权限,但除了在 obj is not None 的情况下返回一个空的权限集外,这个后端并没有实现它们。

with_perm() 也允许传递一个对象作为参数,但与其他方法不同的是,如果 obj is not None,则返回一个空的查询集。

  • authenticate(request, username=None, password=None, \*kwargs*)

    通过调用 User.check_password 尝试用 password 认证 username。如果没有提供 username,则尝试使用键 CustomUser.USERNAME_FIELDkwargs 中获取一个用户名。返回一个已认证的用户或 None

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

  • get_user_permissions(user_obj, obj=None)

    从他们自己的用户权限中返回 user_obj 拥有的权限字符串集。如果 is_anonymousis_activeFalse,则返回空集。

  • get_group_permissions(user_obj, obj=None)

    从他们自己的用户权限中返回 user_obj 拥有的权限字符串集。如果 is_anonymousis_activeFalse,则返回空集。

  • get_all_permissions(user_obj, obj=None)

    从他们自己的用户权限中返回 user_obj 拥有的权限字符串集。如果 is_anonymousis_activeFalse,则返回空集。

  • has_perm(user_obj, perm, obj=None)

    使用 get_all_permissions() 检查 user_obj 是否有 perm 的权限。如果用户没有 is_active,则返回 False

  • has_module_perms(user_obj, app_label)

    返回 user_obj 是否对应用 app_label 具有任何权限。

  • user_can_authenticate()

    返回是否允许用户进行认证。为了与 AuthenticationFormprohibits inactive users from logging in 的行为相匹配,对于有 is_active=False 的用户,本方法返回 False。允许没有 is_active 字段的自定义用户模型。

  • with_perm(perm, is_active=True, include_superusers=True, obj=None)

    返回所有拥有 perm 权限的活跃用户,可以是 "<app label>.<permission codename>" 的形式,也可以是 Permission 实例。如果没有找到拥有 perm 权限的用户,则返回一个空的查询集。

    如果 is_activeTrue (默认),则只返回活跃用户,如果 False,则只返回非活跃用户。使用 None 返回所有用户,无论其是否处于活跃状态。

    如果 include_superusersTrue (默认),结果将包括超级用户。

class AllowAllUsersModelBackend

ModelBackend 一样,只是它不会拒绝非活动用户,因为 user_can_authenticate() 总是返回 True

当使用这个后台时,你可能会想要自定义 AuthenticationForm 所使用的 LoginView,通过覆盖 confirm_login_allowed() 方法,因为它拒绝非活动用户。

class RemoteUserBackend

使用这个后端来利用外部对 Django 处理的认证。 它使用 request.META['REMOTE_USER'] 中传递的用户名进行认证。 参见 认证 REMOTE_USER 文档。

如果你需要更多的控制,你可以创建自己的认证后端,继承这个类,并覆盖这些属性或方法:

  • create_unknown_user

    TrueFalse。确定如果数据库中没有用户对象,是否创建用户对象。默认为 True

  • authenticate(request, remote_user)

    作为 remote_user 传递的用户名被认为是可信的。如果 create_unknown_userTrue,则该方法返回给定用户名的用户对象,创建一个新的用户对象。

    如果 create_unknown_userFalse,且数据库中没有找到给定用户名的 User 对象,则返回 None

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

  • clean_username(username)

    在使用 username 获取或创建用户对象之前,对 username 进行任何清理(例如剥离 LDAP DN 信息)。返回清理后的用户名。

  • configure_user(request, user)

    配置一个新创建的用户。 这个方法在新用户创建后立即被调用,可以用来执行自定义设置操作,例如根据 LDAP 目录中的属性设置用户的组。返回用户对象。

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

  • user_can_authenticate()

    返回是否允许用户进行身份认证。对于有 is_active=False 的用户,本方法返回 False。允许没有 is_active 字段的自定义用户模型。

class AllowAllUsersRemoteUserBackend

RemoteUserBackend 相同,只是它不会拒绝非活动用户,因为 user_can_authenticate 总是返回 True

实用工具函数

get_user(request)

返回与给定 request 的会话相关联的用户模型实例。

它检查会话中存储的认证后端是否存在于 AUTHENTICATION_BACKENDS 中。如果存在,它使用后端的 get_user() 方法检索用户模型实例,然后通过调用用户模型的 get_session_auth_hash() 方法来认证会话。

如果存储在会话中的认证后端不再在 AUTHENTICATION_BACKENDS 中,如果后端的 get_user() 方法没有返回用户,或者会话认证的哈希没有认证,则返回一个 AnonymousUser 的实例。