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
)。电子邮件地址。
- password¶
Required. A hash of, and metadata about, the password. (Django doesn't store the raw password.) Raw passwords can be arbitrarily long and can contain any character. The metadata in this field may mark the password as unusable. See the password documentation.
- 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()¶
Marks the user as having no password set by updating the metadata in the
password
field. This isn't the same as having a blank string for a password.check_password()
for this user will never returnTrue
. Doesn't save theUser
object.如果针对现有外部源(例如 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()
将被调用。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()
函数已添加。