Skip to main content

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

可选的。电子邮件地址。

password

需要。密码的哈希和元数据。 (Django不存储原始密码。)原始密码可以任意长,并且可以包含任何字符。见 密码文档

groups

Group 的多对多关系

user_permissions

Permission 的多对多关系

is_staff

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

is_active

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

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

Changed in Django 1.10:

在旧版本中,ModelBackendRemoteUserBackend 允许非活动用户进行身份验证。

is_superuser

布尔值。指定此用户具有所有权限,而不显式分配它们。

last_login

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

date_joined

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

属性

class models.User
is_authenticated

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

Changed in Django 1.10:

在旧版本中,这是一种方法。使用它作为方法的向后兼容性支持将在Django 2.0中删除。

is_anonymous

只读属性,始终为 False。这是区分 UserAnonymousUser 对象的一种方法。一般来说,您应该优先使用 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_passwordNone 时,密码将设置为不可用的密码,如同使用 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_emailNone,Django使用 DEFAULT_FROM_EMAIL。任何 **kwargs 都被传递给底层的 send_mail() 调用。

管理器方法

class models.UserManager

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

create_user(username, email=None, password=None, **extra_fields)

创建,保存和返回 User

usernamepassword 设置为给定。 email 的域部分自动转换为小写,返回的 User 对象将 is_active 设置为 True

如果没有提供密码,将调用 set_unusable_password()

extra_fields 关键字参数传递到 User__init__ 方法,以允许在 自定义用户模型 上设置任意字段。

有关使用示例,请参阅 创建用户

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

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

AnonymousUser 对象

class models.AnonymousUser

django.contrib.auth.models.AnonymousUser 是实现 django.contrib.auth.models.User 接口的类,具有以下区别:

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

Permission 模型

class models.Permission

字段

Permission 对象具有以下字段:

class models.Permission
name

需要。 255个字符或更少。示例:'Can vote'

content_type

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

codename

需要。 100个字符或更少。示例:'can_vote'

方法

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指定的字段(请参阅 自定义用户和身份验证)。

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

has_perm()get_all_permissions()get_user_permissions()get_group_permissions() 允许将对象作为对象特定权限的参数传递,但是这个后端不会实现它们,除非返回一组空的权限,如果 obj is not None

authenticate(username=None, password=None, **kwargs)

尝试通过调用 User.check_password 来验证 usernamepassword。如果没有提供 username,它尝试使用密钥 CustomUser.USERNAME_FIELDkwargs 获取用户名。返回已认证的用户或 None

get_user_permissions(user_obj, obj=None)

返回 user_obj 从其自己的用户权限中获取的一组权限字符串。如果 is_anonymousis_activeFalse,则返回空集。

get_group_permissions(user_obj, obj=None)

从它们所属的组的权限返回 user_obj 具有的一组权限字符串。如果 is_anonymousis_activeFalse,则返回空集。

get_all_permissions(user_obj, obj=None)

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

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 inAuthenticationForm 的行为,该方法为具有 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

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

RemoteUserBackend.authenticate(remote_user)

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

如果 create_unknown_userFalse,则返回 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 的实例。