django.contrib.auth

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

User модель

Поля

class models.User

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

username

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

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

Имена пользователей и Unicode

Django изначально принимал только символы ASCII в именах пользователей. Хотя это не было сознательным выбором, символы Unicode всегда принимались при использовании Python 3. В Django 1.10 официально была добавлена поддержка Unicode в именах пользователей, сохраняя поведение только с символами ASCII при использовании Python 2.

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

Длина max_length увеличена с 30 до 150 символов.

first_name

Необязательное поле. 30 символов или меньше.

last_name

Необязательное поле. 30 символов или меньше.

email

Необязательное поле. Адрес электронной почты.

password

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

groups

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

user_permissions

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

is_staff

Булево. Определяет, имеет ли пользователь доступ к админской панели.

is_active

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

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

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

В более старых версиях ModelBackend и RemoteUserBackend разрешали аутентификацию неактивных пользователей.

is_superuser

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

last_login

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

date_joined

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

Атрибуты

class models.User

is_authenticated

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

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

В более ранних версиях это был метод. Поддержка обратной совместимости для его использования в качестве метода будет удалена в Django 2.0.

is_anonymous

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

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

В более ранних версиях это был метод. Поддержка обратной совместимости для его использования в качестве метода будет удалена в Django 2.0.

Методы

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_group_permissions(obj=None)

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

Если obj передаётся, возвращает только разрешения группы для данного объекта.

get_all_permissions(obj=None)

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

Если obj передаётся, возвращает только разрешения для данного объекта.

has_perm(perm, obj=None)

Возвращает True если пользователь имеет указанное разрешение, где perm имеет формат "<app label>.<permission codename>". (см. документацию по разрешениям). Если пользователь неактивен, этот метод всегда возвращает False.

Если obj передаётся, этот метод не проверяет разрешение для модели, а для данного объекта.

has_perms(perm_list, obj=None)

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

Если obj передаётся, этот метод не проверяет разрешения для модели, а для конкретного объекта.

has_module_perms(package_name)

Возвращает True если пользователь имеет какие-либо разрешения в заданном пакете (метке приложения Django). Если пользователь неактивен, этот метод всегда возвращает False.

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, password, **extra_fields)

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

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

Обязательно. 80 символов или меньше. Разрешены любые символы. Пример: '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

Добавлена в Django 1.10.

Валидатор поля, допускающий только символы ASCII, помимо @, ., +, -, и _. По умолчанию используется для валидации User.username в Python 2.

class validators.UnicodeUsernameValidator

Добавлена в Django 1.10.

Валидатор поля, допускающий символы Юникод, помимо @, ., +, -, и _. По умолчанию используется для валидации User.username в Python 3.

Сигналы входа и выхода из системы

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

user_logged_in()

Отправляется при успешном входе пользователя.

Аргументы, отправленные с этим сигналом:

sender

Класс пользователя, который только что вошёл.

request

Текущий экземпляр HttpRequest.

user

Экземпляр пользователя, который только что вошёл.

user_logged_out()

Отправляется, когда вызывается метод выхода.

sender

Как выше: класс пользователя, который только что вышел, или None , если пользователь не был авторизован.

request

Текущий экземпляр HttpRequest.

user

Экземпляр пользователя, который только что вышел, или None , если пользователь не был авторизован.

user_login_failed()

Отправляется, когда пользователь не смог успешно войти.

sender

Имя модуля, используемого для аутентификации.

credentials

Словарь ключевых аргументов, содержащий данные пользователя, которые были переданы в authenticate() или ваш собственный бэкэнд аутентификации. Данные, соответствующие набору «конфиденциальных» шаблонов (включая пароль), не будут отправлены открыто как часть сигнала.

Справочник по бэкендам аутентификации

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

Доступные бэкэнды аутентификации

В django.contrib.auth.backends доступны следующие бэкэнды:

class ModelBackend

Это по умолчанию используемый Django механизм аутентификации. Он выполняет аутентификацию, используя учетные данные, состоящие из идентификатора пользователя и пароля. Для стандартной модели пользователей Django идентификатором пользователя является имя пользователя, для настраиваемых моделей пользователей — поле, указанное в USERNAME_FIELD (см. Настройка пользователей и аутентификации).

Он также обрабатывает стандартную модель разрешений, как определено для User и PermissionsMixin.

has_perm(), get_all_permissions(), get_user_permissions() и get_group_permissions() позволяют передавать объект в качестве параметра для разрешений, специфичных для объекта, но этот механизм не реализует их, кроме как возвращает пустой набор разрешений, если obj is not None.

authenticate(username=None, password=None, **kwargs)

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

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(self, user_obj, app_label)

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

user_can_authenticate()

Новое в Django 1.10.

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

class AllowAllUsersModelBackend

Новое в Django 1.10.

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

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

class RemoteUserBackend

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

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

RemoteUserBackend.create_unknown_user

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

RemoteUserBackend.authenticate(remote_user)

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

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

RemoteUserBackend.clean_username(username)

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

RemoteUserBackend.configure_user(user)

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

RemoteUserBackend.user_can_authenticate()

Новое в Django 1.10.

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

class AllowAllUsersRemoteUserBackend

Новое в Django 1.10.

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

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

get_user(request) [source]

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

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

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