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 个字符或更少。
- last_name¶
可选的(
blank=True
)。150 个字符或更少。
- email¶
可选的(
blank=True
)。电子邮件地址。
- 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
。这是区分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)¶
- acheck_password(raw_password)¶
异步版本:
acheck_password()
如果给定的原始字符串是用户的正确密码,返回
True
。(密码哈希值用于比较)Changed in Django 5.0:acheck_password()
方法已添加。
- set_unusable_password()¶
通过更新
password
字段中的元数据,将用户标记为未设置密码。这与密码为空字符串不同。此用户的check_password()
永远不会返回True
。不会保存User
对象。如果针对现有外部源(例如 LDAP 目录)进行应用程序的身份认证,则可能需要这个功能。
密码重置限制
用户如果使用不可用的密码,将无法通过
PasswordResetView
请求密码重置电子邮件。
- 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_email
是None
,Django 使用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()
将被调用。If no email is provided,
email
will be set to an empty string.extra_fields
关键字参数被传递到User
的__init__
方法中,允许在 自定义用户模型 上设置任意字段。使用方法参见 创建用户。
- create_superuser(username, email=None, password=None, **extra_fields)¶
与
create_user()
相同,但将is_staff
和is_superuser
设置为True
。
- with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)¶
返回拥有给定权限
perm
的用户,可以是"<app label>.<permission codename>"
格式,也可以是Permission
实例。如果没有找到拥有perm
的用户,返回一个空的查询集。如果
is_active
为True
(默认),则只返回活跃用户,如果False
,则只返回非活跃用户。使用None
返回所有用户,无论其是否处于活跃状态。如果
include_superusers
为True
(默认),结果将包括超级用户。如果传入了
backend
,并且在AUTHENTICATION_BACKENDS
中定义了,那么本方法将使用它。否则,它将使用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
。group
和user_permissions
总是空的。set_password()
、check_password()
、save()
和delete()
引发NotImplementedError
。
在实践中,你可能不需要自己使用 AnonymousUser
对象,但它们会被网络请求使用,在下一节中解释。
Permission
模型¶
- class models.Permission¶
字段¶
Permission
对象有以下字段:
方法¶
Permission
对象和其他 Django 模型 一样拥有标准的数据访问方法。
Group
模型¶
- class models.Group¶
字段¶
Group
对象有以下字段:
- class models.Group
- name¶
要求: 150 个字符或以下。允许使用任何字符。例如:
'Awesome Users'
。
- permissions¶
多对多字段到
Permission
: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[source]¶
一个为所有所需方法提供默认实现的基类。默认情况下,它将拒绝任何用户并不提供任何权限。
- get_all_permissions(user_obj, obj=None)[source]¶
使用
get_user_permissions()
和get_group_permissions()
来获取user_obj
所拥有的权限字符串。
- has_perm(user_obj, perm, obj=None)[source]¶
使用
get_all_permissions()
检查user_obj
是否有perm
的权限字符串。
- class ModelBackend[source]¶
这是 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)[source]¶
通过调用
User.check_password
尝试用password
认证username
。如果没有提供username
,则尝试使用键CustomUser.USERNAME_FIELD
从kwargs
中获取一个用户名。返回一个已认证的用户或None
。request
是一个HttpRequest
,如果没有提供给authenticate()
(将其传递给后端),则可能是None
。
- get_user_permissions(user_obj, obj=None)[source]¶
从他们自己的用户权限中返回
user_obj
拥有的权限字符串集。如果is_anonymous
或is_active
是False
,则返回空集。
- get_group_permissions(user_obj, obj=None)[source]¶
从他们自己的用户权限中返回
user_obj
拥有的权限字符串集。如果is_anonymous
或is_active
是False
,则返回空集。
- get_all_permissions(user_obj, obj=None)[source]¶
从他们自己的用户权限中返回
user_obj
拥有的权限字符串集。如果is_anonymous
或is_active
是False
,则返回空集。
- has_perm(user_obj, perm, obj=None)[source]¶
使用
get_all_permissions()
检查user_obj
是否有perm
的权限。如果用户没有is_active
,则返回False
。
- user_can_authenticate()[source]¶
返回是否允许用户进行认证。为了与
AuthenticationForm
中prohibits inactive users from logging in
的行为相匹配,对于有is_active=False
的用户,本方法返回False
。允许没有is_active
字段的自定义用户模型。
- with_perm(perm, is_active=True, include_superusers=True, obj=None)[source]¶
返回所有拥有
perm
权限的活跃用户,可以是"<app label>.<permission codename>"
的形式,也可以是Permission
实例。如果没有找到拥有perm
权限的用户,则返回一个空的查询集。如果
is_active
为True
(默认),则只返回活跃用户,如果False
,则只返回非活跃用户。使用None
返回所有用户,无论其是否处于活跃状态。如果
include_superusers
为True
(默认),结果将包括超级用户。
- class AllowAllUsersModelBackend[source]¶
与
ModelBackend
一样,只是它不会拒绝非活动用户,因为user_can_authenticate()
总是返回True
。当使用这个后台时,你可能会想要自定义
AuthenticationForm
所使用的LoginView
,通过覆盖confirm_login_allowed()
方法,因为它拒绝非活动用户。
- class RemoteUserBackend[source]¶
使用这个后端来利用外部对 Django 处理的认证。 它使用
request.META['REMOTE_USER']
中传递的用户名进行认证。 参见 认证 REMOTE_USER 文档。如果你需要更多的控制,你可以创建自己的认证后端,继承这个类,并覆盖这些属性或方法:
- create_unknown_user¶
True
或False
。确定如果数据库中没有用户对象,是否创建用户对象。默认为True
。
- authenticate(request, remote_user)[source]¶
作为
remote_user
传递的用户名被认为是可信的。如果create_unknown_user
为True
,则该方法返回给定用户名的用户对象,创建一个新的用户对象。如果
create_unknown_user
为False
,且数据库中没有找到给定用户名的User
对象,则返回None
。request
是一个HttpRequest
,如果没有提供给authenticate()
(将其传递给后端),则可能是None
。
- clean_username(username)[source]¶
在使用
username
获取或创建用户对象之前,对username
进行任何清理(例如剥离 LDAP DN 信息)。返回清理后的用户名。
- configure_user(request, user, created=True)[source]¶
在每次认证尝试中配置用户。此方法在获取或创建要认证的用户后立即调用,可用于执行自定义设置操作,例如根据 LDAP 目录中的属性设置用户的组。返回用户对象。
可以在用户创建时执行设置(
created
为True
)或在现有用户上执行设置(created
为False
),以在远程和本地系统之间同步属性。request
是一个HttpRequest
,如果没有提供给authenticate()
(将其传递给后端),则可能是None
。
- user_can_authenticate()¶
返回是否允许用户进行身份认证。对于有
is_active=False
的用户,本方法返回False
。允许没有is_active
字段的自定义用户模型。
- class AllowAllUsersRemoteUserBackend[source]¶
与
RemoteUserBackend
相同,只是它不会拒绝非活动用户,因为user_can_authenticate
总是返回True
。
实用工具函数¶
- aget_user(request)¶
异步版本:
aget_user()
返回与给定
request
的会话相关联的用户模型实例。它会检查会话中存储的身份验证后端是否存在于
AUTHENTICATION_BACKENDS
中。如果存在,它将使用后端的get_user()
方法来检索用户模型实例,然后通过调用用户模型的get_session_auth_hash()
方法来验证会话。如果验证失败并且提供了SECRET_KEY_FALLBACKS
,它将使用get_session_auth_fallback_hash()
来对会话进行每个后备密钥的验证。如果存储在会话中的认证后端不再在
AUTHENTICATION_BACKENDS
中,如果后端的get_user()
方法没有返回用户,或者会话认证的哈希没有认证,则返回一个AnonymousUser
的实例。Changed in Django 5.0:aget_user()
函数已添加。