django.contrib.auth

本文档提供了Django认证系统组件的API参考资料。 有关这些组件的使用情况或如何自定义身份验证和授权的详细信息,请参阅authentication topic guide

User模型

领域¶ T0>

楷模。用户 T0> ¶ T1>

User objects have the following fields:

用户名 T0> ¶ T1>

需要。 150个字符或更少。 用户名可能包含字母数字,_@+ . -个字符。

max_length应该足够用于许多用例。 如果您需要更长的时间,请使用custom user model 如果你使用MySQL的utf8mb4编码(推荐用于正确的Unicode支持),最多指定max_length=191,因为MySQL只能创建191个字符的唯一索引默认。

用户名和Unicode

Django最初只接受用户名中的ASCII字母和数字。 尽管这不是一个有意的选择,但在使用Python 3时,Unicode字符总是被接受。 Django 1.10在用户名中正式添加了Unicode支持,在Python 2上保留了纯ASCII的行为,可以使用User.username_validator自定义行为。

如first_name T0> ¶ T1>

可选(blank=True)。 30个字符或更少。

姓氏 T0> ¶ T1>

可选(blank=True)。 150个字符或更少。

在Django 2.0中更改:

max_length从30个字符增加到150个字符。

电子邮件 T0> ¶ T1>

可选(blank=True)。 电子邮件地址。

密码 T0> ¶ T1>

需要。 密码的散列和元数据。 (Django不存储原始密码。) 原始密码可以是任意长的,可以包含任何字符。 请参阅password documentation

基 T0> ¶ T1>

Group的多对多关系

user_permissions T0> ¶ T1>

Permission的多对多关系

is_staff T0> ¶ T1>

布尔。 指定此用户是否可以访问管理站点。

IS_ACTIVE T0> ¶ T1>

布尔。 指定此用户帐户是否应被视为活动。 我们建议您将此标志设置为False,而不是删除帐户;这样,如果你的应用程序有任何外键给用户,外键不会中断。

这不一定控制用户是否可以登录。 验证后端不需要检查is_active标志,而是默认的后端(ModelBackend)和RemoteUserBackend 如果您希望允许非活动用户登录,则可以使用AllowAllUsersModelBackendAllowAllUsersRemoteUserBackend 在这种情况下,您还需要自定义LoginView使用的AuthenticationForm,因为它拒绝不活动的用户。 请注意,非活动用户的权限检查方法(如has_perm())和Django admin中的身份验证均返回False

is_superuser T0> ¶ T1>

布尔。 指定该用户具有所有权限而不明确分配它们。

LAST_LOGIN T0> ¶ T1>

用户上次登录的日期时间。

date_joined T0> ¶ T1>

指定帐户何时创建的日期时间。 帐户创建时默认设置为当前日期/时间。

属性¶ T0>

楷模。用户
is_authenticated T0> ¶ T1>

总是True的只读属性(与AnonymousUser.is_authenticated永远是False相反)。 这是一种判断用户是否被认证的方法。 这并不意味着任何权限,也不会检查用户是否处于活动状态或具有有效的会话。 即使你通常会在request.user上检查这个属性,以确定它是否已经被AuthenticationMiddleware(代表当前登录的用户)填充,你应该知道对于任何User实例,这个属性是True

is_anonymous T0> ¶ T1>

总是False的只读属性。 这是区分UserAnonymousUser对象的一种方法。 通常,您应该更喜欢使用is_authenticated来使用此属性。

username_validator T0> ¶ T1>

指向用于验证用户名的验证程序实例。 默认为validators.UnicodeUsernameValidator

要更改默认的用户名验证器,您可以对User模型进行子类化,并将此属性设置为不同的验证器实例。 例如,要使用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.

方法¶ T0>

楷模。用户
get_username T0>()¶ T1>

返回用户的用户名。 由于User模型可以被换出,您应该使用此方法而不是直接引用username属性。

get_full_name T0>()¶ T1>

返回first_name加上last_name,两者之间有空格。

get_short_name T0>()¶ T1>

返回first_name

set_password T0>( raw_password T1>)¶ T2>

将用户的密码设置为给定的原始字符串,注意密码散列。 不保存User对象。

When the raw_password is None, the password will be set to an unusable password, as if set_unusable_password() were used.

check_password T0>( raw_password T1>)¶ T2>

如果给定的原始字符串是用户的正确密码,则返回True (这在做比较时需要密码哈希处理。)

set_unusable_password T0>()¶ T1>

标记用户没有设置密码。 这与密码的空白字符串不一样。 这个用户的check_password()永远不会返回True 不保存User对象。

