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 символов.

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

Длина max_length увеличилась с 30 до 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 может быть заменена, следует использовать этот метод вместо прямого обращения к атрибуту имени пользователя.

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

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

Новое в 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 и объект User с данным именем пользователя не найден в базе данных.

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

clean_username(username)

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

configure_user(request, user)

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

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

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() или если хеш аутентификации сессии не проходит проверку.