django.contrib.auth
class models.``User
class models.``User
对象有如下字段:
username
必要的。150 个字符或以下。用户名可包含字母数字、
_
、@
、+
、.
和-
字符。max_length
对许多使用情况来说应该是足够的。如果你需要更长的长度,请使用 自定义用户模型。如果你使用的 MySQL 是utf8mb4
编码(推荐用于适当的 Unicode 支持),最多指定max_length=191
,因为在这种情况下,MySQL 默认只能创建 191 个字符的唯一索引。first_name
可选的()。150 个字符或更少。
Changed in Django 3.1:
max_length
从 30 个字符增加到 150 个字符。last_name
可选的(
blank=True
)。150 个字符或更少。email
可选的()。电子邮件地址。
password
需要。一个密码的哈希值和元数据。(Django 不存储原始密码。)原始密码可以任意长,可以包含任何字符。参见 密码文档。
groups
多对多关系到
user_permissions
多对多关系到
Permission
is_staff
布尔型。指定该用户是否可以访问管理站点。
is_active
布尔值。指定该用户账户是否应该被视为活跃账户。我们建议你把这个标志设置为
False
,而不是删除账户;这样,如果你的应用程序对用户有任何外键,外键就不会被破坏。这不一定能控制用户是否能登录。认证后端不一定需要检查
is_active
标志,但默认的后端()和RemoteUserBackend
会检查。如果你想允许不活跃的用户登录,你可以使用 或者AllowAllUsersRemoteUserBackend
。在这种情况下,你还需要自定义 所使用的LoginView
,因为它拒绝非活动用户。需要注意的是,has_perm()
等权限检查方法,以及 Django 管理中的认证方法,都会对非活跃用户返回False
。is_superuser
布尔值。指定该用户拥有所有权限,而不用一个个开启权限。
date_joined
指定账户创建时间的日期时间。帐户创建时,默认设置为当前日期/时间。
属性
class models.``User
is_authenticated
只读属性,始终返回
True
(匿名用户AnonymousUser.is_authenticated
始终返回False
)。这是一种判断用户是否已通过身份认证的方法。这并不意味着任何权限,也不会检查用户是否处于活动状态或是否具有有效会话。即使通常你会根据request.user
检查这个属性,以确定它是否被 填充(表示当前登录的用户),但是你应该知道该属性对于任何User
实例都返回True
。is_anonymous
只读属性,总是
False
。这是区分 和AnonymousUser
对象的一种方式。一般来说,你应该优先使用 来代替这个属性。
class models.``User
get_username
()返回用户的用户名。由于
User
模型可以被替换,你应该使用这个方法而不是直接引用用户名属性。get_full_name
()返回
first_name
加上 ,中间有一个空格。get_short_name
()返回
first_name
。set_password
(raw_password)将用户的密码设置为给定的原始字符串,并进行密码哈希处理。不保存 对象。
当
raw_password
为None
时,密码将被设置为不可用的密码,就像set_unusable_password()
一样。check_password
(raw_password)如果给定的原始字符串是用户的正确密码,返回
True
。(密码哈希值用于比较)set_unusable_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
,这个方法不会检查模型的权限,而是检查这个特定对象的权限。-
如果用户拥有指定的每个权限,返回
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
都会传递给底层的 调用。
管理器方法
class models.``UserManager
User
模型有一个自定义管理器,它有以下辅助方法(除了 BaseUserManager
提供的方法外):
create_user
(username, email=None, password=None, \*extra_fields*)创建、保存并返回一个
User
。和
password
按给定设置。 的域名部分会自动转换为小写,返回的User
对象的 设置为True
。如果没有提供密码,
set_unusable_password()
将被调用。extra_fields
关键字参数被传递到 的__init__
方法中,允许在 自定义用户模型 上设置任意字段。使用方法参见 。
create_superuser
(username, email=None, password=None, \*extra_fields*)与
create_user()
相同,但将 和is_superuser
设置为True
。with_perm
(perm, is_active=True, include_superusers=True, backend=None, obj=None)返回拥有给定权限
perm
的用户,可以是"<app label>.<permission codename>"
格式,也可以是 实例。如果没有找到拥有perm
的用户,返回一个空的查询集。如果
is_active
为True
(默认),则只返回活跃用户,如果False
,则只返回非活跃用户。使用None
返回所有用户,无论其是否处于活跃状态。如果
include_superusers
为True
(默认),结果将包括超级用户。如果传入了
backend
,并且在AUTHENTICATION_BACKENDS
中定义了,那么本方法将使用它。否则,它将使用 中的backend
,如果只有一个的话,或者引发一个异常。
AnonymousUser
对象
class models.``AnonymousUser
django.contrib.auth.models.AnonymousUser
是一个实现了 接口的类,有这些区别:
- id 总是
None
。 - 总是空字符串。
get_username()
总是返回空字符串。- 是
True
而不是False
。 is_authenticated
是False
而不是True
。- 和
is_superuser
总是False
。 group
和 总是空的。set_password()
、、save()
和 引发NotImplementedError
。
在实践中,你可能不需要自己使用 对象,但它们会被 Web 请求使用,下一节会解释。
class models.``Permission
Permission
对象有以下字段:
class models.``Permission
name
必要的。255 个字符或以下。例如:
'Can vote'
。content_type
必要的。对
django_content_type
数据库表的引用,该表包含每个已安装模型的记录。codename
必要的。100 个字符或以下。例如:
'can_vote'
。
方法
对象和其他 Django 模型 一样拥有标准的数据访问方法。
Group
模型
class models.``Group
对象有以下字段:
class models.``Group
name
要求: 150 个字符或以下。允许使用任何字符。例如:
'Awesome Users'
。permissions
多对多字段到
Permission
:
class validators.``ASCIIUsernameValidator
除了 @
、.
、+
、-
和 _
之外,只允许使用 ASCII 字母和数字的字段验证器。
class validators.``UnicodeUsernameValidator
除了 @
、.
、+
、-
和 _
之外,还允许使用 Unicode 字符的字段验证器。User.username
的默认验证器。
登录和注销的信号
认证框架使用了以下的 ,可以在用户登录或退出时用于通知。
user_logged_in
()
当用户成功登录时发送。
用此信号发送的参数:
sender
刚刚登录的用户的类。
request
当前的
HttpRequest
实例。user
刚刚登录的用户的实例。
user_logged_out
()
调用注销方法时发送。
sender
如上所述:刚刚注销的用户的类,如果用户没有经过认证,则为
None
。request
当前的 实例。
user
刚刚注销的用户实例,如果用户没有经过认证,则为
None
。
user_login_failed
()
当用户未能成功登录时发送
-
用于认证的模块名称。
credentials
一个包含关键字参数的字典,其中包含传递给
authenticate()
或你自己的自定义认证后端的用户凭证。匹配一组“敏感的”模式的凭证(包括密码)将不会作为信号的一部分被发送。request
对象,如果有提供给
authenticate()
对象的话。
本节详细介绍了 Django 自带的认证后端。关于如何使用它们以及如何编写你自己的认证后端,请参阅 中的 其他认证源 部分。
可用的认证后端
在 中可以找到以下后端:
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()
和 来获取user_obj
所拥有的权限字符串。(user_obj, perm, obj=None)
使用
get_all_permissions()
检查user_obj
是否有perm
的权限字符串。
class ModelBackend
这是 Django 默认使用的认证后端。 它使用由用户标识符和密码组成的凭证进行认证。 对于 Django 的默认用户模型来说,用户标识符是用户名,对于自定义用户模型来说,它是 USERNAME_FIELD 指定的字段(参见 )。
它还处理了为 User
和 定义的默认权限模型。
has_perm()
、 、 get_user_permissions()
和 允许将对象作为参数传递给特定对象的权限,但除了在 obj is not None
的情况下返回一个空的权限集外,这个后端并没有实现它们。
with_perm()
也允许传递一个对象作为参数,但与其他方法不同的是,如果 obj is not None
,则返回一个空的查询集。
authenticate
(request, username=None, password=None, \*kwargs*)通过调用 尝试用
password
认证username
。如果没有提供username
,则尝试使用键CustomUser.USERNAME_FIELD
从kwargs
中获取一个用户名。返回一个已认证的用户或None
。request
是一个 ,如果没有提供给authenticate()
(将其传递给后端),则可能是None
。get_user_permissions
(user_obj, obj=None)从他们自己的用户权限中返回
user_obj
拥有的权限字符串集。如果 或is_active
是False
,则返回空集。get_group_permissions
(user_obj, obj=None)从他们自己的用户权限中返回
user_obj
拥有的权限字符串集。如果 或is_active
是False
,则返回空集。get_all_permissions
(user_obj, obj=None)从他们自己的用户权限中返回
user_obj
拥有的权限字符串集。如果 或is_active
是False
,则返回空集。has_perm
(user_obj, perm, obj=None)使用 检查
user_obj
是否有perm
的权限。如果用户没有is_active
,则返回False
。has_module_perms
(user_obj, app_label)返回
user_obj
是否对应用app_label
具有任何权限。user_can_authenticate
()返回是否允许用户进行认证。为了与 中
prohibits inactive users from logging in
的行为相匹配,对于有 的用户,本方法返回False
。允许没有is_active
字段的自定义用户模型。with_perm
(perm, is_active=True, include_superusers=True, obj=None)返回所有拥有
perm
权限的活跃用户,可以是"<app label>.<permission codename>"
的形式,也可以是 实例。如果没有找到拥有perm
权限的用户,则返回一个空的查询集。如果
is_active
为True
(默认),则只返回活跃用户,如果False
,则只返回非活跃用户。使用None
返回所有用户,无论其是否处于活跃状态。如果
include_superusers
为True
(默认),结果将包括超级用户。
class AllowAllUsersModelBackend
与 ModelBackend
一样,只是它不会拒绝非活动用户,因为 总是返回 True
。
当使用这个后台时,你可能会想要自定义 AuthenticationForm
所使用的 ,通过覆盖 confirm_login_allowed()
方法,因为它拒绝非活动用户。
class RemoteUserBackend
使用这个后端来利用外部对 Django 处理的认证。 它使用 中传递的用户名进行认证。 参见 认证 REMOTE_USER 文档。
如果你需要更多的控制,你可以创建自己的认证后端,继承这个类,并覆盖这些属性或方法:
create_unknown_user
True
或False
。确定如果数据库中没有用户对象,是否创建用户对象。默认为True
。authenticate
(request, remote_user)作为
remote_user
传递的用户名被认为是可信的。如果 为True
,则该方法返回给定用户名的用户对象,创建一个新的用户对象。如果
create_unknown_user
为False
,且数据库中没有找到给定用户名的User
对象,则返回None
。request
是一个 ,如果没有提供给authenticate()
(将其传递给后端),则可能是None
。clean_username
(username)在使用
username
获取或创建用户对象之前,对username
进行任何清理(例如剥离 LDAP DN 信息)。返回清理后的用户名。configure_user
(request, user)配置一个新创建的用户。 这个方法在新用户创建后立即被调用,可以用来执行自定义设置操作,例如根据 LDAP 目录中的属性设置用户的组。返回用户对象。
request
是一个 ,如果没有提供给authenticate()
(将其传递给后端),则可能是None
。
class AllowAllUsersRemoteUserBackend
与 相同,只是它不会拒绝非活动用户,因为 user_can_authenticate
总是返回 True
。
实用工具函数
get_user
(request)
返回与给定 request
的会话相关联的用户模型实例。
它检查会话中存储的认证后端是否存在于 中。如果存在,它使用后端的 get_user()
方法检索用户模型实例,然后通过调用用户模型的 get_session_auth_hash()
方法来认证会话。