django.contrib.auth

Данный документ содержит справочную информацию по API-компонентам системы аутентификации Django. Для получения дополнительных сведений об использовании этих компонентов или о том, как настроить аутентификацию и авторизацию, обратитесь к руководству по теме аутентификации.

User модель

class models.User

Поля

class models.User

User объекты имеют следующие поля:

username

Обязательное поле. Длина не более 150 символов. Имена пользователей могут содержать символы латинского алфавита, _, @, +, . и -.

Длина в max_length обычно достаточна для многих случаев использования. Если вам нужна большая длина, используйте пользовательскую модель. Если вы используете MySQL с кодировкой utf8mb4 (рекомендуется для правильной поддержки Unicode), укажите не более max_length=191, так как MySQL по умолчанию может создавать уникальные индексы только с 191 символом в этом случае.

first_name

Необязательное поле (blank=True). Длина не более 30 символов.

last_name

Необязательное поле (blank=True). Длина не более 150 символов.

email

Необязательное поле (blank=True). Электронный адрес.

password

Обязательное поле. Хэш пароля и метаданные о нём. (Django не хранит сам пароль.) Сырые пароли могут быть произвольной длины и содержать любые символы. См. документацию по паролям.

groups

Связь «многие ко многим» с Group

user_permissions

Связь «многие ко многим» с Permission

is_staff

Булево значение. Указывает, может ли данный пользователь получить доступ к админской панели.

is_active

Булево значение. Указывает, считается ли учётная запись пользователя активной. Рекомендуется устанавливать этот флаг в False, а не удалять учётные записи, чтобы при наличии внешних ключей к пользователям они не сломались.

Это не обязательно контролирует возможность входа пользователя в систему. Модули аутентификации не обязаны проверять флаг is_active, но это делает модуль по умолчанию (ModelBackend) и RemoteUserBackend. Вы можете использовать AllowAllUsersModelBackend или AllowAllUsersRemoteUserBackend, если хотите позволить входить неактивным пользователям. В этом случае вам также потребуется настроить AuthenticationForm, используемый LoginView, так как он отклоняет неактивных пользователей. Имейте в виду, что методы проверки разрешений, такие как has_perm(), и аутентификация в Django admin возвращают False для неактивных пользователей.

is_superuser

Булево значение. Указывает, что у пользователя есть все разрешения без явного назначения.

last_login

Дата и время последнего входа пользователя.

date_joined

Дата и время создания учётной записи. По умолчанию устанавливается текущей датой и временем при создании учётной записи.

Атрибуты

class models.User

is_authenticated

Только для чтения атрибут, который всегда True (в отличие от AnonymousUser.is_authenticated, который всегда False). Это способ определить, был ли пользователь аутентифицирован. Это не подразумевает никаких разрешений и не проверяет, активен ли пользователь или у него есть действительная сессия. Хотя обычно вы проверяете этот атрибут на request.user, чтобы узнать, был ли он заполнен AuthenticationMiddleware (представляющим текущего вошедшего в систему пользователя), вы должны знать, что этот атрибут True для любого объекта User.

is_anonymous

Только для чтения атрибут, который всегда False. Это способ отличить объекты User от объектов AnonymousUser. Обычно следует предпочитать использование is_authenticated этому атрибуту.

Методы

class models.User

get_username()

Возвращает имя пользователя. Поскольку модель User может быть заменена, следует использовать этот метод вместо прямого обращения к атрибуту username.

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

Возвращает False, если для этого пользователя был вызван метод set_unusable_password().

get_user_permissions(obj=None)

Новое в Django 3.0.

Возвращает набор строк разрешений, которые у пользователя есть напрямую.

Если 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)

Возвращает True, если пользователь имеет какие-либо разрешения в заданном пакете (метка приложения Django). Если пользователь неактивен, этот метод всегда возвращает 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 передаются в метод __init__ объекта User, чтобы позволить устанавливать произвольные поля в настраиваемой модели пользователя настраиваемой модели пользователя.

Пример использования см. в создании пользователей.

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

Аналогично create_user(), но устанавливает is_staff и is_superuser в True.

Изменено в Django 3.0:

Параметры email и password стали необязательными.

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

Новое в Django 3.0.