如果您的应用程序的身份验证是针对现有的外部源(例如LDAP目录)进行的,则可能需要此操作。

has_usable_password T0>()¶ T1>

如果为此用户调用了set_unusable_password(),则返回False

get_group_permissions T0>( OBJ =无 T1>)¶ T2>

通过他们的组返回一组用户拥有的权限字符串。

如果传入obj,则只返回此特定对象的组权限。

get_all_permissions T0>( OBJ =无 T1>)¶ T2>

通过组和用户权限返回用户拥有的一组权限字符串。

如果传入obj,则只会返回此特定对象的权限。

has_permpermobj = None

如果用户具有指定权限,则返回True,其中perm的格式为“< app 标签>。<权限 代号>“中 T5> T2>。 (请参阅permissions的文档)。 如果用户处于非活动状态,则此方法将始终返回False

如果传入obj,则此方法不会检查模型的权限,而是检查此特定对象的权限。

has_permsperm_listobj = 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 T0>(程序包 T1>)¶ T2>

如果用户在给定包(Django应用程序标签)中有任何权限,则返回True 如果用户处于非活动状态,则此方法将始终返回False

email_user(subject, message, from_email=None, **kwargs)

发送电子邮件给用户。 如果from_emailNone,Django将使用DEFAULT_FROM_EMAIL 任何**kwargs被传递给底层的send_mail()调用。

经理方法

楷模。的UserManager T0> ¶ T1>

User模型具有一个自定义管理器,它具有以下辅助方法(除BaseUserManager提供的方法外):

create_userusernameemail = Nonepassword = None** extra_fields¶ T5>

创建,保存并返回一个User

usernamepassword设置为给定。 The domain portion of email is automatically converted to lowercase, and the returned User object will have is_active set to True.

If no password is provided, set_unusable_password() will be called.

extra_fields关键字参数传递给User__init__方法,以允许在custom user model

例如Creating users

create_superuser(username, email, password, **extra_fields)

create_user()相同,但将is_staffis_superuser设置为True

AnonymousUser对象

楷模。 AnonymousUser T0> ¶ T1>

django.contrib.auth.models.AnonymousUser是实现django.contrib.auth.models.User接口的类,具有以下不同之处:

实际上,您可能不需要自己使用AnonymousUser对象,但是它们被Web请求使用,如下一节所述。

Permission model

楷模。权限 T0> ¶ T1>

领域¶ T0>

Permission objects have the following fields:

楷模。允许
名称 T0> ¶ T1>

需要。 255个字符或更少。 例如:'可以 投票'

CONTENT_TYPE T0> ¶ T1>

需要。 django_content_type数据库表的引用,其中包含每个已安装模型的记录。

代号 T0> ¶ T1>

需要。 不超过100个字符 例如:'can_vote'

方法¶ T0>

Permission objects have the standard data-access methods like any other Django model.

Group模型

楷模。组 T0> ¶ T1>

领域¶ T0>

Group objects have the following fields:

楷模。
名称 T0> ¶ T1>

需要。 不超过80个字符 任何字符都是允许的。 例如:'Awesome 用户的

权限 T0> ¶ T1>

多对多字段Permission

group.permissions.set([permission_list])
group.permissions.add(permission, permission, ...)
group.permissions.remove(permission, permission, ...)
group.permissions.clear()

验证¶ T0>

验证。 ASCIIUsernameValidator T0> ¶ T1>

只允许ASCII字母和数字的字段验证器,除了@之外, .+-_

验证。 UnicodeUsernameValidator T0> ¶ T1>

除了@之外,允许Unicode字符的字段验证程序 .+-_ User.username的默认验证器。

登录和注销信号

auth框架使用下面的signals,当用户登录或注销时可用于通知。

user_logged_in()

当用户登录成功时发送。

使用此信号发送的参数:

sender
刚刚登录的用户的类。
request
当前的HttpRequest实例。
user
刚刚登录的用户实例。
user_logged_out()

当注销方法被调用时发送。

寄件人
如上所述:刚刚注销的用户的类,或者如果用户没有被认证,那么None
请求
当前的HttpRequest实例。
用户
刚刚注销的用户实例,或者如果用户未经过身份验证,则None
user_login_failed()

当用户登录失败时发送

寄件人
用于身份验证的模块的名称。
证书
包含传递给authenticate()或您自己的自定义身份验证后端的用户凭据的关键字参数字典。 与一组“敏感”模式(包括密码)相匹配的证书将不会以清晰的方式作为信号的一部分发送。
请求
HttpRequest对象(如果提供给authenticate())。
在Django 1.11中更改:

