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

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)

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

Если 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.

with_perm(perm, is_active=True, include_superusers=True, backend=None, obj=None)

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

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

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)

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

authenticate(request, remote_user)

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

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

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

clean_username(username)

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

configure_user(request, user, created=True)

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

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

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

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

Добавлен аргумент created.

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(). Если проверка завершается неудачно, и предоставлены значения SECRET_KEY_FALLBACKS, он проверяет сеанс по каждому резервному ключу, используя get_session_auth_fallback_hash().

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

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

Была добавлена проверка по резервным значениям SECRET_KEY_FALLBACKS.