django.contrib.auth
¶这份文档提供Django 认证系统组件的API 参考资料。 对于这些组件的用法以及如何自定义认证和授权请参照authentication topic guide。
User
模型¶models.
User
¶User
对象具有如下字段:
username
¶必选。 150个字符以内。 用户名可能包含字母数字,_
,@
,+
.
和-
个字符。
对于许多用例,max_length
应该是足够的。 如果您需要较长的长度,请使用custom user model。 如果您使用具有utf8mb4
编码(推荐用于正确的Unicode支持)的MySQL,请至少指定max_length=191
,因为MySQL只能创建具有191个字符的唯一索引,默认。
用户名和Unicode
Django最初只接受用户名中的ASCII字母和数字。 虽然这不是一个故意的选择,Unicode字符一直被接受使用Python 3时。 Django 1.10在用户名中正式添加了Unicode支持,在Python 2中保留了仅适用于ASCII的行为,可以使用User.username_validator
自定义行为的选项。
max_length
从30个字符增加到150个字符。
first_name
¶可选(blank=True
)。 少于等于30个字符。
last_name
¶可选(blank=True
)。 少于等于30个字符。
email
¶可选(blank=True
)。 邮箱地址。
password
¶必选。 密码的哈希及元数据。 (Django 不保存原始密码)。 原始密码可以无限长而且可以包含任意字符。 参见password documentation。
user_permissions
¶与Permission
之间的多对多关系。
is_staff
¶布尔值。 指示用户是否可以访问Admin 站点。
is_active
¶布尔值。 指示用户的账号是否激活。 我们建议您将此标志设置为False
而不是删除帐户;这样,如果您的应用程序对用户有任何外键,则外键不会中断。
它不是用来控制用户是否能够登录。
不需要验证后端来检查is_active
标志,而是默认后端(ModelBackend
)和RemoteUserBackend
。 如果要允许非活动用户登录,您可以使用AllowAllUsersModelBackend
或AllowAllUsersRemoteUserBackend
。 在这种情况下,您还需要自定义LoginView
使用的AuthenticationForm
,因为它拒绝了非活动用户。 请注意,诸如has_perm()
等权限检查方法,Django管理员中的身份验证全部返回为非活动用户的False
。
在旧版本中,ModelBackend
和RemoteUserBackend
允许非活动用户进行身份验证。
is_superuser
¶布尔值。 指定这个用户拥有所有的权限而不需要给他们分配明确的权限。
last_login
¶用户最后一次登录的时间。
date_joined
¶账户创建的时间。 当账号创建时,默认设置为当前的date/time。
models.
User
is_authenticated
¶始终为True
(与AnonymousUser.is_authenticated
相对,始终为False
)的只读属性。 这是区分用户是否已经认证的一种方法。 这并不表示任何权限,也不会检查用户是否处于活动状态或是否具有有效的会话。 即使正常情况下,您将在request.user
上检查此属性,以了解它是否已由AuthenticationMiddleware
填充(表示当前登录的用户),您应该知道对于任何User
实例,此属性为True
。
在旧版本中,这是一种方法。 使用它作为方法的向后兼容性支持将在Django 2.0中被删除。
不要使用is
操作符进行比较!
为了允许is_authenticated
和is_anonymous
属性也可以作为方法,属性是CallableBool
对象。 因此,直到Django 2.0中的弃用期结束为止,您不能使用is
运算符来比较这些属性。 也就是说,request.user.is_authenticated is True
总是求值得False
。
is_anonymous
¶始终为False
的只读属性。 这是区别User
和AnonymousUser
对象的一种方法。 一般来说,您应该优先使用is_authenticated
到此属性。
在旧版本中,这是一种方法。 使用它作为方法的向后兼容性支持将在Django 2.0中被删除。
username_validator
¶指向用于验证用户名的验证器实例。 Python 3上的默认值为validators.UnicodeUsernameValidator
和Python 3上的validators.ASCIIUsernameValidator
。
要更改默认用户名验证器,可以将User
模型子类化,并将此属性设置为不同的验证器实例。 例如,要在Python 3上使用ASCII用户名:
from django.contrib.auth.models import 用户
from django.contrib.auth.validators import ASCIIUsernameValidator
class CustomUser(User):
username_validator = ASCIIUsernameValidator()
class Meta:
proxy = True # If no new field is added.
models.
User
get_username
()¶返回这个User 的username。 由于可以将User
模型交换出来,您应该使用此方法,而不是直接引用用户名属性。
get_full_name
()¶返回first_name
和last_name
,之间带有一个空格。
get_short_name
()¶返回first_name
。
set_password
(raw_password)¶设置用户的密码为给定的原始字符串,并负责密码的哈希。 不会保存User
对象。
当None
为raw_password
时,密码将设置为一个不可用的密码,和使用set_unusable_password()
的效果一样。
check_password
(raw_password)¶Returns True
if the given raw string is the correct password for the user. (它负责在比较时密码的哈希)。
set_unusable_password
()¶标记用户为没有设置密码。 它与密码为空的字符串不一样。
check_password()
对这种用户永远不会返回True
。 不会保存User
对象。
如果你的认证发生在外部例如LDAP 目录时,可能需要这个函数。
has_usable_password
()¶如果对这个用户调用过set_unusable_password()
,则返回False
。
get_group_permissions
(obj=None)¶返回一个用户当前拥有的权限的set,通过用户组
如果传入obj
,则仅返回此特定对象的组权限。http://python.usyiyi.cn/translate/django_182/ref/contrib/auth.html#
get_all_permissions
(obj=None)¶通过组和用户权限返回用户拥有的一组权限字符串。
如果传入obj
,则仅返回此特定对象的权限。
has_perm
(perm, obj=None)¶如果用户具有指定的权限,则返回True
,其中perm的格式为"<app label>.<permission codename>"
。 (请参阅有关permissions)。 如果用户没有激活,这个方法将永远返回 False
。
如果传入obj
,此方法将不会检查模型的权限,而是检查此特定对象。
has_perms
(perm_list, obj=None)¶Returns True
if the user has each of the specified permissions,
where each perm is in the format
"<app label>.<permission codename>"
. 如果用户没有激活,这个方法将永远返回 False
。
如果传入obj
,此方法将不会检查模型的权限,而是检查特定对象。
has_module_perms
(package_name)¶如果用户具有给出的package_name(Django应用的标签)中的任何一个权限,则返回True
。 如果用户没有激活,这个方法将永远返回False
。
email_user
(subject, message, from_email=None, **kwargs)¶发生邮件给这个用户。 如果None
为from_email
,Django 将使用DEFAULT_FROM_EMAIL
。 任何**kwargs
都将传递给底层的send_mail()
调用。
models.
UserManager
¶User
模型有一个自定义的管理器,它具有以下辅助方法(除了BaseUserManager
提供的方法之外):
create_user
(username, email=None, password=None, **extra_fields)¶创建、保存并返回一个User
。
username
和password
设置为给出的值。 email
的域名部分将自动转换成小写,返回的User
对象将设置is_active
为True
。
如果没有提供password,将调用 set_unusable_password()
。
The extra_fields
keyword arguments are passed through to the
User
’s __init__
method to
allow setting arbitrary fields on a custom user model.
参见Creating users 中的示例用法。
create_superuser
(username, email, password, **extra_fields)¶与create_user()
相同,但是设置is_staff
和is_superuser
为True
。
AnonymousUser
对象¶models.
AnonymousUser
¶django.contrib.auth.models.AnonymousUser
类实现了django.contrib.auth.models.User
接口,但具有下面几个不同点:
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
模型¶models.
Permission
¶Permission
对象有以下字段:
Permission
对象具有类似任何其他Django model的标准数据访问方法。
Group
模型¶models.
Group
¶Group
对象有以下字段:
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()
validators.
ASCIIUsernameValidator
¶仅允许使用ASCII字母和数字的字段验证器,除@
之外, .
,+
,-
和_
。 Python 2上的User.username
的默认验证器。
validators.
UnicodeUsernameValidator
¶允许Unicode字符的字段验证器,除@
之外, .
,+
,-
和_
。 Python 3上的User.username
的默认验证器。
auth框架使用以下signals,可用于在用户登录或注销时通知。
user_logged_in
()¶当用户成功登录时发送。
与此信号一起发送的参数:
sender
request
HttpRequest
实例。user
user_logged_out
()¶在调用logout方法时发送。
sender
None
,如果用户未通过身份验证。request
HttpRequest
实例。user
None
。user_login_failed
()¶当用户登录失败时发送
sender
credentials
authenticate()
或您自己的自定义身份验证后端的用户凭据的关键字参数的字典。 匹配一组“敏感”模式(包括密码)的凭证不会作为信号的一部分发送到清除中。request
HttpRequest
对象,如果提供给authenticate()
。添加了request
参数。
这一节详细讲述Django自带的认证后端。 关于如何使用它们以及如何编写你自己的认证后端,参见用户认证指南中的其它认证源一节。
以下是django.contrib.auth.backends
中可以使用的后端:
ModelBackend
¶这是Django使用的默认认证后台。 它使用由用户标识和密码组成的凭据进行认证。 对于Django的默认用户模型,用户的标识是用户名,对于自定义的用户模型,它通过USERNAME_FIELD 字段表示(参见Customizing Users and authentication)。
它还处理 User
和PermissionsMixin
定义的权限模型。
has_perm()
, get_all_permissions()
, get_user_permissions()
, 和get_group_permissions()
允许一个对象作为特定权限参数来传递, 如果条件是 if obj is not None
. 后端除了返回一个空的permissions 外,并不会去完成他们。
authenticate
(request, username=None, password=None, **kwargs)¶通过调用User.check_password
验证password
和username
。 如果kwargs
没有提供,它会使用CustomUser.USERNAME_FIELD
关键字从username
中获取username。 返回一个认证过的User 或None
。
request
is an HttpRequest
and may be None
if it wasn’t provided to authenticate()
(which passes it on to the backend).
添加了request
参数。
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
()¶返回是否允许用户进行身份验证。 To match the
behavior of AuthenticationForm
which prohibits inactive users from logging in
,
this method returns False
for users with is_active=False
. 不允许使用is_active
字段的自定义用户模型。
AllowAllUsersModelBackend
¶与ModelBackend
相同,但是不会拒绝非激活的用户,因为user_can_authenticate()
始终返回True
。
使用此后端时,你可能会需要覆盖confirm_login_allowed()
方法来自定义LoginView
使用的AuthenticationForm
,因为它拒绝了非激活的用户。
RemoteUserBackend
¶使用这个后端来处理Django的外部认证。 它使用在request.META['REMOTE_USER']
中传递的用户名进行身份验证。 请参阅REMOTE_USER的认证文档。
如果你需要更多的控制,你可以创建你自己的验证后端,继承这个类,并重写这些属性或方法:
RemoteUserBackend.
create_unknown_user
¶True
或False
。 确定是否创建用户对象(如果尚未在数据库中)默认为True
。
RemoteUserBackend.
authenticate
(request, remote_user)¶作为remote_user
传递的用户名被认为是可信的。 此方法只需返回具有给定用户名的用户对象,如果create_unknown_user
为True
则创建新的用户对象。
如果create_unknown_user
是User
,并且在数据库中找不到具有给定用户名的None
对象,则返回False
。
request
is an HttpRequest
and may be None
if
it wasn’t provided to authenticate()
(which
passes it on to the backend).
RemoteUserBackend.
clean_username
(username)¶在使用它获取或创建用户对象之前,请对username
执行任何清除(例如剥离LDAP DN信息)。 返回已清除的用户名。
RemoteUserBackend.
configure_user
(user)¶配置新创建的用户。 此方法在创建新用户后立即调用,并可用于执行自定义设置操作,例如根据LDAP目录中的属性设置用户的组。 返回用户对象。
RemoteUserBackend.
user_can_authenticate
()¶返回是否允许用户进行身份验证。 对于is_active=False
的用户,此方法返回False
。 不允许使用is_active
字段的自定义用户模型。
AllowAllUsersRemoteUserBackend
¶与ModelBackend
相同,但是不会拒绝非激活的用户,因为user_can_authenticate()
始终返回True
。
get_user
(request)[source]¶返回与给定的request
会话关联的用户模型实例。
它检查存储在会话中的身份验证后端是否存在于AUTHENTICATION_BACKENDS
中。 如果是这样,它使用后端的get_user()
方法来检索用户模型实例,然后通过调用用户模型的get_session_auth_hash()
方法验证会话。
如果存储在会话中的身份验证后端不再在AUTHENTICATION_BACKENDS
中返回AnonymousUser
的实例,如果后端的get_user()
2017年9月6日