django.contrib.auth — Django 文档

django.contrib.auth

本文档提供了 Django 认证系统组件的 API 参考资料。 有关这些组件的使用或如何自定义身份验证和授权的更多详细信息，请参阅 身份验证主题指南 。

User 型号

class models.User

字段

class models.User

User 对象具有以下字段：

username

必需的。 150 个字符或更少。 用户名可能包含字母数字、_、@、+、. 和 - 字符。

max_length 应该足以满足许多用例。 如果您需要更长的长度，请使用自定义用户型号。 如果您使用带有 utf8mb4 编码的 MySQL（推荐用于适当的 Unicode 支持），最多指定 max_length=191，因为默认情况下 MySQL 只能创建具有 191 个字符的唯一索引。

first_name

可选（blank=True）。 30 个字符或更少。

last_name

可选（blank=True）。 150 个字符或更少。

email

可选（blank=True）。 电子邮件地址。

password

必需的。 密码的散列和元数据。 （Django 不存储原始密码。）原始密码可以是任意长的并且可以包含任何字符。 请参阅 密码文档 。

groups

与 Group 的多对多关系

user_permissions

与权限的多对多关系

is_staff

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

is_active

布尔值。 指定是否应将此用户帐户视为活动帐户。 我们建议您将此标志设置为 False，而不是删除帐户； 这样，如果您的应用程序对用户有任何外键，则外键不会损坏。

这不一定控制用户是否可以登录。 身份验证后端不需要检查 is_active 标志，但默认后端 (ModelBackend) 和 RemoteUserBackend 会检查。 如果要允许非活动用户登录，可以使用 AllowAllUsersModelBackend 或 AllowAllUsersRemoteUserBackend。 在这种情况下，您还需要自定义 LoginView 使用的 AuthenticationForm，因为它拒绝非活动用户。 请注意，权限检查方法如 has_perm() 和 Django admin 中的身份验证都为非活动用户返回 False。

is_superuser

布尔值。 指定此用户拥有所有权限，而无需明确分配。

last_login

用户上次登录的日期时间。

date_joined

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

属性

class models.User

is_authenticated

只读属性，始终为 True（相对于 AnonymousUser.is_authenticated，始终为 False）。 这是一种判断用户是否已通过身份验证的方法。 这并不意味着任何权限，也不检查用户是否处于活动状态或具有有效的会话。 即使通常您会在 request.user 上检查此属性以了解它是否已被 AuthenticationMiddleware（代表当前登录的用户）填充，但您应该知道此属性是 [X226X ] 用于任何 User 实例。

is_anonymous

只读属性，始终为 False。 这是区分 User 和 AnonymousUser 对象的一种方式。 通常，您应该更喜欢使用 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_password 为 None 时，密码将设置为不可用密码，如同使用了 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)

3.0 版中的新功能。

返回用户直接拥有的一组权限字符串。

如果传入 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，其中每个权限的格式为 "<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_email 是 None，Django 使用 :setting:`DEFAULT_FROM_EMAIL`。 任何 **kwargs 都被传递到底层的 send_mail() 调用。

管理者方法

class models.UserManager

User 模型有一个自定义管理器，它具有以下辅助方法（除了 BaseUserManager 提供的方法）：

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

创建、保存并返回一个 User。

username 和 password 设置为给定。 email 的域部分会自动转换为小写，返回的 User 对象会将 is_active 设置为 True。

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

extra_fields 关键字参数传递给 User 的 __init__ 方法，以允许在 自定义用户模型 上设置任意字段。

有关示例用法，请参阅 创建用户 。

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

与 create_user() 相同，但将 is_staff 和 is_superuser 设置为 True。

3.0 版更改： email 和 password 参数可选。

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

3.0 版中的新功能。

以 "<app label>.<permission codename>" 格式或作为 Permission 实例返回具有给定权限 perm 的用户。 如果没有找到 perm 的用户，则返回一个空查询集。

如果 is_active 为 True（默认），则仅返回活跃用户，如果 False，则仅返回非活跃用户。 使用 None 返回所有用户，而不考虑活动状态。

如果 include_superusers 是 True（默认），结果将包括超级用户。

如果传入 backend 并且在 :setting:`AUTHENTICATION_BACKENDS` 中定义，则该方法将使用它。 否则，它会使用 :setting:`AUTHENTICATION_BACKENDS` 中的 backend，如果只有一个，否则会引发异常。

AnonymousUser 对象

