django.contrib.auth

该文档提供了 Django 认证系统组件的 API 。有关更多这些组件的用例，或需要自定义认证与鉴权，请参阅 认证主题指南。

User 模型

class models.User

字段

class models.User

User 对象有如下字段：

• username

  必要的。150 个字符或以下。用户名可包含字母数字、_、@、+、. 和 - 字符。

  max_length 对许多使用情况来说应该是足够的。如果你需要更长的长度，请使用 自定义用户模型。如果你使用的 MySQL 是 utf8mb4 编码（推荐用于适当的 Unicode 支持），最多指定 max_length=191，因为在这种情况下，MySQL 默认只能创建 191 个字符的唯一索引。

• first_name

  可选的（blank=True）。150 个字符或更少。

• last_name

  可选的（blank=True）。150 个字符或更少。

• email

  可选的（blank=True）。电子邮件地址。

• password

  需要。一个密码的哈希值和元数据。（Django 不存储原始密码。）原始密码可以任意长，可以包含任何字符。参见 密码文档。

• groups

  多对多关系到 Group

• user_permissions

  多对多关系到 Permission

• is_staff

  Boolean. Allows this user to access the admin site.

• is_active

  Boolean. Marks this user account as active. We recommend that you set this flag to False instead of deleting accounts. That way, if your applications have any foreign keys to users, the foreign keys won’t break.

  这不一定能控制用户是否能登录。认证后端不一定需要检查 is_active 标志，但默认的后端（ModelBackend）和 RemoteUserBackend 会检查。如果你想允许不活跃的用户登录，你可以使用 AllowAllUsersModelBackend 或者 AllowAllUsersRemoteUserBackend。在这种情况下，你还需要自定义 AuthenticationForm 所使用的 LoginView，因为它拒绝非活动用户。需要注意的是， has_perm() 等权限检查方法，以及 Django 管理中的认证方法，都会对非活跃用户返回 False。

• is_superuser

  Boolean. Treats this user as having all permissions without assigning any permission to it in particular.

• last_login

  用户最后一次登录的日期时间。

• date_joined

  The date/time when the account was created.

属性

class models.User

• is_authenticated

  只读属性，始终返回 True （匿名用户 AnonymousUser.is_authenticated 始终返回 False ）。这是一种判断用户是否已通过身份认证的方法。这并不意味着任何权限，也不会检查用户是否处于活动状态或是否具有有效会话。即使通常你会根据 request.user 检查这个属性，以确定它是否被 AuthenticationMiddleware 填充（表示当前登录的用户），但是你应该知道该属性对于任何 User 实例都返回 True。

• is_anonymous

  只读属性，总是 False。这是区分 User 和 AnonymousUser 对象的一种方式。一般来说，你应该优先使用 is_authenticated 来代替这个属性。

方法

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)

• acheck_password(raw_password)

  Asynchronous version: acheck_password()

  如果给定的原始字符串是用户的正确密码，返回 True。（密码哈希值用于比较）

  Changed in Django 5.0:

  acheck_password() method was added.

• set_unusable_password()

  标记该用户没有设置密码。 check_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，这个方法不会检查模型的权限，而是检查这个特定对象的权限。

• has_perms(perm_list, obj=None)

  如果用户拥有指定的每个权限，返回 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 都会传递给底层的 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=None, password=None, **extra_fields)

  与 create_user() 相同，但将 is_staff 和 is_superuser 设置为 True。

• with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)

  返回拥有给定权限 perm 的用户，可以是 "<app label>.<permission codename>" 格式，也可以是 Permission 实例。如果没有找到拥有 perm 的用户，返回一个空的查询集。

  如果 is_active 为 True （默认），则只返回活跃用户，如果 False，则只返回非活跃用户。使用 None 返回所有用户，无论其是否处于活跃状态。

  如果 include_superusers 为 True （默认），结果将包括超级用户。

  如果传入了 backend，并且在 AUTHENTICATION_BACKENDS 中定义了，那么本方法将使用它。否则，它将使用 AUTHENTICATION_BACKENDS 中的 backend，如果只有一个的话，或者引发一个异常。

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。
• group 和 user_permissions 总是空的。
• set_password()、check_password()、save() 和 delete() 引发 NotImplementedError。

在实践中，你可能不需要自己使用 AnonymousUser 对象，但它们会被网络请求使用，在下一节中解释。

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

  要求： 150 个字符或以下。允许使用任何字符。例如：'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

除了 @、.、+、- 和 _ 之外，只允许使用 ASCII 字母和数字的字段验证器。

class validators.UnicodeUsernameValidator

除了 @、.、+、- 和 _ 之外，还允许使用 Unicode 字符的字段验证器。User.username 的默认验证器。

登录和注销的信号

认证框架使用了以下的 信号，可以在用户登录或退出时用于通知。

user_logged_in

当用户成功登录时发送。

用此信号发送的参数：

• sender

  刚刚登录的用户的类。

  request

  当前的 HttpRequest 实例。

  user

  刚刚登录的用户的实例。

user_logged_out

调用注销方法时发送。

• sender

  如上所述：刚刚注销的用户的类，如果用户没有经过认证，则为 None。

  request

  当前的 HttpRequest 实例。

  user

  刚刚注销的用户实例，如果用户没有经过认证，则为 None。

user_login_failed

当用户未能成功登录时发送

