django.contrib.auth

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

User модель

class models.User

Поля

class models.User

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

username

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

Значения по умолчанию обычно достаточно для многих случаев использования. Если вам требуется большая длина, используйте пользовательскую модель. При использовании 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 может быть заменена, следует использовать этот метод вместо прямой ссылки на атрибут 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_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 передаются в метод User’s __init__, чтобы позволить устанавливать произвольные поля в модели пользователя.

См. Создание пользователей для примера использования.

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

authenticate(request, remote_user)

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

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

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

clean_username(username)

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

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

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