django.contrib.auth

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

User 模型

字段

• class models.User

• User 对象有如下字段：

  • username
  • Required. 150 characters or fewer. Usernames may contain alphanumeric,_, @, +, . and - characters.

The max_length should be sufficient for many use cases. If you needa longer length, please use a custom user model. If you use MySQL with the utf8mb4encoding (recommended for proper Unicode support), specify at mostmax_length=191 because MySQL can only create unique indexes with191 characters in that case by default.

Usernames and Unicode

Django originally accepted only ASCII letters and numbers inusernames. Although it wasn't a deliberate choice, Unicodecharacters have always been accepted when using Python 3. Django1.10 officially added Unicode support in usernames, keeping theASCII-only behavior on Python 2.

• first_name

• Optional (blank=True). 30characters or fewer.

• last_name

• Optional (blank=True). 150characters or fewer.

• email

• Optional (blank=True). Emailaddress.

• password

• Required. A hash of, and metadata about, the password. (Django doesn'tstore the raw password.) Raw passwords can be arbitrarily long and cancontain any character. See the password documentation.

• groups

• Many-to-many relationship to Group

• user_permissions

• Many-to-many relationship to Permission

• is_staff

• Boolean. Designates whether this user can access the admin site.

• is_active

• Boolean. Designates whether this user account should be consideredactive. We recommend that you set this flag to False instead ofdeleting accounts; that way, if your applications have any foreign keysto users, the foreign keys won't break.

This doesn't necessarily control whether or not the user can log in.Authentication backends aren't required to check for the is_activeflag but the default backend(ModelBackend) and theRemoteUserBackend do. You canuse AllowAllUsersModelBackendor AllowAllUsersRemoteUserBackendif you want to allow inactive users to login. In this case, you'll alsowant to customize theAuthenticationForm used by theLoginView as it rejects inactiveusers. Be aware that the permission-checking methods such ashas_perm() and theauthentication in the Django admin all return False for inactiveusers.

• is_superuser

• 布尔值。指定该用户拥有所有权限，而不用一个个开启权限。

• last_login

• A datetime of the user's last login.

• date_joined

• A datetime designating when the account was created. Is set to thecurrent date/time by default when the account is created.

属性

• class models.User
• • is_authenticated

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

  • is_anonymous

  • Read-only attribute which is always False. This is a way ofdifferentiating User and AnonymousUserobjects. Generally, you should prefer usingis_authenticated to thisattribute.

方法

• class models.User
• • get_username()

  • Returns the username for the user. Since the User model can beswapped out, you should use this method instead of referencing theusername attribute directly.

  • get_full_name()

  • Returns the first_name plusthe last_name, with a space inbetween.

  • get_short_name()

  • Returns the first_name.

  • setpassword(_raw_password)

  • Sets the user's password to the given raw string, taking care of thepassword hashing. Doesn't save theUser object.

When the raw_password is None, the password will be set to anunusable password, as ifset_unusable_password()were used.

• checkpassword(_raw_password)

• 如果密码正确则返回'True'。(密码哈希值用于比较)

• set_unusable_password()

• Marks the user as having no password set. This isn't the same ashaving a blank string for a password.check_password() for this userwill never return True. Doesn't save theUser object.

如果针对现有外部源（例如LDAP目录）进行应用程序的身份验证，则可能需要这样做。

• has_usable_password()
• Returns False ifset_unusable_password() hasbeen called for this user.

Changed in Django 2.1:在旧版本中，如果密码是 None 或空字符串或使用不在 PASSWORD_HASHERS 中的哈希，那么也会返回 False 。这个行为被认为是一个 bug ，因为它阻止有这样密码的用户通过请求重置密码。

• getgroup_permissions(_obj=None)
• 返回用户拥有权限的字符串集合。

如果传入 obj 参数，则只返回指定对象所属组的权限。

• getall_permissions(_obj=None)
• 返回用户拥有权限的字符串集合，同时从用户所属组及用户本身的权限中获取。

如果传入 ``obj``参数，则只返回指定对象和所属组的权限。

• hasperm(_perm, obj=None)
• Returns True if the user has the specified permission, where permis in the format "<app label>.<permission codename>". (seedocumentation on permissions). If the user isinactive, this method will always return False. For an activesuperuser, this method will always return True.

如果传入 obj 参数，则这个方法不会检查该模型权限，而只会检查这个出传入对象的权限。

• hasperms(_perm_list, obj=None)
• Returns True if the user has each of the specified permissions,where each perm is in the format"<app label>.<permission codename>". If the user is inactive,this method will always return False. For an active superuser, thismethod will always return True.

如果传入参数 obj ，则这个方法不会检查指定的权限列表，只检查指定对象的权限。

• hasmodule_perms(_package_name)

• Returns True if the user has any permissions in the given package(the Django app label). If the user is inactive, this method willalways return False. For an active superuser, this method willalways return True.

• emailuser(_subject, message, from_email=None, **kwargs)

• Sends an email to the user. If from_email is None, Django usesthe DEFAULT_FROM_EMAIL. Any **kwargs are passed to theunderlying send_mail() call.

Manager methods

• class models.UserManager

• The User model has a custom managerthat has the following helper methods (in addition to the methods providedby BaseUserManager):

  • createuser(_username, email=None, password=None, **extra_fields)
  • Creates, saves and returns a User.

The username andpassword are set as given. Thedomain portion of email isautomatically converted to lowercase, and the returnedUser object will haveis_active set to True.

If no password is provided,set_unusable_password() willbe called.

The extrafields keyword arguments are passed through to theUser’s _init method toallow setting arbitrary fields on a custom user model.

See Creating users for example usage.

• createsuperuser(_username, email, password, **extra_fields)
• Same as create_user(), but sets is_staff andis_superuser to True.

AnonymousUser object

• class models.AnonymousUser

• django.contrib.auth.models.AnonymousUser is a class thatimplements the django.contrib.auth.models.User interface, withthese differences:

  • id is always None.
  • username is always the emptystring.
  • get_username() always returnsthe empty string.
  • is_anonymous is Trueinstead of False.
  • is_authenticated isFalse instead of True.
  • is_staff andis_superuser are alwaysFalse.
  • is_active is always False.
  • groups anduser_permissions are alwaysempty.
  • set_password(),check_password(),save() anddelete() raise NotImplementedError.In practice, you probably won't need to useAnonymousUser objects on your own, butthey're used by Web requests, as explained in the next section.

Permission model

• class models.Permission

字段

Permission objects have the followingfields:

• class models.Permission
• • name

  • Required. 255 characters or fewer. Example: 'Can vote'.

  • content_type

  • Required. A reference to the django_content_type database table,which contains a record for each installed model.

  • codename

  • Required. 100 characters or fewer. Example: 'can_vote'.

方法

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

Group model

• class models.Group

字段

Group objects have the following fields:

• class models.Group
• • name
  • Required. 150 characters or fewer. Any characters are permitted.Example: 'Awesome Users'.

Changed in Django 2.2:The max_length increased from 80 to 150 characters.

• permissions
• Many-to-many field to Permission:

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

Validators

• class validators.ASCIIUsernameValidator

• A field validator allowing only ASCII letters and numbers, in addition to@, ., +, -, and _.

• class validators.UnicodeUsernameValidator

• A field validator allowing Unicode characters, in addition to @, .,+, -, and _. The default validator for User.username.

Login and logout signals

The auth framework uses the following signals thatcan be used for notification when a user logs in or out.

• user_logged_in()
• Sent when a user logs in successfully.

Arguments sent with this signal:

• 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()
  • Sent when the logout method is called.

• sender

• As above: the class of the user that just logged out or Noneif the user was not authenticated.
• request
• The current HttpRequest instance.
• user

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

  • user_login_failed()
  • Sent when the user failed to login successfully

• sender

• The name of the module used for authentication.
• credentials
• A dictionary of keyword arguments containing the user credentials that werepassed to authenticate() or your own customauthentication backend. Credentials matching a set of 'sensitive' patterns,(including password) will not be sent in the clear as part of the signal.
• request
• The HttpRequest object, if one was provided toauthenticate().

Authentication backends

This section details the authentication backends that come with Django. Forinformation on how to use them and how to write your own authenticationbackends, see the Other authentication sources section of the User authentication guide.

Available authentication backends

The following backends are available in django.contrib.auth.backends:

• class ModelBackend
• This is the default authentication backend used by Django. Itauthenticates using credentials consisting of a user identifier andpassword. For Django's default user model, the user identifier is theusername, for custom user models it is the field specified byUSERNAME_FIELD (see Customizing Users and authentication).

It also handles the default permissions model as defined forUser andPermissionsMixin.

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

• authenticate(request, username=None, password=None, **kwargs)
• Tries to authenticate username with password by callingUser.check_password. If no usernameis provided, it tries to fetch a username from kwargs using thekey CustomUser.USERNAME_FIELD. Returns anauthenticated user or None.

request 是 HttpRequest ，默认为 None 如果没有被提供给 authenticate() (它把request传给后端).

• getuser_permissions(_user_obj, obj=None)

• Returns the set of permission strings the user_obj has from theirown user permissions. Returns an empty set ifis_anonymous oris_active is False.

• getgroup_permissions(_user_obj, obj=None)

• Returns the set of permission strings the user_obj has from thepermissions of the groups they belong. Returns an empty set ifis_anonymous oris_active is False.

• getall_permissions(_user_obj, obj=None)

• Returns the set of permission strings the user_obj has, including bothuser permissions and group permissions. Returns an empty set ifis_anonymous oris_active is False.

• hasperm(_user_obj, perm, obj=None)

• Uses get_all_permissions() to check if user_obj has thepermission string perm. Returns False if the user is notis_active.

• hasmodule_perms(_user_obj, app_label)

• Returns whether the user_obj has any permissions on the appapp_label.

• user_can_authenticate()

• Returns whether the user is allowed to authenticate. To match thebehavior of AuthenticationFormwhich prohibits inactive users from logging in,this method returns False for users with is_active=False. Custom user models thatdon't have an is_activefield are allowed.

• class AllowAllUsersModelBackend
• Same as ModelBackend except that it doesn't reject inactive usersbecause user_can_authenticate() always returns True.

When using this backend, you'll likely want to customize theAuthenticationForm used by theLoginView by overriding theconfirm_login_allowed()method as it rejects inactive users.

• class RemoteUserBackend
• Use this backend to take advantage of external-to-Django-handledauthentication. It authenticates using usernames passed inrequest.META['REMOTE_USER']. Seethe Authenticating against REMOTE_USERdocumentation.

If you need more control, you can create your own authentication backendthat inherits from this class and override these attributes or methods:

• create_unknown_user

• True or False. Determines whether or not a user object iscreated if not already in the database Defaults to True.

• authenticate(request, remote_user)

• The username passed as remote_user is considered trusted. Thismethod simply returns the user object with the given username, creatinga new user object if create_unknown_user isTrue.

Returns None if create_unknown_user isFalse and a User object with the given username is not found inthe database.

request 是 HttpRequest ，默认为 None 如果没有被提供给 authenticate() (它把request传给后端).

• cleanusername(_username)

• Performs any cleaning on the username (e.g. stripping LDAP DNinformation) prior to using it to get or create a user object. Returnsthe cleaned username.

• configureuser(_request, user)

• Configures a newly created user. This method is called immediatelyafter a new user is created, and can be used to perform custom setupactions, such as setting the user's groups based on attributes in anLDAP directory. Returns the user object.

request 是 HttpRequest ，默认为 None 如果没有被提供给 authenticate() (它把request传给后端).

Changed in Django 2.2:The request argument was added. Support for method overridesthat don't accept it will be removed in Django 3.1.

• user_can_authenticate()
• Returns whether the user is allowed to authenticate. This methodreturns False for users with is_active=False. Custom user models thatdon't have an is_activefield are allowed.

• class AllowAllUsersRemoteUserBackend
• Same as RemoteUserBackend except that it doesn't reject inactiveusers because user_can_authenticate alwaysreturns True.

Utility functions

• getuser(_request)[源代码]
• Returns the user model instance associated with the given request’ssession.

It checks if the authentication backend stored in the session is present inAUTHENTICATION_BACKENDS. If so, it uses the backend'sget_user() method to retrieve the user model instance and then verifiesthe session by calling the user model'sget_session_auth_hash()method.

Returns an instance of AnonymousUserif the authentication backend stored in the session is no longer inAUTHENTICATION_BACKENDS, if a user isn't returned by thebackend's get_user() method, or if the session auth hash doesn'tvalidate.