django.contrib.auth

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

User модель

class models.User

Поля

class models.User

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

username

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

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

first_name

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

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 возвращают значение False для неактивных пользователей.

is_superuser

Булево значение. Присваивает этому пользователю все разрешения, без привязки к конкретным разрешениям.

last_login

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

date_joined

Дата/время создания учётной записи.

Атрибуты

class models.User

is_authenticated

Только для чтения атрибут, который всегда True (в отличие от AnonymousUser.is_authenticated, который всегда False). Это способ определить, был ли пользователь аутентифицирован. Это не подразумевает никаких разрешений и не проверяет, активен ли пользователь или у него есть действительная сессия. Хотя обычно вы проверяете этот атрибут на request.user, чтобы узнать, был ли он заполнен middleware 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)

acheck_password(raw_password)

Асинхронная версия: acheck_password()

Возвращает True, если заданная строка — правильный пароль для пользователя. (Это учитывает хеширование пароля при сравнении.)

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

acheck_password() метод был добавлен.

set_unusable_password()

Помечает пользователя как не имеющего установленного пароля. Это не то же самое, что иметь пустую строку в качестве пароля. check_password() для этого пользователя никогда не вернёт True. Не сохраняет объект User.

Возможно, это потребуется, если аутентификация для вашего приложения выполняется по внешнему источнику, такому как каталог LDAP.

Ограничение сброса пароля

Пользователи с недопустимым паролем не смогут запросить письмо для сброса пароля через PasswordResetView.

has_usable_password()

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

get_user_permissions(obj=None)

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

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

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

Возвращает пользователей, имеющих заданное разрешение 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'.

permissions

Множественное поле для 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

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

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

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)

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

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

configure_user(request, user, created=True)

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

Настройка может быть выполнена один раз при создании пользователя (created имеет значение True) или для существующих пользователей (created имеет значение False) как способ синхронизации атрибутов между удалённой и локальной системами.

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

user_can_authenticate()

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

class AllowAllUsersRemoteUserBackend

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

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

get_user(request)

aget_user(request)

Асинхронная версия: aget_user()

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

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

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

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

Добавлена проверка с резервными ключами SECRET_KEY_FALLBACKS.

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

Добавлена функция aget_user().