--- title: "django.contrib.auth" version: 5.2 locale: zh-hans source: https://docs.djangoproject.com/zh-hans/5.2/ref/contrib/auth/ canonical: https://djangodocs.dev/zh-hans/5.2/ref/contrib/auth/ --- # `django.contrib.auth` 该文档提供了 Django 认证系统组件的 API 。有关更多这些组件的用例，或需要自定义认证与鉴权，请参阅 [认证主题指南](/zh-hans/5.2/topics/auth/)。 ## `User` 模型 #### `class models.User` ### 字段 #### `class models.User` [`User`](#django.contrib.auth.models.User) 对象有如下字段： #### `username` 必要的。150 个字符或以下。用户名可包含字母数字、`_`、`@`、`+`、`.` 和 `-` 字符。 The `max_length` should be sufficient for many use cases. If you need a longer length, please use a [custom user model](/zh-hans/5.2/topics/auth/customizing/#specifying-custom-user-model). #### `first_name` 可选的（[`blank=True`](/zh-hans/5.2/ref/models/fields/#django.db.models.Field.blank)）。150 个字符或更少。 #### `last_name` 可选的（[`blank=True`](/zh-hans/5.2/ref/models/fields/#django.db.models.Field.blank)）。150 个字符或更少。 #### `email` 可选的（[`blank=True`](/zh-hans/5.2/ref/models/fields/#django.db.models.Field.blank)）。电子邮件地址。 #### `password` 必需。密码的哈希值和元数据。（Django 不存储原始密码。）原始密码可以是任意长度，并且可以包含任何字符。此字段中的元数据可能会将密码标记为不可用。请参阅 [密码文档](/zh-hans/5.2/topics/auth/passwords/)。 #### `groups` 多对多关系到 [`Group`](#django.contrib.auth.models.Group) #### `user_permissions` 多对多关系到 [`Permission`](#django.contrib.auth.models.Permission) #### `is_staff` 布尔值。允许此用户访问管理站点。 #### `is_active` 布尔值。将此用户帐户标记为活动。我们建议您将此标志设置为 `False` 而不是删除帐户。这样，如果您的应用程序有任何对用户的外键引用，外键就不会断开。 这不一定能控制用户是否能登录。认证后端不一定需要检查 `is_active` 标志，但默认的后端（[`ModelBackend`](#django.contrib.auth.backends.ModelBackend)）和 [`RemoteUserBackend`](#django.contrib.auth.backends.RemoteUserBackend) 会检查。如果你想允许不活跃的用户登录，你可以使用 [`AllowAllUsersModelBackend`](#django.contrib.auth.backends.AllowAllUsersModelBackend) 或者 [`AllowAllUsersRemoteUserBackend`](#django.contrib.auth.backends.AllowAllUsersRemoteUserBackend)。在这种情况下，你还需要自定义 [`AuthenticationForm`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.forms.AuthenticationForm) 所使用的 `LoginView`，因为它拒绝非活动用户。需要注意的是， [`has_perm()`](#django.contrib.auth.models.User.has_perm) 等权限检查方法，以及 Django 管理中的认证方法，都会对非活跃用户返回 `False`。 #### `is_superuser` 布尔值。将此用户视为拥有所有权限，而不会分配任何特定的权限。 #### `last_login` 用户最后一次登录的日期时间。 #### `date_joined` 帐户创建的日期/时间。 ### 属性 #### `class models.User` #### `is_authenticated` 只读属性，始终返回 `True` （匿名用户 `AnonymousUser.is_authenticated` 始终返回 `False` ）。这是一种判断用户是否已通过身份认证的方法。这并不意味着任何权限，也不会检查用户是否处于活动状态或是否具有有效会话。即使通常你会根据 `request.user` 检查这个属性，以确定它是否被 [`AuthenticationMiddleware`](/zh-hans/5.2/ref/middleware/#django.contrib.auth.middleware.AuthenticationMiddleware) 填充（表示当前登录的用户），但是你应该知道该属性对于任何 [`User`](#django.contrib.auth.models.User) 实例都返回 `True`。 #### `is_anonymous` 只读属性，总是 `False`。这是区分 [`User`](#django.contrib.auth.models.User) 和 [`AnonymousUser`](#django.contrib.auth.models.AnonymousUser) 对象的一种方式。一般来说，你应该优先使用 [`is_authenticated`](#django.contrib.auth.models.User.is_authenticated) 来代替这个属性。 ### 方法 #### `class models.User` #### `get_username()` 返回用户的用户名。由于 `User` 模型可以被替换，你应该使用这个方法而不是直接引用用户名属性。 #### `get_full_name()` 返回 [`first_name`](#django.contrib.auth.models.User.first_name) 加上 [`last_name`](#django.contrib.auth.models.User.last_name)，中间有一个空格。 #### `get_short_name()` 返回 [`first_name`](#django.contrib.auth.models.User.first_name)。 #### `set_password(raw_password)` 将用户的密码设置为给定的原始字符串，并进行密码哈希处理。不保存 [`User`](#django.contrib.auth.models.User) 对象。 当 `raw_password` 为 `None` 时，密码将被设置为不可用的密码，就像 [`set_unusable_password()`](#django.contrib.auth.models.User.set_unusable_password) 一样。 #### `check_password(raw_password)` #### `acheck_password(raw_password)` *异步版本*：`acheck_password()` 如果给定的原始字符串是用户的正确密码，返回 `True`。（密码哈希值用于比较） #### `set_unusable_password()` 通过更新 [`password`](#django.contrib.auth.models.User.password) 字段中的元数据，将用户标记为未设置密码。这与密码为空字符串不同。此用户的 [`check_password()`](#django.contrib.auth.models.User.check_password) 永远不会返回 `True`。不会保存 [`User`](#django.contrib.auth.models.User) 对象。 如果针对现有外部源（例如 LDAP 目录）进行应用程序的身份认证，则可能需要这个功能。 > **密码重置限制** > > 用户如果使用不可用的密码，将无法通过 [`PasswordResetView`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.views.PasswordResetView) 请求密码重置电子邮件。 #### `has_usable_password()` 如果 `set_unusable_password()` 被调用，返回 `False`。 #### `get_user_permissions(obj=None)` #### `aget_user_permissions(obj=None)` *Asynchronous version*: `aget_user_permissions()` 返回用户直接拥有的一组权限字符串。 如果传入了 `obj`，则只返回这个特定对象的用户权限。 > **Changed in Django 5.2** > > `aget_user_permissions()` method was added. #### `get_group_permissions(obj=None)` #### `aget_group_permissions(obj=None)` *Asynchronous version*: `aget_group_permissions()` 返回用户通过他们的组拥有的一组权限字符串。 如果传入了 `obj`，则只返回这个特定对象的组权限。 > **Changed in Django 5.2** > > `aget_group_permissions()` method was added. #### `get_all_permissions(obj=None)` #### `aget_all_permissions(obj=None)` *Asynchronous version*: `aget_all_permissions()` 返回用户拥有的一组权限字符串，包括通过组和用户的权限。 如果传入了 `obj`，则只返回这个特定对象的权限。 > **Changed in Django 5.2** > > `aget_all_permissions()` method was added. #### `has_perm(perm, obj=None)` #### `ahas_perm(perm, obj=None)` *Asynchronous version*: `ahas_perm()` 如果用户拥有指定的权限，返回 `True`，其中 perm 的格式是 `"."`。（参见 [权限](/zh-hans/5.2/topics/auth/default/#topic-authorization) 的文档）。如果用户是不活跃的，这个方法将总是返回 `False`。对于活跃的超级用户，本方法将始终返回 `True`。 如果传入了 `obj`，这个方法不会检查模型的权限，而是检查这个特定对象的权限。 > **Changed in Django 5.2** > > `ahas_perm()` method was added. #### `has_perms(perm_list, obj=None)` #### `ahas_perms(perm_list, obj=None)` *Asynchronous version*: `ahas_perms()` 如果用户拥有指定的每个权限，返回 `True`，其中每个 perm 的格式为 `"."`。如果用户不活跃，本方法将总是返回 `False`。对于活跃的超级用户，本方法将始终返回 `True`。 如果传入了 `obj`，这个方法不会检查模型的权限，而是检查这个特定对象的权限。 > **Changed in Django 5.2** > > `ahas_perms()` method was added. #### `has_module_perms(package_name)` #### `ahas_module_perms(package_name)` *Asynchronous version*: `ahas_module_perms()` 如果用户在给定的包（Django 应用标签）中有任何权限，则返回 `True`。如果用户不活跃，本方法将总是返回 `False`。如果是活跃的超级用户，本方法将始终返回 `True`。 > **Changed in Django 5.2** > > `ahas_module_perms()` method was added. #### `email_user(subject, message, from_email=None, **kwargs)` Sends an email to the user. If `from_email` is `None`, Django uses the [`DEFAULT_FROM_EMAIL`](/zh-hans/5.2/ref/settings/#std-setting-DEFAULT_FROM_EMAIL). Any `**kwargs` are passed to the underlying [`send_mail()`](/zh-hans/5.2/topics/email/#django.core.mail.send_mail) call. ### 管理器方法 #### `class models.UserManager` `User` 模型有一个自定义管理器，它有以下辅助方法（除了 `BaseUserManager` 提供的方法外）： #### `create_user(username, email=None, password=None, **extra_fields)` #### `acreate_user(username, email=None, password=None, **extra_fields)` *Asynchronous version*: `acreate_user()` 创建、保存并返回一个 [`User`](#django.contrib.auth.models.User)。 [`username`](#django.contrib.auth.models.User.username) 和 [`password`](#django.contrib.auth.models.User.password) 按给定设置。[`email`](#django.contrib.auth.models.User.email) 的域名部分会自动转换为小写，返回的 [`User`](#django.contrib.auth.models.User) 对象的 [`is_active`](#django.contrib.auth.models.User.is_active) 设置为 `True`。 如果没有提供密码， [`set_unusable_password()`](#django.contrib.auth.models.User.set_unusable_password) 将被调用。 If no email is provided, [`email`](#django.contrib.auth.models.User.email) will be set to an empty string. `extra_fields` 关键字参数被传递到 [`User`](#django.contrib.auth.models.User) 的 `__init__` 方法中，允许在 [自定义用户模型](/zh-hans/5.2/topics/auth/customizing/#auth-custom-user) 上设置任意字段。 使用方法参见 [创建用户](/zh-hans/5.2/topics/auth/default/#topics-auth-creating-users)。 > **Changed in Django 5.2** > > `acreate_user()` method was added. #### `create_superuser(username, email=None, password=None, **extra_fields)` #### `acreate_superuser(username, email=None, password=None, **extra_fields)` *Asynchronous version*: `acreate_superuser()` 与 [`create_user()`](#django.contrib.auth.models.UserManager.create_user) 相同，但将 [`is_staff`](#django.contrib.auth.models.User.is_staff) 和 [`is_superuser`](#django.contrib.auth.models.User.is_superuser) 设置为 `True`。 > **Changed in Django 5.2** > > `acreate_superuser()` method was added. #### `with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)` 返回拥有给定权限 `perm` 的用户，可以是 `"."` 格式，也可以是 [`Permission`](#django.contrib.auth.models.Permission) 实例。如果没有找到拥有 `perm` 的用户，返回一个空的查询集。 如果 `is_active` 为 `True` （默认），则只返回活跃用户，如果 `False`，则只返回非活跃用户。使用 `None` 返回所有用户，无论其是否处于活跃状态。 如果 `include_superusers` 为 `True` （默认），结果将包括超级用户。 如果传入了 `backend`，并且在 [`AUTHENTICATION_BACKENDS`](/zh-hans/5.2/ref/settings/#std-setting-AUTHENTICATION_BACKENDS) 中定义了，那么本方法将使用它。否则，它将使用 [`AUTHENTICATION_BACKENDS`](/zh-hans/5.2/ref/settings/#std-setting-AUTHENTICATION_BACKENDS) 中的 `backend`，如果只有一个的话，或者引发一个异常。 ## `AnonymousUser` 对象 #### `class models.AnonymousUser` [`django.contrib.auth.models.AnonymousUser`](#django.contrib.auth.models.AnonymousUser) 是一个实现了 [`django.contrib.auth.models.User`](#django.contrib.auth.models.User) 接口的类，有这些区别： - [id](/zh-hans/5.2/topics/db/models/#automatic-primary-key-fields) 总是 `None`。 - [`username`](#django.contrib.auth.models.User.username) 总是空字符串。 - [`get_username()`](#django.contrib.auth.models.User.get_username) 总是返回空字符串。 - [`is_anonymous`](#django.contrib.auth.models.User.is_anonymous) 是 `True` 而不是 `False`。 - [`is_authenticated`](#django.contrib.auth.models.User.is_authenticated) 是 `False` 而不是 `True`。 - [`is_staff`](#django.contrib.auth.models.User.is_staff) 和 [`is_superuser`](#django.contrib.auth.models.User.is_superuser) 总是 `False`。 - [`is_active`](#django.contrib.auth.models.User.is_active) 总是 `False`。 - `group` 和 [`user_permissions`](#django.contrib.auth.models.User.user_permissions) 总是空的。 - [`set_password()`](#django.contrib.auth.models.User.set_password)、[`check_password()`](#django.contrib.auth.models.User.check_password)、[`save()`](/zh-hans/5.2/ref/models/instances/#django.db.models.Model.save) 和 [`delete()`](/zh-hans/5.2/ref/models/instances/#django.db.models.Model.delete) 引发 [`NotImplementedError`](https://docs.python.org/3/library/exceptions.html#NotImplementedError)。 在实践中，你可能不需要自己使用 [`AnonymousUser`](#django.contrib.auth.models.AnonymousUser) 对象，但它们会被网络请求使用，在下一节中解释。 ## `Permission` 模型 #### `class models.Permission` ### 字段 [`Permission`](#django.contrib.auth.models.Permission) 对象有以下字段： #### `class models.Permission` #### `name` 必要的。255 个字符或以下。例如：`'Can vote'`。 #### `content_type` Required. A foreign key to the [`ContentType`](/zh-hans/5.2/ref/contrib/contenttypes/#django.contrib.contenttypes.models.ContentType) model. #### `codename` 必要的。100 个字符或以下。例如：`'can_vote'`。 ### 方法 [`Permission`](#django.contrib.auth.models.Permission) 对象和其他 [Django 模型](/zh-hans/5.2/ref/models/instances/) 一样拥有标准的数据访问方法。 ## `Group` 模型 #### `class models.Group` ### 字段 [`Group`](#django.contrib.auth.models.Group) 对象有以下字段： #### `class models.Group` #### `name` 要求： 150 个字符或以下。允许使用任何字符。例如：`'Awesome Users'`。 #### `permissions` 多对多字段到 [`Permission`](#django.contrib.auth.models.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` 的默认验证器。 ## 登录和注销的信号 认证框架使用了以下的 [信号](/zh-hans/5.2/topics/signals/)，可以在用户登录或退出时用于通知。 #### `user_logged_in` 当用户成功登录时发送。 用此信号发送的参数： **`sender`** 刚刚登录的用户的类。 **`request`** 当前的 [`HttpRequest`](/zh-hans/5.2/ref/request-response/#django.http.HttpRequest) 实例。 **`user`** 刚刚登录的用户的实例。 #### `user_logged_out` 调用注销方法时发送。 **`sender`** 如上所述：刚刚注销的用户的类，如果用户没有经过认证，则为 `None`。 **`request`** 当前的 [`HttpRequest`](/zh-hans/5.2/ref/request-response/#django.http.HttpRequest) 实例。 **`user`** 刚刚注销的用户实例，如果用户没有经过认证，则为 `None`。 #### `user_login_failed` 当用户未能成功登录时发送 **`sender`** 用于认证的模块名称。 **`credentials`** 一个包含关键字参数的字典，其中包含传递给 [`authenticate()`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.authenticate) 或你自己的自定义认证后端的用户凭证。匹配一组“敏感的”模式的凭证（包括密码）将不会作为信号的一部分被发送。 **`request`** [`HttpRequest`](/zh-hans/5.2/ref/request-response/#django.http.HttpRequest) 对象，如果有提供给 [`authenticate()`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.authenticate) 对象的话。 ## 认证后端 本节详细介绍了 Django 自带的认证后端。关于如何使用它们以及如何编写你自己的认证后端，请参阅 [用户认证指南](/zh-hans/5.2/topics/auth/) 中的 [其他认证源](/zh-hans/5.2/topics/auth/customizing/#authentication-backends) 部分。 ### 可用的认证后端 在 [`django.contrib.auth.backends`](#module-django.contrib.auth.backends) 中可以找到以下后端： #### `class BaseBackend` 一个为所有所需方法提供默认实现的基类。默认情况下，它将拒绝任何用户并不提供任何权限。 #### `get_user_permissions(user_obj, obj=None)` #### `aget_user_permissions(user_obj, obj=None)` *Asynchronous version*: `aget_user_permissions()` 返回一个空集。 > **Changed in Django 5.2** > > `aget_user_permissions()` function was added. #### `get_group_permissions(user_obj, obj=None)` #### `aget_group_permissions(user_obj, obj=None)` *Asynchronous version*: `aget_group_permissions()` 返回一个空集。 > **Changed in Django 5.2** > > `aget_group_permissions()` function was added. #### `get_all_permissions(user_obj, obj=None)` #### `aget_all_permissions(user_obj, obj=None)` *Asynchronous version*: `aget_all_permissions()` 使用 [`get_user_permissions()`](#django.contrib.auth.backends.BaseBackend.get_user_permissions) 和 [`get_group_permissions()`](#django.contrib.auth.backends.BaseBackend.get_group_permissions) 来获取 `user_obj` 所拥有的权限字符串。 > **Changed in Django 5.2** > > `aget_all_permissions()` function was added. #### `has_perm(user_obj, perm, obj=None)` #### `ahas_perm(user_obj, perm, obj=None)` *Asynchronous version*: `ahas_perm()` 使用 [`get_all_permissions()`](#django.contrib.auth.backends.BaseBackend.get_all_permissions) 检查 `user_obj` 是否有 `perm` 的权限字符串。 > **Changed in Django 5.2** > > `ahas_perm()` function was added. #### `class ModelBackend` 这是 Django 默认使用的认证后端。 它使用由用户标识符和密码组成的凭证进行认证。 对于 Django 的默认用户模型来说，用户标识符是用户名，对于自定义用户模型来说，它是 USERNAME\_FIELD 指定的字段（参见 [自定义用户和身份认证](/zh-hans/5.2/topics/auth/customizing/)）。 它还处理了为 [`User`](#django.contrib.auth.models.User) 和 [`PermissionsMixin`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.PermissionsMixin) 定义的默认权限模型。 [`has_perm()`](#django.contrib.auth.backends.ModelBackend.has_perm)、 [`get_all_permissions()`](#django.contrib.auth.backends.ModelBackend.get_all_permissions)、 [`get_user_permissions()`](#django.contrib.auth.backends.ModelBackend.get_user_permissions) 和 [`get_group_permissions()`](#django.contrib.auth.backends.ModelBackend.get_group_permissions) 允许将对象作为参数传递给特定对象的权限，但除了在 `obj is not None` 的情况下返回一个空的权限集外，这个后端并没有实现它们。 [`with_perm()`](#django.contrib.auth.backends.ModelBackend.with_perm) 也允许传递一个对象作为参数，但与其他方法不同的是，如果 `obj is not None`，则返回一个空的查询集。 #### `authenticate(request, username=None, password=None, **kwargs)` #### `aauthenticate(request, username=None, password=None, **kwargs)` *异步版本*：`aauthenticate()` 通过调用 [`User.check_password`](#django.contrib.auth.models.User.check_password) 尝试用 `password` 认证 `username`。如果没有提供 `username`，则尝试使用键 [`CustomUser.USERNAME_FIELD`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.CustomUser.USERNAME_FIELD) 从 `kwargs` 中获取一个用户名。返回一个已认证的用户或 `None`。 `request` 是一个 [`HttpRequest`](/zh-hans/5.2/ref/request-response/#django.http.HttpRequest)，如果没有提供给 [`authenticate()`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.authenticate) （将其传递给后端），则可能是 `None`。 > **Changed in Django 5.2** > > `aauthenticate()` 函数已添加。 #### `get_user_permissions(user_obj, obj=None)` #### `aget_user_permissions(user_obj, obj=None)` *Asynchronous version*: `aget_user_permissions()` 从他们自己的用户权限中返回 `user_obj` 拥有的权限字符串集。如果 [`is_anonymous`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.AbstractBaseUser.is_anonymous) 或 [`is_active`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.CustomUser.is_active) 是 `False`，则返回空集。 > **Changed in Django 5.2** > > `aget_user_permissions()` function was added. #### `get_group_permissions(user_obj, obj=None)` #### `aget_group_permissions(user_obj, obj=None)` *Asynchronous version*: `aget_group_permissions()` 从他们自己的用户权限中返回 `user_obj` 拥有的权限字符串集。如果 [`is_anonymous`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.AbstractBaseUser.is_anonymous) 或 [`is_active`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.CustomUser.is_active) 是 `False`，则返回空集。 > **Changed in Django 5.2** > > `aget_group_permissions()` function was added. #### `get_all_permissions(user_obj, obj=None)` #### `aget_all_permissions(user_obj, obj=None)` *Asynchronous version*: `aget_all_permissions()` 从他们自己的用户权限中返回 `user_obj` 拥有的权限字符串集。如果 [`is_anonymous`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.AbstractBaseUser.is_anonymous) 或 [`is_active`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.CustomUser.is_active) 是 `False`，则返回空集。 > **Changed in Django 5.2** > > `aget_all_permissions()` function was added. #### `has_perm(user_obj, perm, obj=None)` #### `ahas_perm(user_obj, perm, obj=None)` *Asynchronous version*: `ahas_perm()` 使用 [`get_all_permissions()`](#django.contrib.auth.backends.ModelBackend.get_all_permissions) 检查 `user_obj` 是否有 `perm` 的权限。如果用户没有 [`is_active`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.CustomUser.is_active)，则返回 `False`。 > **Changed in Django 5.2** > > `ahas_perm()` function was added. #### `has_module_perms(user_obj, app_label)` #### `ahas_module_perms(user_obj, app_label)` *Asynchronous version*: `ahas_module_perms()` 返回 `user_obj` 是否对应用 `app_label` 具有任何权限。 > **Changed in Django 5.2** > > `ahas_module_perms()` function was added. #### `user_can_authenticate()` 返回是否允许用户进行认证。为了与 [`AuthenticationForm`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.forms.AuthenticationForm) 中 [`prohibits inactive users from logging in`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed) 的行为相匹配，对于有 [`is_active=False`](#django.contrib.auth.models.User.is_active) 的用户，本方法返回 `False`。允许没有 [`is_active`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.CustomUser.is_active) 字段的自定义用户模型。 #### `with_perm(perm, is_active=True, include_superusers=True, obj=None)` 返回所有拥有 `perm` 权限的活跃用户，可以是 `"."` 的形式，也可以是 [`Permission`](#django.contrib.auth.models.Permission) 实例。如果没有找到拥有 `perm` 权限的用户，则返回一个空的查询集。 如果 `is_active` 为 `True` （默认），则只返回活跃用户，如果 `False`，则只返回非活跃用户。使用 `None` 返回所有用户，无论其是否处于活跃状态。 如果 `include_superusers` 为 `True` （默认），结果将包括超级用户。 #### `class AllowAllUsersModelBackend` 与 [`ModelBackend`](#django.contrib.auth.backends.ModelBackend) 一样，只是它不会拒绝非活动用户，因为 [`user_can_authenticate()`](#django.contrib.auth.backends.ModelBackend.user_can_authenticate) 总是返回 `True`。 当使用这个后台时，你可能会想要自定义 [`AuthenticationForm`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.forms.AuthenticationForm) 所使用的 [`LoginView`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.views.LoginView)，通过覆盖 [`confirm_login_allowed()`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.forms.AuthenticationForm.confirm_login_allowed) 方法，因为它拒绝非活动用户。 #### `class RemoteUserBackend` 使用这个后端来利用外部对 Django 处理的认证。 它使用 [`request.META['REMOTE_USER']`](/zh-hans/5.2/ref/request-response/#django.http.HttpRequest.META) 中传递的用户名进行认证。 参见 [认证 REMOTE\_USER](/zh-hans/5.2/howto/auth-remote-user/) 文档。 如果你需要更多的控制，你可以创建自己的认证后端，继承这个类，并覆盖这些属性或方法： #### `create_unknown_user` `True` 或 `False`。确定如果数据库中没有用户对象，是否创建用户对象。默认为 `True`。 #### `authenticate(request, remote_user)` #### `aauthenticate(request, remote_user)` *异步版本*：`aauthenticate()` 作为 `remote_user` 传递的用户名被认为是可信的。如果 [`create_unknown_user`](#django.contrib.auth.backends.RemoteUserBackend.create_unknown_user) 为 `True`，则该方法返回给定用户名的用户对象，创建一个新的用户对象。 如果 [`create_unknown_user`](#django.contrib.auth.backends.RemoteUserBackend.create_unknown_user) 为 `False`，且数据库中没有找到给定用户名的 `User` 对象，则返回 `None`。 `request` 是一个 [`HttpRequest`](/zh-hans/5.2/ref/request-response/#django.http.HttpRequest)，如果没有提供给 [`authenticate()`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.authenticate) （将其传递给后端），则可能是 `None`。 > **Changed in Django 5.2** > > `aauthenticate()` 函数已添加。 #### `clean_username(username)` 在使用 `username` 获取或创建用户对象之前，对 `username` 进行任何清理（例如剥离 LDAP DN 信息）。返回清理后的用户名。 #### `configure_user(request, user, created=True)` #### `aconfigure_user(request, user, created=True)` *Asynchronous version*: `aconfigure_user()` 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. When fetching or creating an user is called from a synchronous context, `configure_user` is called, `aconfigure_user` is called from async contexts. 可以在用户创建时执行设置（`created` 为 `True`）或在现有用户上执行设置（`created` 为 `False`），以在远程和本地系统之间同步属性。 `request` 是一个 [`HttpRequest`](/zh-hans/5.2/ref/request-response/#django.http.HttpRequest)，如果没有提供给 [`authenticate()`](/zh-hans/5.2/topics/auth/default/#django.contrib.auth.authenticate) （将其传递给后端），则可能是 `None`。 > **Changed in Django 5.2** > > `aconfigure_user()` function was added. #### `user_can_authenticate()` 返回是否允许用户进行身份认证。对于有 [`is_active=False`](#django.contrib.auth.models.User.is_active) 的用户，本方法返回 `False`。允许没有 [`is_active`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.CustomUser.is_active) 字段的自定义用户模型。 #### `class AllowAllUsersRemoteUserBackend` 与 [`RemoteUserBackend`](#django.contrib.auth.backends.RemoteUserBackend) 相同，只是它不会拒绝非活动用户，因为 [`user_can_authenticate`](#django.contrib.auth.backends.RemoteUserBackend.user_can_authenticate) 总是返回 `True`。 ## 实用工具函数 #### `get_user(request)` #### `aget_user(request)` *异步版本*：`aget_user()` 返回与给定 `request` 的会话相关联的用户模型实例。 它会检查会话中存储的身份验证后端是否存在于 [`AUTHENTICATION_BACKENDS`](/zh-hans/5.2/ref/settings/#std-setting-AUTHENTICATION_BACKENDS) 中。如果存在，它将使用后端的 `get_user()` 方法来检索用户模型实例，然后通过调用用户模型的 [`get_session_auth_hash()`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.AbstractBaseUser.get_session_auth_hash) 方法来验证会话。如果验证失败并且提供了 [`SECRET_KEY_FALLBACKS`](/zh-hans/5.2/ref/settings/#std-setting-SECRET_KEY_FALLBACKS)，它将使用 [`get_session_auth_fallback_hash()`](/zh-hans/5.2/topics/auth/customizing/#django.contrib.auth.models.AbstractBaseUser.get_session_auth_fallback_hash) 来对会话进行每个后备密钥的验证。 如果存储在会话中的认证后端不再在 [`AUTHENTICATION_BACKENDS`](/zh-hans/5.2/ref/settings/#std-setting-AUTHENTICATION_BACKENDS) 中，如果后端的 `get_user()` 方法没有返回用户，或者会话认证的哈希没有认证，则返回一个 [`AnonymousUser`](#django.contrib.auth.models.AnonymousUser) 的实例。