添加了request参数。

认证后端

本节详细介绍了Django附带的身份验证后端。 有关如何使用它们以及如何编写自己的身份验证后端的信息,请参阅User authentication guideOther authentication sources section

可用的身份验证后端

以下后端可在django.contrib.auth.backends中使用:

ModelBackend T0> ¶ T1>

这是Django使用的默认身份验证后端。 它使用由用户标识符和密码组成的凭证进行身份验证。 对于Django的默认用户模型,用户标识符是用户名,对于自定义用户模型,它是USERNAME_FIELD指定的字段(请参阅Customizing Users and authentication)。

它还处理为UserPermissionsMixin定义的默认权限模型。

has_perm(), get_all_permissions(), get_user_permissions(), and get_group_permissions() allow an object to be passed as a parameter for object-specific permissions, but this backend does not implement them other than returning an empty set of permissions if obj is not None.

验证请求用户名=无密码=无** kwargs¶ T5>

尝试通过调用User.check_password来用password验证username 如果没有提供username,它将尝试使用CustomUser.USERNAME_FIELD键从kwargs中获取用户名。 返回认证用户或None

request is an HttpRequest and may be None if it wasn’t provided to authenticate() (which passes it on to the backend).

在Django 1.11中更改:

添加了request参数。

get_user_permissionsuser_objobj = None

返回user_obj拥有的自己的用户权限的权限字符串集。 如果is_anonymousis_activeFalse,则返回空集。

get_group_permissionsuser_objobj = None

返回user_obj从其所属组的权限中获得的权限字符串集合。 如果is_anonymousis_activeFalse,则返回空集。

get_all_permissionsuser_objobj = None

返回user_obj具有的一组权限字符串,包括用户权限和组权限。 如果is_anonymousis_activeFalse,则返回空集。

has_permuser_objpermobj = None

使用get_all_permissions()来检查user_obj是否具有权限字符串perm 如果用户不是is_active,则返回False

has_module_permsuser_objapp_label

返回user_obj是否对app app_label具有任何权限。

user_can_authenticate T0>()¶ T1>

返回是否允许用户进行身份验证。 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 T0> ¶ T1>

ModelBackend相同,只是它不会拒绝不活动的用户,因为user_can_authenticate()总是返回True

当使用这个后端时,你可能想通过重写confirm_login_allowed()方法来自定义LoginView使用的AuthenticationForm用户。

RemoteUserBackend T0> ¶ T1>

使用这个后端来利用外部到Django处理的认证。 它使用在request.META['REMOTE_USER']中传递的用户名进行身份验证。 请参阅Authenticating against REMOTE_USER文档进行身份验证。

如果您需要更多的控制权,您可以创建自己的身份验证后端,从此类继承并覆盖这些属性或方法:

RemoteUserBackend。 create_unknown_user T0> ¶ T1>

TrueFalse 确定是否创建了用户对象(如果尚未在数据库中),则默认为True

RemoteUserBackend。验证请求remote_user

作为remote_user传递的用户名被认为是可信的。 这个方法只是简单地返回给定用户名的用户对象,如果create_unknown_userTrue则创建一个新的用户对象。

如果create_unknown_userFalse,并且在数据库中找不到具有给定用户名的User对象,则返回None

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 T0>(用户名 T1>)¶ T2>

在使用它来获取或创建用户对象之前,对username执行任何清理(例如剥离LDAP DN信息)。 返回已清除的用户名。

RemoteUserBackend。 configure_user T0>(用户 T1>)¶ T2>

配置一个新创建的用户。 在创建新用户后立即调用此方法,并可用于执行自定义设置操作,例如根据LDAP目录中的属性设置用户的组。 返回用户对象。

RemoteUserBackend。 user_can_authenticate T0>()¶ T1>

返回是否允许用户进行身份验证。 对于is_active=False的用户,此方法返回False 自定义用户模型没有is_active字段是允许的。

AllowAllUsersRemoteUserBackend T0> ¶ T1>

RemoteUserBackend相同,只是它不会拒绝不活动的用户,因为user_can_authenticate总是返回True

工具函数

get_user(request)[source]

返回与给定request的会话关联的用户模型实例。

它检查存储在会话中的认证后端是否存在于AUTHENTICATION_BACKENDS中。 如果是,则使用后端的get_user()方法来检索用户模型实例,然后通过调用用户模型的get_session_auth_hash()方法来验证会话。

Returns an instance of AnonymousUser if the authentication backend stored in the session is no longer in AUTHENTICATION_BACKENDS, if a user isn’t returned by the backend’s get_user() method, or if the session auth hash doesn’t validate.