django.contrib.auth

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

User модель

class models.User

Поля

class models.User

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

username

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

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

first_name

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

last_name

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

email

Необязательно (blank=True). Адрес электронной почты.

password

Требуется. Хеш пароля и метаданные о нем. (Django не хранит необработанный пароль.) Необработанные пароли могут быть произвольно длинными и содержать любые символы. См. password documentation.

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

Асинхронная версия: acheck_password()

Возвращает True, если заданная необработанная строка является правильным паролем для пользователя. (При сравнении происходит хеширование пароля).

Changed in Django 5.0:

Был добавлен метод acheck_password().

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>". (см. документацию по permissions). Если пользователь неактивен, этот метод всегда будет возвращать False. Для активного суперпользователя этот метод всегда будет возвращать True.

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

has_perms(perm_list, obj=None)

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

Пример использования см. в Creating users.

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, с такими отличиями:

На практике вам, скорее всего, не понадобится самостоятельно использовать объекты AnonymousUser, но они используются в веб-запросах, как объясняется в следующем разделе.

Permission модель

class models.Permission

Поля

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

class models.Permission
name

Требуется. 255 символов или меньше. Пример: 'Can vote'.

content_type

Требуется. Ссылка на таблицу базы данных django_content_type, которая содержит запись для каждой установленной модели.

codename

Требуется. Не более 100 символов. Пример: 'can_vote'.

Методы

Объекты Permission имеют стандартные методы доступа к данным, как и любые другие Django model.

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.

Сигналы входа и выхода из системы

Фреймворк auth использует следующие signals, которые могут быть использованы для уведомления, когда пользователь входит или выходит из системы.

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. Информацию о том, как их использовать и как писать свои собственные бэкенды аутентификации, смотрите в Other authentication sources section User authentication guide.

Доступные бэкенды аутентификации

В 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 (см. Customizing Users and authentication).

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

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

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

create_unknown_user

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

authenticate(request, remote_user)

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

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

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() (который передает его бэкенду).

user_can_authenticate()

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

class AllowAllUsersRemoteUserBackend

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

Функции полезности

get_user(request)[исходный код]
aget_user(request)

Асинхронная версия: aget_user()

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

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

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

Changed in Django 4.1.8:

Добавлена обратная проверка с помощью SECRET_KEY_FALLBACKS.

Changed in Django 5.0:

Добавлена функция aget_user().

Вернуться на верх