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). Не более 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, чтобы узнать, был ли он заполнен 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 передаются методу 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 (по умолчанию), возвращаются только активные пользователи; в противном случае — только неактивные. Используйте 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 [source]

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

get_user_permissions(user_obj, obj=None) [source]

Возвращает пустое множество.

get_group_permissions(user_obj, obj=None) [source]

Возвращает пустое множество.

get_all_permissions(user_obj, obj=None) [source]

Использует get_user_permissions() и get_group_permissions() для получения набора строк разрешений, которые имеет user_obj.

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

Использует get_all_permissions() для проверки, имеет ли user_obj разрешение perm.

class ModelBackend [source]

Это по умолчанию используемый 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) [source]

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

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

get_user_permissions(user_obj, obj=None) [source]

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

has_module_perms(user_obj, app_label) [source]

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

user_can_authenticate() [source]

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

with_perm(perm, is_active=True, include_superusers=True, obj=None) [source]

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

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

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

class AllowAllUsersModelBackend [source]

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

При использовании этого бэкенда, вероятно, потребуется настроить AuthenticationForm, используемый LoginView, переопределяя метод confirm_login_allowed(), поскольку он отклоняет неактивных пользователей.

class RemoteUserBackend [source]

Используйте этот бэкенд для использования аутентификации, обрабатываемой внешним по отношению к Django сервисом. Он выполняет аутентификацию, используя имена пользователей, переданные в request.META['REMOTE_USER']. См. документацию по аутентификации по REMOTE_USER.

Если вам нужен больший контроль, вы можете создать собственный бэкенд аутентификации, унаследовав его от этого класса и переопределив эти атрибуты или методы:

create_unknown_user

True или False. Определяет, будет ли создаваться объект пользователя, если он ещё не существует в базе данных. По умолчанию True.

authenticate(request, remote_user) [source]

Имя пользователя, переданное как remote_user, считается надёжным. Этот метод возвращает объект пользователя с заданным именем пользователя, создавая новый объект пользователя, если create_unknown_user равно True.

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

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

clean_username(username) [source]

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

configure_user(request, user, created=True) [source]

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

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

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

user_can_authenticate()

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

class AllowAllUsersRemoteUserBackend [source]

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

Функции-утилиты

get_user(request) [source]

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 5.0:

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