django.contrib.auth¶本文件为Django认证系统的组成部分提供了API参考资料。有关这些组件的用法或如何自定义身份验证和授权的详细信息，请参阅 authentication topic guide .
User 模型¶User 对象具有以下字段：
必修的。不超过150个字符。用户名可以包含字母数字， _, @, +, . 和 - 字符。
的 max_length 对于许多用例来说应该足够了。如果您需要更长的长度，请使用 custom user model .
可选的 (blank=True ）不超过150个字符。
可选的 (blank=True ）不超过150个字符。
可选的 (blank=True ）电子邮件地址。
必需的.密码的哈希值和有关密码的元数据。（Django不存储原始密码。）原始密码可以任意长，并且可以包含任何字符。此字段中的元数据可能会将密码标记为不可用。看到 password documentation .
多对多关系 Permission
布尔型。允许此用户访问管理站点。
布尔型。将此用户帐户标记为活动。我们建议您将此标志设置为 False 而不是删除帐户。这样，如果您的应用程序有任何指向用户的外键，外键就不会中断。
这不一定控制用户是否可以登录。不需要验证后端来检查 is_active 标记，但默认后端 (ModelBackend ） RemoteUserBackend 做。你可以使用 AllowAllUsersModelBackend 或 AllowAllUsersRemoteUserBackend 如果要允许非活动用户登录。在这种情况下，您还需要自定义 AuthenticationForm 用于 LoginView 因为它拒绝不活动的用户。注意权限检查方法，例如 has_perm() django admin中的身份验证全部返回 False 对于非活动用户。
布尔型。将此用户视为拥有所有权限，而不特别为其分配任何权限。
用户上次登录的日期时间。
创建帐户的日期/时间。
只读属性 True （而不是 AnonymousUser.is_authenticated 总是这样 False ）这是一种判断用户是否已通过身份验证的方法。这并不意味着任何权限，也不检查用户是否处于活动状态或是否具有有效会话。即使正常情况下您将在 request.user 以确定它是否由 AuthenticationMiddleware （表示当前登录的用户），您应该知道该属性是 True 对于任何 User 实例。
只读属性 False . 这是一种区分 User 和 AnonymousUser 对象。一般来说，您应该更喜欢使用 is_authenticated 到这个属性。
返回用户的用户名。自从 User 模型可以换出，您应该使用这个方法，而不是直接引用username属性。
返回 first_name 加上 last_name ，中间有一个空格。
返回 first_name .
将用户密码设置为给定的原始字符串，注意密码散列。不保存 User 对象。
当 raw_password 是 None ，密码将设置为不可用的密码，就像 set_unusable_password() 使用。
Asynchronous version ： acheck_password()
返回 True 如果给定的原始字符串是用户的正确密码。（这将在进行比较时考虑密码散列。）
中的元数据将用户标记为未设置密码 password 领域这与密码具有空白字符串不同。 check_password() 对于该用户将永远不会返回 True .也救不了 User object.
如果应用程序针对现有外部源（如LDAP目录）进行身份验证，则可能需要这样做。
密码重置限制
密码不可用的用户将无法通过以下方式请求密码重置电子邮件 PasswordResetView 。
返回 False 如果 set_unusable_password() 已为此用户调用。
Asynchronous version : aget_user_permissions()
返回用户直接拥有的一组权限字符串。
如果 obj 传递，仅返回该特定对象的用户权限。
aget_user_permissions() 添加了方法。
Asynchronous version : aget_group_permissions()
返回用户通过其组拥有的一组权限字符串。
如果 obj 传入，仅返回此特定对象的组权限。
aget_group_permissions() 添加了方法。
Asynchronous version : aget_all_permissions()
返回用户通过组和用户权限拥有的一组权限字符串。
如果 obj 传入，仅返回此特定对象的权限。
aget_all_permissions() 添加了方法。
Asynchronous version : ahas_perm()
退货 True 如果用户具有指定的权限，其中perm的格式为 "<app label>.<permission codename>" . (see文档 permissions ).如果用户处于非活动状态，此方法将始终返回 False .对于活跃的超级用户来说，该方法总是会返回 True 。
如果 obj 如果传入，此方法将不会检查模型的权限，而是检查此特定对象的权限。
ahas_perm() 添加了方法。
Asynchronous version : ahas_perms()
退货 True 如果用户具有每个指定的权限，其中每个烫发的格式为 "<app label>.<permission codename>" .如果用户处于非活动状态，此方法将始终返回 False .对于活跃的超级用户来说，该方法总是会返回 True 。
如果 obj 如果传入，此方法将不会检查模型的权限，而是检查特定对象的权限。
ahas_perms() 添加了方法。
Asynchronous version : ahas_module_perms()
退货 True 用户是否在给定包中拥有任何权限（Django应用程序标签）。如果用户处于非活动状态，此方法将始终返回 False .对于活跃的超级用户来说，该方法总是会返回 True 。
ahas_module_perms() 添加了方法。
向用户发送电子邮件。如果 from_email 是 None ，Django使用 DEFAULT_FROM_EMAIL . 任何 **kwargs 传递给基础 send_mail() 调用。
这个 User 模型有一个自定义管理器，该管理器具有以下帮助器方法（除了 BaseUserManager ）：
Asynchronous version : acreate_user()
创建、保存并返回 User .
这个 username 和 password 按给定设置。的域部分 email 将自动转换为小写，并返回 User 对象将具有 is_active 设置为 True .
如果没有提供密码， set_unusable_password() 将被调用。
如果没有提供电子邮件， email 将被设置为空字符串。
这个 extra_fields 关键字参数传递给 User 的 __init__ 方法以允许在 custom user model .
见 Creating users 例如用法。
acreate_user() 添加了方法。
Asynchronous version : acreate_superuser()
等同于 create_user() 但集合 is_staff 和 is_superuser 到 True .
acreate_superuser() 添加了方法。
返回具有给定权限的用户 perm 无论是在 "<app label>.<permission codename>" 格式或作为 Permission instance.如果没有用户拥有 perm found.
如果 is_active 是 True （默认），仅返回活动用户，或者如果 False ，仅返回非活动用户。使用 None 返回所有用户，无论活动状态如何。
如果 include_superusers 是 True （默认），结果将包括超级用户。
如果 backend 被传递并定义在 AUTHENTICATION_BACKENDS ，那么这个方法就会使用它。否则，它就会使用 backend 在……里面 AUTHENTICATION_BACKENDS ，如果只有一个，或者引发异常。
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 模型¶Permission 对象具有以下字段：
必修的。255个字符或更少。例子： 'Can vote' .
必需的.的外键 ContentType 模型
必修的。不超过100个字符。例子： 'can_vote' .
Permission 对象与其他对象一样具有标准的数据访问方法 Django model .
Group 模型¶Group 对象具有以下字段：
必修的。不超过150个字符。允许使用任何字符。例子： 'Awesome Users' .
多对多字段到 Permission ：：
group.permissions.set([permission_list])
group.permissions.add(permission, permission, ...)
group.permissions.remove(permission, permission, ...)
group.permissions.clear()
除此之外，只允许使用ASCII字母和数字的字段验证器 @ ， . ， + ， - 和 _ .
除了允许使用Unicode字符外，还允许使用 @ ， . ， + ， - 和 _ . 的默认验证器 User.username .
auth框架使用以下内容 signals 它可用于用户登录或注销时的通知。
当用户成功登录时发送。
随此信号发送的参数：
sender刚登录的用户的类。
requestHttpRequest 实例。
user刚登录的用户实例。
在调用注销方法时发送。
sender如上所述：刚注销或 None 如果用户未通过身份验证。
requestHttpRequest 实例。
user刚注销的用户实例或 None 如果用户未通过身份验证。
用户登录失败时发送
sender用于身份验证的模块的名称。
credentials包含传递给的用户凭据的关键字参数字典 authenticate() 或者您自己的自定义身份验证后端。与一组“敏感”模式（包括密码）匹配的凭证不会作为信号的一部分以明文形式发送。
request这个 HttpRequest 对象，如果提供给 authenticate() .
本节详细介绍了Django附带的身份验证后端。有关如何使用它们以及如何编写自己的身份验证后端的信息，请参阅 Other authentication sources section 的 User authentication guide .
以下后端可用于 django.contrib.auth.backends ：
为所有所需方法提供默认实现的Base Class。默认情况下，它将拒绝任何用户并且不提供任何权限。
Asynchronous version : aget_user_permissions()
返回空集。
aget_user_permissions() 添加了功能。
Asynchronous version : aget_group_permissions()
返回空集。
aget_group_permissions() 添加了功能。
Asynchronous version : aget_all_permissions()
用途 get_user_permissions() 和 get_group_permissions() 要获取权限字符串集， user_obj 类型为.
aget_all_permissions() 添加了功能。
Asynchronous version : ahas_perm()
用途 get_all_permissions() 以检查是否 user_obj 具有权限字符串 perm 。
ahas_perm() 添加了功能。
这是Django使用的默认身份验证后端。它使用由用户标识符和密码组成的凭证进行身份验证。对于django的默认用户模型，用户标识符是用户名，对于自定义用户模型，它是由username_字段指定的字段（请参见 Customizing Users and authentication ）
它还处理为定义的默认权限模型 User 和 PermissionsMixin .
has_perm() ， get_all_permissions() ， get_user_permissions() 和 get_group_permissions() 允许将对象作为对象特定权限的参数传递，但此后端除了返回空权限集外，不实现这些权限，如果 obj is not None .
with_perm() 还允许对象作为参数传递，但与其他方法不同，如果 obj is not None 。
Asynchronous version : aauthenticate()
尝试进行身份验证 username 具有 password 通过调用 User.check_password . 如果没有 username 提供了，它尝试从 kwargs 使用密钥 CustomUser.USERNAME_FIELD . 返回经过身份验证的用户或 None .
request 是一个 HttpRequest 可能是 None 如果没有提供给 authenticate() （将其传递到后端）。
aauthenticate() 添加了功能。
Asynchronous version : aget_user_permissions()
返回一组权限字符串 user_obj 拥有自己的用户权限。如果返回空集 is_anonymous 或 is_active 是 False .
aget_user_permissions() 添加了功能。
Asynchronous version : aget_group_permissions()
返回一组权限字符串 user_obj 从所属组的权限中获取。如果返回空集 is_anonymous 或 is_active 是 False .
aget_group_permissions() 添加了功能。
Asynchronous version : aget_all_permissions()
返回一组权限字符串 user_obj 包含用户权限和组权限。如果返回空集 is_anonymous 或 is_active 是 False .
aget_all_permissions() 添加了功能。
Asynchronous version : ahas_perm()
使用 get_all_permissions() 检查是否 user_obj 具有权限字符串 perm . 退换商品 False 如果用户不是 is_active .
ahas_perm() 添加了功能。
Asynchronous version : ahas_module_perms()
返回是否 user_obj 对应用程序有任何权限 app_label .
ahas_module_perms() 添加了功能。
返回是否允许用户进行身份验证。以匹配 AuthenticationForm 哪一个 prohibits inactive users from logging in ，此方法返回 False 为用户提供 is_active=False . 自定义用户模型没有 is_active 字段是允许的。
返回拥有该权限的所有活动用户 perm 等形式 "<app label>.<permission codename>" 或者是 Permission instance.如果没有用户拥有 perm found.
如果 is_active 是 True （默认），仅返回活动用户，或者如果 False ，仅返回非活动用户。使用 None 返回所有用户，无论活动状态如何。
如果 include_superusers 是 True （默认），结果将包括超级用户。
等同于 ModelBackend 但它不会拒绝不活动的用户，因为 user_can_authenticate() 总是回报 True .
使用此后端时，您可能希望自定义 AuthenticationForm 用于 LoginView 通过覆盖 confirm_login_allowed() 方法，因为它拒绝不活动的用户。
使用此后端可以利用Django处理的外部身份验证。它使用传入的用户名进行身份验证 request.META['REMOTE_USER'] . 见 Authenticating against REMOTE_USER 文档。
如果您需要更多的控制，可以创建继承自此类的自己的身份验证后端，并重写这些属性或方法：
True 或 False . 确定是否在数据库中创建用户对象（如果尚未创建）默认为 True .
Asynchronous version : aauthenticate()
用户名传递为 remote_user 被认为是值得信赖的。此方法返回具有给定用户名的用户对象，如果 create_unknown_user 是 True 。
返回 None 如果 create_unknown_user 是 False 和A User 在数据库中找不到具有给定用户名的对象。
request 是一个 HttpRequest 可能是 None 如果没有提供给 authenticate() （将其传递到后端）。
aauthenticate() 添加了功能。
Asynchronous version : aconfigure_user()
在每次身份验证尝试时配置用户。获取或创建正在验证的用户后立即调用此方法，并可用于执行自定义设置操作，例如根据PDA目录中的属性设置用户的组。返回用户对象。当从同步上下文调用获取或创建用户时， configure_user 被称为， aconfigure_user 从SEARCH上下文中调用。
设置可以在创建用户时执行一次 (created 是 True )或在现有用户上 (created 是 False )作为在远程和本地系统之间同步属性的一种方式。
request 是一个 HttpRequest 可能是 None 如果没有提供给 authenticate() （将其传递到后端）。
aconfigure_user() 添加了功能。
返回是否允许用户进行身份验证。此方法返回 False 为用户提供 is_active=False . 自定义用户模型没有 is_active 字段是允许的。
等同于 RemoteUserBackend 但它不会拒绝不活动的用户，因为 user_can_authenticate 总是回报 True .
Asynchronous version ： aget_user()
返回与给定的 request 的会议。
它检查存储在会话中的身份验证后端是否存在于 AUTHENTICATION_BACKENDS 。如果是，它使用后端的 get_user() 方法检索用户模型实例，然后通过调用用户模型的 get_session_auth_hash() 方法。如果验证失败，并且 SECRET_KEY_FALLBACKS ，它使用以下命令验证会话： get_session_auth_fallback_hash() 。
返回的实例 AnonymousUser 如果会话中存储的身份验证后端不再位于 AUTHENTICATION_BACKENDS ，如果后端系统没有返回用户 get_user() 方法，或者如果会话身份验证哈希未验证。
5月 28, 2025