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 символом в этом случае.

Имена пользователей и Unicode

Django изначально принимал только символы ASCII в именах пользователей. Хотя это не было намеренным выбором, символы Unicode всегда принимались при использовании Python 3. В Django 1.10 официально была добавлена поддержка Unicode в именах пользователей, сохраняя поведение, учитывающее только ASCII, при использовании Python 2.

first_name

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

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

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

В более старых версиях это также возвращает False , если пароль является None или пустой строкой, или если пароль использует хэширователь, который не находится в настройке PASSWORD_HASHERS. Такое поведение считается ошибкой, так как это препятствует пользователям с такими паролями запрашивать сброс пароля.

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, password, **extra_fields)

То же, что и create_user(), но устанавливает is_staff и is_superuser в значение True.

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'.

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

Максимальная длина поля max_length увеличена с 80 до 150 символов.

permissions

Поле "многие-ко-многим" для Permission:

group.permissions.set([permission_list])
group.permissions.add(permission, permission, ...)
group.permissions.remove(permission, permission, ...)
group.permissions.clear()

Валидаторы

class validators.ASCIIUsernameValidator

Валидатор поля, разрешающий только латинские буквы и цифры, а также @, ., +, -, и _.

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

Доступные модули аутентификации

Следующие модули доступны в django.contrib.auth.backends:

class ModelBackend

Это стандартный модуль аутентификации, используемый Django. Он выполняет аутентификацию, используя учетные данные, состоящие из идентификатора пользователя и пароля. Для стандартной модели пользователей Django идентификатор пользователя — это имя пользователя, для пользовательских моделей — поле, указанное в USERNAME_FIELD (см. Настройка пользователей и аутентификации).

Он также обрабатывает стандартную модель разрешений, как определено для User и PermissionsMixin.

has_perm(), get_all_permissions(), get_user_permissions() и get_group_permissions() позволяют передавать объект в качестве параметра для разрешений, специфичных для объекта, но этот модуль не реализует их, кроме возвращения пустого набора разрешений, если 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, разрешены.

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

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

Добавлен аргумент request. Поддержка переопределений методов, которые его не принимают, будет удалена в Django 3.1.

user_can_authenticate()

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

class AllowAllUsersRemoteUserBackend

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

Вспомогательные функции

get_user(request) [source]

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

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

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