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 символов.

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

Длина max_length увеличилась с 30 до 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 передаются в метод __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

Валидатор поля, позволяющий символы Unicode, а также @, ., +, -, и _. По умолчанию используется для 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)

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

configure_user(request, user)

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

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

user_can_authenticate()

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

class AllowAllUsersRemoteUserBackend

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

Служебные функции

get_user(request)

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

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

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