Возвращает пользователей, у которых есть данное разрешение perm в формате "<app label>.<permission codename>" или как экземпляр Permission. Возвращает пустой набор запросов, если не найдено пользователей с данным perm.

Если is_active равно True (по умолчанию), возвращаются только активные пользователи, или False, возвращаются только неактивные пользователи. Используйте None, чтобы вернуть всех пользователей независимо от их активного состояния.

Если include_superusers равно True (по умолчанию), результат будет включать суперпользователей.

Если backend передан и определён в AUTHENTICATION_BACKENDS, этот метод его использует. Иначе, он использует backend из AUTHENTICATION_BACKENDS, если таковой единственный, или генерирует исключение.

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.
• groups и 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'.

Изменено в Django 2.2:

Предельная длина max_length увеличена с 80 до 150 символов.

permissions

Связь многие-ко-многим с Permission:

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

Валидаторы

class validators.ASCIIUsernameValidator

Валидатор поля, допускающий только латинские буквы и цифры, а также @, ., +, -, и _.

class validators.UnicodeUsernameValidator

Валидатор поля, допускающий символы Юникода, а также @, ., +, -, и _. По умолчанию используется для 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

Новое в Django 3.0.

Базовый класс, предоставляющий стандартные реализации всех необходимых методов. По умолчанию он отклоняет любого пользователя и не предоставляет разрешений.

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)

Пытается аутентифицировать username с password, вызывая User.check_password. Если username не предоставлен, он пытается извлечь имя пользователя из kwargs с помощью ключа CustomUser.USERNAME_FIELD. Возвращает аутентифицированного пользователя или None.

request — это HttpRequest и может быть None в случае, если он не был передан в authenticate() (который передает его в механизм).

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. Возвращает False если пользователь не is_active.

has_module_perms(user_obj, app_label)

Возвращает, обладает ли user_obj какими-либо разрешениями на приложение app_label.

user_can_authenticate()

Возвращает, разрешено ли пользователю аутентифицироваться. Для соответствия поведению AuthenticationForm, который prohibits inactive users from logging in, этот метод возвращает False для пользователей с is_active=False. Пользовательские модели пользователей, у которых нет поля is_active, разрешены.

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

Новое в Django 3.0.

Возвращает всех активных пользователей, у которых есть разрешение 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.

Возвращает None если create_unknown_user имеет значение False и объект пользователя с заданным именем пользователя не найден в базе данных.

request является объектом HttpRequest и может быть None, если он не был передан в authenticate() (который передает его бэкенду).

clean_username(username)

Выполняет любые операции очистки по имени пользователя username (например, удаляет информацию из LDAP DN) перед использованием его для получения или создания объекта пользователя. Возвращает очищенное имя пользователя.

configure_user(request, user)

Настраивает вновь созданного пользователя. Этот метод вызывается сразу после создания нового пользователя и может использоваться для выполнения пользовательских действий настройки, таких как установка групп пользователя на основе атрибутов в каталоге LDAP. Возвращает объект пользователя.

request является объектом HttpRequest и может быть None, если он не был передан в authenticate() (который передает его бэкенду).

Изменено в Django 2.2:

Добавлен аргумент request. Поддержка переопределений методов, не принимающих его, будет удалена в Django 3.1.

user_can_authenticate()

Возвращает, разрешено ли пользователю пройти аутентификацию. Этот метод возвращает False для пользователей с is_active=False. Пользовательские модели пользователей, у которых нет поля is_active, разрешены.

class AllowAllUsersRemoteUserBackend

Аналогично RemoteUserBackend, за исключением того, что он не отклоняет неактивных пользователей, так как user_can_authenticate всегда возвращает True.

Вспомогательные функции

get_user(request)

Возвращает экземпляр модели пользователя, связанный с заданной сессией request.

Он проверяет, присутствует ли бэкенд аутентификации, сохраненный в сессии, в AUTHENTICATION_BACKENDS. Если это так, он использует метод бэкенда get_user() для получения экземпляра модели пользователя, а затем проверяет сессию, вызвав метод модели пользователя get_session_auth_hash().

Возвращает экземпляр AnonymousUser, если бэкенд аутентификации, сохраненный в сессии, больше не находится в AUTHENTICATION_BACKENDS, если пользователь не возвращается методом бэкенда get_user() или если хэш аутентификации сессии не проходит проверку.