API参考

这份文档提供Django 认证系统组件的API 参考资料。对于这些组件的用法以及如何自定义认证和授权请参照认证主题的相关指南。

字段

class models.``User

User 对象具有如下字段：

username

必选。少于等于30个字符。 用户名可以包含字母、数字、_、@、+、.和- 字符。

first_name

可选。 少于等于30个字符。

last_name

可选。少于30个字符。

email

可选。邮箱地址。

password

必选。 密码的哈希及元数据。（Django 不保存原始密码）。原始密码可以无限长而且可以包含任意字符。参见密码相关的文档。

groups

与Group 之间的多对多关系。

user_permissions

与Permission 之间的多对多关系。

is_staff

布尔值。指示用户是否可以访问Admin 站点。

is_active

布尔值。指示用户的账号是否激活。我们建议把这个标记设置为False 来代替删除账号；这样的话，如果你的应用和User 之间有外键关联，外键就不会失效。

它不是用来控制用户是否能够登录。认证的后端没有要求检查is_active 标记，而且默认的后端不会检查。如果你想在is_active 为False 时拒绝用户登录，你需要在你自己的视图或自定义的认证后端中作检查。但是，默认的login() 视图使用的AuthenticationForm 却会 作这个检查，正如在Django 的Admin 站点中所做的权限检查方法如has_perm() 和认证一样。对于未激活的用户，所有这些函数/方法都返回False。

is_superuser

布尔值。指定这个用户拥有所有的权限而不需要给他们分配明确的权限。

last_login

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

Changed in Django 1.8:

如果这个用户没有登录过，这个字段将会是null。以前默认设置成当前的date/time。

date_joined

账户创建的时间。当账号创建时，默认设置为当前的date/time。

方法

class models.``User

get_username()

返回这个User 的username。因为User 模型可以置换，你应该使用这个方法而不要直接访问username 属性。

is_anonymous()

永远返回False。这是区别User 和AnonymousUser 对象的一种方法。一般情况下，相比这个方法更建议你使用is_authenticated()。

is_authenticated()

永远返回True（与AnonymousUser.is_authenticated() 永远返回False 相反）。这是区分用户是否已经认证的一种方法。它不检查权限、用户是否激活以及是否具有一个合法的会话。即使通常你将在request.user上面 调用这个方法来确认用户是否已经被AuthenticationMiddleware 填充（表示当前登录的用户），你应该明白这个方法对于任何User 实例都返回True。

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)

如果给出的原始字符串是用户正确的密码，则返回True。 （它负责在比较时密码的哈希）。

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的格式为“＆lt； app label＆gt；。＆lt； permission codename＆gt；“。（请参阅有关permissions）。如果用户处于非活动状态，此方法将始终返回False。

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

has_perms(perm_list, obj=None)

如果用户具有每个指定的权限，则返回True，其中每个perm的格式为“＆lt； app label＆gt；。＆lt； permission codename＆gt；“。如果用户处于非活动状态，此方法将始终返回False。

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

has_module_perms(package_name)

如果用户具有给出的package（Django 的应用标签）中的权限，则返回True。如果用户没有激活，这个方法将永远返回 False。

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

发生邮件给这个用户。如果from_email 为None，Django 将使用DEFAULT_FROM_EMAIL。

Changed in Django 1.7:

任何**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。

如果没有提供password，将调用 set_unusable_password()。

extra_fields 关键字参数将传递给User 的__init__ 方法，以允许设置自定义User 模型 的字段。

参见创建用户 中的示例用法。

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

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

class models.``AnonymousUser

django.contrib.auth.models.AnonymousUser 类实现了django.contrib.auth.models.User 接口，但具有下面几个不同点：

• id 永远为None。
• username 永远为空字符串。
• get_username() 永远返回空字符串。
• is_staff 和is_superuser 永远为False。
• is_active 永远为 False。
• groups 和user_permissions 永远为空。
• is_anonymous() 返回True 而不是False。
• is_authenticated() 返回False 而不是True。
• set_password()、check_password()、save() 和delete() 引发NotImplementedError。

New in Django 1.8:

新增AnonymousUser.get_username() 以更好地模拟 django.contrib.auth.models.User。