class models.AnonymousUser

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

• id 总是 None。
• username 始终为空字符串。
• get_username() 总是返回空字符串。
• is_anonymous 是 True 而不是 False。
• is_authenticated 是 False 而不是 True。
• is_staff 和 is_superuser 总是 False。
• is_active 总是 False。
• groups 和 user_permissions 始终为空。
• set_password()、check_password()、save() 和 delete() 提升 NotImplementedError。

在实践中，您可能不需要自己使用 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'。

2.2 版本变更： max_length 从 80 个字符增加到 150 个字符。

permissions

权限的多对多字段：

group.permissions.set([permission_list])
group.permissions.add(permission, permission, ...)
group.permissions.remove(permission, permission, ...)
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

3.0 版中的新功能。

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

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 指定的字段（请参阅 自定义用户和身份验证 ）。

它还处理为 User 和 PermissionsMixin 定义的默认权限模型。

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_FIELD 键从 kwargs 获取用户名。 返回经过身份验证的用户或 None。

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

get_user_permissions(user_obj, obj=None)

返回 user_obj 从他们自己的用户权限中获得的权限字符串集。 如果 is_anonymous 或 is_active 是 False，则返回一个空集。

get_group_permissions(user_obj, obj=None)

从它们所属的组的权限中返回 user_obj 具有的权限字符串集。 如果 is_anonymous 或 is_active 是 False，则返回一个空集。

get_all_permissions(user_obj, obj=None)

返回 user_obj 拥有的权限字符串集，包括用户权限和组权限。 如果 is_anonymous 或 is_active 是 False，则返回一个空集。

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()

返回是否允许用户进行身份验证。 为了匹配 AuthenticationForm 的行为 禁止非活动用户登录 ，此方法为 is_active=False 的用户返回 False。 允许没有 is_active 字段的自定义用户模型。

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

3.0 版中的新功能。

以 "<app label>.<permission codename>" 或 Permission 实例的形式返回具有权限 perm 的所有活动用户。 如果没有找到 perm 的用户，则返回一个空查询集。

如果 is_active 为 True（默认），则仅返回活跃用户，如果 False，则仅返回非活跃用户。 使用 None 返回所有用户，而不考虑活动状态。

如果 include_superusers 是 True（默认），结果将包括超级用户。

class AllowAllUsersModelBackend

与 ModelBackend 相同，但它不会拒绝非活动用户，因为 user_can_authenticate() 总是返回 True。

使用此后端时，您可能希望通过覆盖 confirm_login_allowed() 方法来自定义 LoginView 使用的 AuthenticationForm，因为它拒绝非活动用户。

class RemoteUserBackend

使用此后端来利用外部到 Django 处理的身份验证。 它使用在 request.META['REMOTE_USER'] 中传递的用户名进行身份验证。 请参阅 针对 REMOTE_USER 进行身份验证的文档。

如果您需要更多控制，您可以创建您自己的从此类继承的身份验证后端并覆盖这些属性或方法：

create_unknown_user

True 或 False。 确定是否创建用户对象（如果数据库中尚未存在） 默认为 True。

authenticate(request, remote_user)

作为 remote_user 传递的用户名被认为是可信的。 此方法返回具有给定用户名的用户对象，如果 create_unknown_user 是 True，则创建一个新的用户对象。

如果 create_unknown_user 是 False 并且在数据库中找不到具有给定用户名的 User 对象，则返回 None。

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

clean_username(username)

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

configure_user(request, user)

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

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

2.2 版更改： 添加了 request 参数。 Django 3.1 中将删除对不接受它的方法覆盖的支持。

user_can_authenticate()

返回是否允许用户进行身份验证。 此方法为 is_active=False 的用户返回 False。 允许没有 is_active 字段的自定义用户模型。

class AllowAllUsersRemoteUserBackend

与 RemoteUserBackend 相同，但它不会拒绝非活动用户，因为 user_can_authenticate 总是返回 True。

实用功能

get_user(request)

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

它检查存储在会话中的身份验证后端是否存在于 :setting:`AUTHENTICATION_BACKENDS` 中。 如果是，则使用后端的 get_user() 方法检索用户模型实例，然后通过调用用户模型的 get_session_auth_hash() 方法验证会话。

如果会话中存储的身份验证后端不再在 中，则返回 AnonymousUser 的实例：setting:`AUTHENTICATION_BACKENDS`，如果后端的 [ X205X] 方法，或者会话身份验证哈希未验证。