django.contrib.auth

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

User модель

Поля

class models.User

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

username

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

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

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

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

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

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

first_name

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

last_name

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

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

Изменено в 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 для сравнений!

Чтобы атрибуты is_authenticated и is_anonymous также работали как методы, атрибуты являются CallableBool объектами. Таким образом, до тех пор, пока срок действия устаревания не закончится в Django 2.0, вы не можете сравнивать эти свойства с помощью оператора is. То есть, request.user.is_authenticated is True всегда оцениваются как False.

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 передаются в метод __init__ объекта 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() или в ваш пользовательский модуль аутентификации. Учетные данные, соответствующие набору «чувствительных» шаблонов (включая пароль), не будут отправляться открытым текстом в составе сигнала.

request

Объект HttpRequest, если он был предоставлен в authenticate().

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

Аргумент request был добавлен.

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

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

Доступные модули аутентификации

В 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(request, username=None, password=None, **kwargs)

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

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

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

Аргумент request был добавлен.

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

Новое в 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, используемый LoginView, переопределяя метод confirm_login_allowed(), так как он отклоняет неактивных пользователей.

class RemoteUserBackend

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

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

RemoteUserBackend.create_unknown_user

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

RemoteUserBackend.authenticate(request, remote_user)

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

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

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

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