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, с возможностью настроить поведение с помощью User.username_validator.

first_name

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

last_name

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

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

Длина max_length увеличена с 30 до 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 этому атрибуту.

username_validator

Указывает экземпляр валидатора, используемого для проверки имён пользователей. По умолчанию validators.UnicodeUsernameValidator.

Чтобы изменить валидатор имён пользователей по умолчанию, можно унаследовать от модели User и установить этот атрибут на другой экземпляр валидатора. Например, для использования имён пользователей ASCII:

from django.contrib.auth.models import User
from django.contrib.auth.validators import ASCIIUsernameValidator

class CustomUser(User):
    username_validator = ASCIIUsernameValidator()

    class Meta:
        proxy = True  # If no new field is added.

Методы

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

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

has_perms(perm_list, obj=None)

Возвращает True, если пользователь имеет каждое из указанных разрешений, где каждое разрешение имеет формат "<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

Валидатор поля, допускающий только 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 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()

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

class AllowAllUsersModelBackend

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

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

RemoteUserBackend.clean_username(username)

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

RemoteUserBackend.configure_user(user)

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

RemoteUserBackend.user_can_authenticate()

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

class AllowAllUsersRemoteUserBackend

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

Функции-помощники

get_user(request) [source]

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

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

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