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
)。电子邮件地址。
-
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)¶ 如果给定的原始字符串是用户的正确密码,返回
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_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
。
- id 总是
在实践中,你可能不需要自己使用 AnonymousUser
对象,但它们会被 Web 请求使用,下一节会解释。
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
¶ 一个为所有所需方法提供默认实现的基类。默认情况下,它将拒绝任何用户并不提供任何权限。
-
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
中prohibits 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_active
为True
(默认),则只返回活跃用户,如果False
,则只返回非活跃用户。使用None
返回所有用户,无论其是否处于活跃状态。如果
include_superusers
为True
(默认),结果将包括超级用户。
-
-
class
AllowAllUsersModelBackend
¶ 与
ModelBackend
一样,只是它不会拒绝非活动用户,因为user_can_authenticate()
总是返回True
。当使用这个后台时,你可能会想要自定义
AuthenticationForm
所使用的LoginView
,通过覆盖confirm_login_allowed()
方法,因为它拒绝非活动用户。
-
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
获取或创建用户对象之前,对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
的实例。