django.contrib.auth
¶
本文档为Django的认证系统的组件提供了API参考资料。有关这些组件的使用或如何自定义认证和授权的更多详细信息,请参阅 认证主题指南。
User
模型¶
字段¶
-
class
models.
User
¶ User
对象具有以下字段:-
username
¶ 需要。 150个字符或更少。用户名可以包含字母数字,
_
,@
,+
,.
和-
字符。max_length
应足以满足许多使用情况。如果您需要更长的长度,请使用 自定义用户模型。如果您使用utf8mb4
编码的MySQL(建议使用正确的Unicode支持),最多指定max_length=191
,因为MySQL默认情况下只能创建191个字符的唯一索引。用户名和Unicode
Django最初在用户名中只接受ASCII字母。虽然它不是一个故意的选择,但是当使用Python 3时,Unicode字符始终被接受.Django 1.10在用户名中正式添加了Unicode支持,保留了Python 2的唯一行为,并且使用
User.username_validator
自定义行为。Changed in Django 1.10:max_length
从30个字符增加到150个字符。
-
first_name
¶ 可选的。 30个字符或更少。
-
last_name
¶ 可选的。 30个字符或更少。
-
email
¶ 可选的。电子邮件地址。
-
user_permissions
¶ 与
Permission
的多对多关系
-
is_staff
¶ 布尔值。指定此用户是否可以访问管理网站。
-
is_active
¶ 布尔值。指定此用户帐户是否应被视为活动。我们建议您将此标记设置为
False
,而不是删除帐户;这样,如果你的应用程序有用户的外键,外键不会中断。这不一定控制用户是否可以登录。不需要验证后端来检查
is_active
标志,而是默认后端(ModelBackend
)和RemoteUserBackend
。如果要允许非活动用户登录,可以使用AllowAllUsersModelBackend
或AllowAllUsersRemoteUserBackend
。在这种情况下,您还需要自定义login()
视图使用的AuthenticationForm
,因为它拒绝不活动的用户。请注意,权限检查方法(如has_perm()
和Django admin中的身份验证)都会为非活动用户返回False
。Changed in Django 1.10:在旧版本中,
ModelBackend
和RemoteUserBackend
允许非活动用户进行身份验证。
-
is_superuser
¶ 布尔值。指定此用户具有所有权限,而不显式分配它们。
-
last_login
¶ 用户上次登录的日期时间。
-
date_joined
¶ 创建帐户时指定的日期时间。在创建帐户时默认设置为当前日期/时间。
-
属性¶
-
class
models.
User
-
is_authenticated
¶ 只读属性总是
True
(与总是False
的AnonymousUser.is_authenticated
相对)。这是一种判断用户是否已通过身份验证的方法。这并不意味着任何权限,也不检查用户是否处于活动状态或有效会话。即使通常你会在request.user
上检查这个属性,以确定它是否由AuthenticationMiddleware
填充(代表当前登录的用户),你应该知道这个属性是任何User
实例的True
。Changed in Django 1.10:在旧版本中,这是一种方法。使用它作为方法的向后兼容性支持将在Django 2.0中删除。
-
is_anonymous
¶ 只读属性,始终为
False
。这是区分User
和AnonymousUser
对象的一种方法。一般来说,您应该优先使用is_authenticated
此属性。Changed in Django 1.10:在旧版本中,这是一种方法。使用它作为方法的向后兼容性支持将在Django 2.0中删除。
-
username_validator
¶ - New in Django 1.10.
指向用于验证用户名的验证器实例。默认为Python 3上的
validators.UnicodeUsernameValidator
和Python 2上的validators.ASCIIUsernameValidator
。要更改默认用户名验证器,您可以对
User
模型进行子类化,并将此属性设置为不同的验证器实例。例如,在Python 3上使用ASCII用户名:from django.contrib.auth.models import User from django.contrib.auth.validators import ASCIIUsernameValidator class CustomUser(User): username_validator = ASCIIUsernameValidator() class Meta: proxy = True # If no new field is added.
-
方法¶
-
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_group_permissions
(obj=None)¶ 通过用户的组返回用户拥有的一组权限字符串。
如果传入
obj
,则仅返回此特定对象的组权限。
-
get_all_permissions
(obj=None)¶ 通过组和用户权限返回用户拥有的一组权限字符串。
如果传入
obj
,则只返回此特定对象的权限。
-
has_perm
(perm, obj=None)¶ 如果用户具有指定的权限,则返回
True
,其中perm的格式为"<app label>.<permission codename>"
。 (参见 权限 的文档)。如果用户处于非活动状态,则此方法将始终返回False
。如果传递
obj
,此方法将不检查模型的权限,但是检查此特定对象。
-
has_perms
(perm_list, obj=None)¶ 如果用户具有每个指定的权限,则返回
True
,其中每个perm的格式为"<app label>.<permission codename>"
。如果用户处于非活动状态,则此方法将始终返回False
。如果传递
obj
,此方法将不检查模型的权限,但是检查特定对象的权限。
-
has_module_perms
(package_name)¶ 如果用户在给定包(Django应用标签)中有任何权限,则返回
True
。如果用户处于非活动状态,则此方法将始终返回False
。
-
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, password, **extra_fields)¶ 与
create_user()
相同,但将is_staff
和is_superuser
设置为True
。
-
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
。groups
和user_permissions
总是空的。set_password()
,check_password()
,save()
和delete()
产生NotImplementedError
。
实际上,您可能不需要自己使用 AnonymousUser
对象,但是它们被Web请求使用,如下一节所述。
Permission
模型¶
-
class
models.
Permission
¶
字段¶
Permission
对象具有以下字段:
方法¶
Permission
对象具有类似任何其他 Django模型 的标准数据访问方法。
Group
模型¶
-
class
models.
Group
¶
字段¶
Group
对象具有以下字段:
-
class
models.
Group
-
name
¶ 需要。 80个字符或更少。允许任何字符。示例:
'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
¶ - New in Django 1.10.
只允许ASCII字母的字段验证器,除了
@
,.
,+
,-
和_
。 Python 2上的User.username
的默认验证器。
-
class
validators.
UnicodeUsernameValidator
¶ - New in Django 1.10.
允许Unicode字母的字段验证器,除了
@
,.
,+
,-
和_
。 Python 3上的User.username
的默认验证器。
登录和注销信号¶
auth框架使用以下 信号,可用于在用户登录或注销时通知。
-
user_logged_in
()¶ 当用户成功登录时发送。
与此信号一起发送的参数:
sender
刚刚登录的用户的类。
request
当前
HttpRequest
实例。user
刚刚登录的用户实例。
-
user_logged_out
()¶ 在调用logout方法时发送。
sender
如上所述:刚刚注销的用户的类或者如果用户未经身份验证,则为
None
。request
当前
HttpRequest
实例。user
刚刚注销的用户实例或
None
(如果用户未通过身份验证)。
-
user_login_failed
()¶ 当用户登录失败时发送
sender
用于认证的模块的名称。
credentials
包含传递给
authenticate()
或您自己的自定义身份验证后端的用户凭据的关键字参数字典。与一组“敏感”模式(包括密码)匹配的凭据将不会作为信号的一部分以明文形式发送。
身份验证后端¶
本节详细介绍了Django提供的身份验证后端。有关如何使用它们以及如何编写自己的身份验证后端的信息,请参阅 用户认证指南 的 其他认证源部分。
可用的身份验证后端¶
django.contrib.auth.backends
中提供了以下后端:
-
class
ModelBackend
¶ 这是Django使用的默认身份验证后端。它使用由用户标识符和密码组成的凭证进行认证。对于Django的默认用户模型,用户标识符是用户名,对于自定义用户模型,它是USERNAME_FIELD指定的字段(请参阅 自定义用户和身份验证)。
它还处理为
User
和PermissionsMixin
定义的默认权限模型。has_perm()
,get_all_permissions()
,get_user_permissions()
和get_group_permissions()
允许将对象作为对象特定权限的参数传递,但是这个后端不会实现它们,除非返回一组空的权限,如果obj is not None
。-
authenticate
(username=None, password=None, **kwargs)¶ 尝试通过调用
User.check_password
来验证username
与password
。如果没有提供username
,它尝试使用密钥CustomUser.USERNAME_FIELD
从kwargs
获取用户名。返回已认证的用户或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
(self, user_obj, app_label)¶ 返回
user_obj
是否对应用程序app_label
具有任何权限。
-
user_can_authenticate
()¶ - New in Django 1.10.
返回是否允许用户进行身份验证。为了匹配
prohibits inactive users from logging in
的AuthenticationForm
的行为,该方法为具有is_active=False
的用户返回False
。允许没有is_active
字段的自定义用户模型。
-
-
class
AllowAllUsersModelBackend
¶ - New in Django 1.10.
与
ModelBackend
相同,除了它不拒绝不活动的用户,因为user_can_authenticate()
总是返回True
。使用此后端时,您可能希望通过覆盖
confirm_login_allowed()
方法来定制login()
视图使用的AuthenticationForm
,因为它拒绝不活动的用户。
-
class
RemoteUserBackend
¶ 使用此后端可利用外部到Django处理的身份验证。它使用在
request.META['REMOTE_USER']
中传递的用户名进行身份验证。请参阅 正在针对REMOTE_USER进行验证 文档。如果您需要更多的控制,您可以创建自己的身份验证后端,继承此类,并覆盖这些属性或方法:
-
RemoteUserBackend.
create_unknown_user
¶ True
或False
。确定是否已创建用户对象(如果尚未在数据库中)默认为True
。
-
RemoteUserBackend.
authenticate
(remote_user)¶ 作为
remote_user
传递的用户名被认为是可信的。此方法简单地返回具有给定用户名的用户对象,如果create_unknown_user
是True
,则创建新的用户对象。如果
create_unknown_user
是False
,则返回None
,并且在数据库中找不到具有给定用户名的User
对象。
-
RemoteUserBackend.
clean_username
(username)¶ 在使用
username
获取或创建用户对象之前,在username
上执行任何清除(例如,清除LDAP DN信息)。返回已清除的用户名。
-
RemoteUserBackend.
configure_user
(user)¶ 配置新创建的用户。此方法在创建新用户后立即调用,并可用于执行自定义设置操作,例如根据LDAP目录中的属性设置用户的组。返回用户对象。
-
RemoteUserBackend.
user_can_authenticate
()¶ - New in Django 1.10.
返回是否允许用户进行身份验证。此方法为具有
is_active=False
的用户返回False
。允许没有is_active
字段的自定义用户模型。
-
class
AllowAllUsersRemoteUserBackend
¶ - New in Django 1.10.
与
RemoteUserBackend
相同,除了它不拒绝不活动的用户,因为user_can_authenticate
总是返回True
。
效用函数¶
-
get_user
(request)¶ 返回与给定
request
的会话关联的用户模型实例。它检查存储在会话中的认证后端是否存在于
AUTHENTICATION_BACKENDS
中。如果是这样,它使用后端的get_user()
方法来检索用户模型实例,然后通过调用用户模型的get_session_auth_hash()
方法来验证会话。如果存储在会话中的身份验证后端不再位于
AUTHENTICATION_BACKENDS
中,如果用户未由后端的get_user()
方法返回,或者会话认证散列未验证,则返回AnonymousUser
的实例。