django.contrib.auth

This document provides API reference material for the components of Django'sauthentication system. For more details on the usage of these components orhow to customize authentication and authorization see the authenticationtopic guide.

User model

Fields

• class models.User

• User objects have the followingfields:

  • 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, with the option to customize thebehavior using User.username_validator.

• 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

• Boolean. Designates that this user has all permissions withoutexplicitly assigning them.

• 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.

Attributes

• class models.User
• • is_authenticated

  • Read-only attribute which is always True (as opposed toAnonymousUser.is_authenticated which is always False). This isa way to tell if the user has been authenticated. This does not implyany permissions and doesn't check if the user is active or has a validsession. Even though normally you will check this attribute onrequest.user to find out whether it has been populated by theAuthenticationMiddleware(representing the currently logged-in user), you should know thisattribute is True for any User instance.

  • 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.

  • username_validator

  • Points to a validator instance used to validate usernames. Defaults tovalidators.UnicodeUsernameValidator.

To change the default username validator, you can subclass the Usermodel and set this attribute to a different validator instance. Forexample, to use ASCII usernames:

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.

Methods

• 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)

• Returns True if the given raw string is the correct password forthe user. (This takes care of the password hashing in making thecomparison.)

• 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.

You may need this if authentication for your application takes placeagainst an existing external source such as an LDAP directory.

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

Changed in Django 2.1:
In older versions, this also returns False if the password isNone or an empty string, or if the password uses a hasherthat's not in the PASSWORD_HASHERS setting. Thatbehavior is considered a bug as it prevents users with suchpasswords from requesting a password reset.

• getgroup_permissions(_obj=None)
• Returns a set of permission strings that the user has, through theirgroups.

If obj is passed in, only returns the group permissions forthis specific object.

• getall_permissions(_obj=None)
• Returns a set of permission strings that the user has, both throughgroup and user permissions.

If obj is passed in, only returns the permissions for thisspecific object.

• 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.

If obj is passed in, this method won't check for a permission forthe model, but for this specific object.

• 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.

If obj is passed in, this method won't check for permissions forthe model, but for the specific object.

• 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.

• 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

Fields

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'.

Methods

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

Group model

• class models.Group

Fields

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 is an HttpRequest and may be Noneif it wasn't provided to authenticate()(which passes it on to the backend).

• 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 is an HttpRequest and may be Noneif it wasn't provided to authenticate()(which passes it on to the backend).

• 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 is an HttpRequest and may be Noneif it wasn't provided to authenticate()(which passes it on to the backend).

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.