django.contrib.auth

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

Пользователь

Поля

class models.User

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

username

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

first_name

Необязательное поле. Не более 30 символов.

last_name

Необязательное поле. Не более 30 символов.

email

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

password

Обязательное поле. Хеш пароля и метаданные о нём. (Django не хранит исходный пароль.) Исходные пароли могут быть произвольной длины и содержать любые символы. См. документацию по паролям.

groups

Связь «многие ко многим» с Group

user_permissions

Связь «многие ко многим» с Permission

is_staff

Булево значение. Определяет, может ли этот пользователь получить доступ к админской панели.

is_active

Булево значение. Определяет, активен ли данный пользовательский аккаунт. Рекомендуется устанавливать это значение в False, а не удалять аккаунты; таким образом, при наличии у ваших приложений внешних ключей к пользователям, внешние ключи не сломаются.

Это не обязательно управляет возможностью пользователя войти в систему. Модули аутентификации не обязаны проверять флаг is_active, и стандартные модули не делают этого. Если вы хотите отклонять вход на основе того, что is_active имеет значение False, вы должны проверить это в собственном представлении входа или в пользовательском модуле аутентификации. Однако, AuthenticationForm, используемый представлением login() (по умолчанию), проверяет это условие, как и методы проверки разрешений, такие как has_perm(), и аутентификация в админской панели Django. Все эти функции/методы вернут False для неактивных пользователей.

is_superuser

Булево значение. Указывает, что этот пользователь имеет все разрешения без явного их назначения.

last_login

Дата и время последнего входа пользователя.

Это поле будет null если пользователь никогда не входил в систему. Ранее оно по умолчанию устанавливалось на текущую дату/время.

date_joined

Дата и время создания учетной записи. По умолчанию устанавливается на текущую дату/время при создании учетной записи.

Методы

class models.User

get_username()

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

is_anonymous()

Всегда возвращает False. Это способ различения объектов User и AnonymousUser. В целом, следует предпочитать использование метода is_authenticated().

is_authenticated()

Всегда возвращает True (в отличие от AnonymousUser.is_authenticated(), который всегда возвращает False). Это способ определить, был ли пользователь аутентифицирован. Это не подразумевает никаких разрешений и не проверяет, активен ли пользователь или у него есть действительная сессия. Хотя обычно вы вызываете этот метод для request.user, чтобы узнать, был ли он заполнен middleware AuthenticationMiddleware (представляющим текущего вошедшего в систему пользователя), следует знать, что этот метод возвращает True для любого экземпляра User.

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_group_permissions(obj=None)

Возвращает множество строк разрешений, которыми пользователь обладает через свои группы.

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

get_all_permissions(obj=None)

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

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

has_perm(perm, obj=None)

Возвращает True, если пользователь обладает указанным разрешением, где perm имеет формат "<app label>.<permission codename>". (см. документацию по разрешениям). Если пользователь неактивен, этот метод всегда возвращает False.

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

has_perms(perm_list, obj=None)

Возвращает True, если пользователь обладает каждым из указанных разрешений, где каждое perm имеет формат "<app label>.<permission codename>". Если пользователь неактивен, этот метод всегда возвращает False.

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

has_module_perms(package_name)

Возвращает True, если пользователь обладает какими-либо разрешениями в указанном пакете (метке приложения Django). Если пользователь неактивен, этот метод всегда возвращает False.

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.

Пользователи без имени

class models.AnonymousUser

django.contrib.auth.models.AnonymousUser — это класс, реализующий интерфейс django.contrib.auth.models.User, с такими отличиями:

• id всегда None.
• username всегда пустая строка.
• get_username() всегда возвращает пустую строку.
• is_staff и is_superuser всегда False.
• is_active всегда False.
• groups и user_permissions всегда пустые.
• is_anonymous() возвращает True вместо False.
• is_authenticated() возвращает False вместо True.
• set_password(), check_password(), save() и delete() вызывают NotImplementedError.

AnonymousUser.get_username() был добавлен, чтобы лучше отразить django.contrib.auth.models.User.

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

Разрешения

class models.Permission

Поля

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

class models.Permission

name

Обязательное. Не более 255 символов. Пример: 'Can vote'.

Предел символов max_length увеличен с 50 до 255.

content_type

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

codename

Обязательное. Не более 100 символов. Пример: 'can_vote'.

Методы

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

Группа

class models.Group

Поля

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

class models.Group

name

Обязательное. Не более 80 символов. Допускаются любые символы. Пример: 'Awesome Users'.

permissions

Множественное поле для Permission:

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

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

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

user_logged_in()

Отправляется, когда пользователь успешно вошёл.

Аргументы, отправляемые с этим сигналом:

sender

Класс пользователя, который только что вошёл.

request

Текущий экземпляр HttpRequest.

user

Экземпляр пользователя, который только что вошёл.

user_logged_out()

Отправляется, когда вызывается метод выхода.

sender

Как выше: класс пользователя, который только что вышел, или None если пользователь не был авторизован.

request

Текущий экземпляр HttpRequest.

user

Экземпляр пользователя, который только что вышел, или None если пользователь не был авторизован.

user_login_failed()

Отправляется, когда пользователь не смог войти успешно.

sender

Имя модуля, используемого для аутентификации.

credentials

Словарь ключевых аргументов, содержащий учетные данные пользователя, которые были переданы в authenticate() или в ваш собственный бэкэнд аутентификации. Учетные данные, соответствующие набору «чувствительных» шаблонов (включая пароль), не будут отправлены открыто в качестве части сигнала.

Справочник по бэкендам аутентификации

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

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

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

class ModelBackend [source]

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

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

has_perm(), get_all_permissions(), get_user_permissions() и get_group_permissions() позволяют передавать объект в качестве параметра для разрешений, специфичных для объекта, но этот механизм не реализует их, кроме как возвращает пустой набор разрешений, если obj is not None.

authenticate(username=None, password=None, **kwargs) [source]

Попытка аутентификации username с помощью password, вызывая User.check_password. Если username не указан, он пытается получить имя пользователя из kwargs используя ключ CustomUser.USERNAME_FIELD. Возвращает аутентифицированного пользователя или None.

get_user_permissions(user_obj, obj=None) [source]

Возвращает набор строк разрешений, имеющихся у user_obj от собственных разрешений пользователя. Возвращает пустой набор, если is_anonymous() или is_active равна False.

get_group_permissions(user_obj, obj=None) [source]

Возвращает набор строк разрешений, имеющихся у user_obj из разрешений групп, к которым он принадлежит. Возвращает пустой набор, если is_anonymous() или is_active равна False.

get_all_permissions(user_obj, obj=None) [source]

Возвращает набор строк разрешений, имеющихся у user_obj, включая как разрешения пользователя, так и группы разрешений. Возвращает пустой набор, если is_anonymous() или is_active равна False.

has_perm(user_obj, perm, obj=None) [source]

Использует get_all_permissions() для проверки наличия разрешения user_obj у perm. Возвращает False если пользователь не is_active.

has_module_perms(self, user_obj, app_label) [source]

Возвращает, имеет ли user_obj какие-либо разрешения на приложение app_label.

class RemoteUserBackend [source]

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

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

RemoteUserBackend.create_unknown_user

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

RemoteUserBackend.authenticate(remote_user) [source]

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

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

RemoteUserBackend.clean_username(username) [source]

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

RemoteUserBackend.configure_user(user) [source]

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