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 admin возвращают 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

Валидатор поля, допускающий символы Юникода, а также @, ., +, -, и _. По умолчанию используется для User.username.

Сигналы входа и выхода

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

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)

Выполняет любые очищения имени пользователя (например, удаление информации из 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)

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

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

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