• sender

  用于认证的模块名称。

  credentials

  一个包含关键字参数的字典，其中包含传递给 authenticate() 或你自己的自定义认证后端的用户凭证。匹配一组“敏感的”模式的凭证（包括密码）将不会作为信号的一部分被发送。

  request

  HttpRequest 对象，如果有提供给 authenticate() 对象的话。

认证后端

本节详细介绍了 Django 自带的认证后端。关于如何使用它们以及如何编写你自己的认证后端，请参阅 用户认证指南 中的 其他认证源 部分。

可用的认证后端

在 django.contrib.auth.backends 中可以找到以下后端：

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() 和 get_group_permissions() 来获取 user_obj 所拥有的权限字符串。

• has_perm(user_obj, perm, obj=None)

  使用 get_all_permissions() 检查 user_obj 是否有 perm 的权限字符串。

class ModelBackend

这是 Django 默认使用的认证后端。 它使用由用户标识符和密码组成的凭证进行认证。 对于 Django 的默认用户模型来说，用户标识符是用户名，对于自定义用户模型来说，它是 USERNAME_FIELD 指定的字段（参见 自定义用户和身份认证）。

它还处理了为 User 和 PermissionsMixin 定义的默认权限模型。

has_perm()、 get_all_permissions()、 get_user_permissions() 和 get_group_permissions() 允许将对象作为参数传递给特定对象的权限，但除了在 obj is not None 的情况下返回一个空的权限集外，这个后端并没有实现它们。

with_perm() 也允许传递一个对象作为参数，但与其他方法不同的是，如果 obj is not None，则返回一个空的查询集。

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

  通过调用 User.check_password 尝试用 password 认证 username。如果没有提供 username，则尝试使用键 CustomUser.USERNAME_FIELD 从 kwargs 中获取一个用户名。返回一个已认证的用户或 None。

  request 是一个 HttpRequest，如果没有提供给 authenticate() （将其传递给后端），则可能是 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(user_obj, app_label)

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

• user_can_authenticate()

  返回是否允许用户进行认证。为了与 AuthenticationForm 中 prohibits inactive users from logging in 的行为相匹配，对于有 is_active=False 的用户，本方法返回 False。允许没有 is_active 字段的自定义用户模型。

• with_perm(perm, is_active=True, include_superusers=True, obj=None)

  返回所有拥有 perm 权限的活跃用户，可以是 "<app label>.<permission codename>" 的形式，也可以是 Permission 实例。如果没有找到拥有 perm 权限的用户，则返回一个空的查询集。

  如果 is_active 为 True （默认），则只返回活跃用户，如果 False，则只返回非活跃用户。使用 None 返回所有用户，无论其是否处于活跃状态。

  如果 include_superusers 为 True （默认），结果将包括超级用户。

class AllowAllUsersModelBackend

与 ModelBackend 一样，只是它不会拒绝非活动用户，因为 user_can_authenticate() 总是返回 True。

当使用这个后台时，你可能会想要自定义 AuthenticationForm 所使用的 LoginView，通过覆盖 confirm_login_allowed() 方法，因为它拒绝非活动用户。

class RemoteUserBackend

使用这个后端来利用外部对 Django 处理的认证。 它使用 request.META[‘REMOTE_USER’] 中传递的用户名进行认证。 参见 认证 REMOTE_USER 文档。

如果你需要更多的控制，你可以创建自己的认证后端，继承这个类，并覆盖这些属性或方法：

• create_unknown_user

  True 或 False。确定如果数据库中没有用户对象，是否创建用户对象。默认为 True。

• authenticate(request, remote_user)

  作为 remote_user 传递的用户名被认为是可信的。如果 create_unknown_user 为 True，则该方法返回给定用户名的用户对象，创建一个新的用户对象。

  如果 create_unknown_user 为 False，且数据库中没有找到给定用户名的 User 对象，则返回 None。

  request 是一个 HttpRequest，如果没有提供给 authenticate() （将其传递给后端），则可能是 None。

• clean_username(username)

  在使用 username 获取或创建用户对象之前，对 username 进行任何清理（例如剥离 LDAP DN 信息）。返回清理后的用户名。

• configure_user(request, user, created=True)

  Configures the user on each authentication attempt. This method is called immediately after fetching or creating the user being authenticated, and can be used to perform custom setup actions, such as setting the user’s groups based on attributes in an LDAP directory. Returns the user object.

  The setup can be performed either once when the user is created (created is True) or on existing users (created is False) as a way of synchronizing attributes between the remote and the local systems.

  request 是一个 HttpRequest，如果没有提供给 authenticate() （将其传递给后端），则可能是 None。

• user_can_authenticate()

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

class AllowAllUsersRemoteUserBackend

与 RemoteUserBackend 相同，只是它不会拒绝非活动用户，因为 user_can_authenticate 总是返回 True。

实用工具函数

get_user(request)

aget_user(request)

Asynchronous version: aget_user()

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

It checks if the authentication backend stored in the session is present in AUTHENTICATION_BACKENDS. If so, it uses the backend’s get_user() method to retrieve the user model instance and then verifies the session by calling the user model’s get_session_auth_hash() method. If the verification fails and SECRET_KEY_FALLBACKS are provided, it verifies the session against each fallback key using get_session_auth_fallback_hash().

如果存储在会话中的认证后端不再在 AUTHENTICATION_BACKENDS 中，如果后端的 get_user() 方法没有返回用户，或者会话认证的哈希没有认证，则返回一个 AnonymousUser 的实例。

Changed in Django 4.1.8:

Fallback verification with SECRET_KEY_FALLBACKS was added.

Changed in Django 5.0:

aget_user() function was added.