在实际应用中，你自己可能不需要使用AnonymousUser 对象，它们用于Web 请求，在下节会讲述。

class models.``Permission

字段

Permission 对象有以下字段:

class models.``Permission

name

必填项. 255个字符或者更少. 例如: 'Can vote'.

Changed in Django 1.8:

max_length 属性从50个字符增加至255个字符

content_type

必填项.对django_content_type数据库表的引用，其中包含每个已安装模型的记录。

codename

必须项.小于等于是100个字符.例如: 'can_vote'.

方法

Permission对象具有类似任何其他Django model的标准数据访问方法。

class models.``Group

字段

Group 对象有以下字段:

class models.``Group

name

必填项，80个字符以内。允许任何字符. 例如: 'Awesome Users'.

permissions

多对多字段到Permission：

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

auth框架使用以下signals，可用于在用户登录或注销时通知。

user_logged_in()

当用户成功登录时发送。

与此信号一起发送的参数：

sender

The class of the user that just logged in.

request

The current HttpRequest instance.

user

The user instance that just logged in.

user_logged_out()

在调用logout方法时发送。

sender

As above: the class of the user that just logged out or None if the user was not authenticated.

request

The current HttpRequest instance.

user

The user instance that just logged out or None if the user was not authenticated.

user_login_failed()

当用户登录失败时发送

sender

The name of the module used for authentication.

credentials

A dictionary of keyword arguments containing the user credentials that were passed to authenticate() or your own custom authentication backend. Credentials matching a set of ‘sensitive’ patterns, (including password) will not be sent in the clear as part of the signal.

这一节详细讲述Django 自带的认证后台。关于如何使用它们以及如何编写你自己的认证后台，参见用户认证指南 中的其它认证源一节。

可用的认证后台

以下是django.contrib.auth.backends 中可以使用的后台：

class ModelBackend[source]

这是Django使用的默认认证后台。它使用由用户标识和密码组成的凭据进行认证。对于Django的默认用户模型，用户的标识是用户名，对于自定义的用户模型，它通过USERNAMEFIELD 字段表示（参见[自定义Users 和认证_](../../topics/auth/customizing.html)）。

它还处理 User 和PermissionsMixin 定义的权限模型。

has_perm(), get_all_permissions(), get_user_permissions(), 和get_group_permissions() 允许一个对象作为特定权限参数来传递, 如果条件是 if obj is not None. 后端除了返回一个空的permissions 外，并不会去完成他们。

authenticate(username=None, password=None, **kwargs)[source]

通过调用User.check_password 验证username 和password。如果username 没有提供，它会使用CustomUser.USERNAME_FIELD 关键字从kwargs 中获取username。返回一个认证过的User 或None。

get_user_permissions(user_obj, obj=None)[source]

New in Django 1.8.

返回user_obj具有的自己用户权限的权限字符串集合。如果is_anonymous()或is_active为False，则返回空集。

get_group_permissions(user_obj, obj=None)[source]

返回user_obj从其所属组的权限中获取的权限字符集。如果is_anonymous()或is_active为False，则返回空集。

get_all_permissions(user_obj, obj=None)[source]

返回user_obj的权限字符串集，包括用户权限和组权限。如果is_anonymous()或is_active为False，则返回空集。

has_perm(user_obj, perm, obj=None)[source]

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

has_module_perms(self, user_obj, app_label)[source]

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

class RemoteUserBackend[source]

使用这个后台来处理Django的外部认证。. 它使用 request.里面的usernames来进行验证。META ['REMOTEUSER']。请参阅[_Authenticating against REMOTE_USER](../../howto/auth-remote-user.html)文档。

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

RemoteUserBackend.``create_unknown_user

True或False。决定是否有一个 User 对象已经在数据库中创建。默认为True。

RemoteUserBackend.``authenticate(remote_user)[source]

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

如果create_unknown_user是False，并且在数据库中找不到具有给定用户名的User对象，则返回None。

RemoteUserBackend.``clean_username(username)[source]

Performs any cleaning on the username (e.g. stripping LDAP DN information) prior to using it to get or create a User object. 返回已清除的用户名。

RemoteUserBackend.``configure_user(user)[source]

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