django.contrib.auth

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

User модель

Поля

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, чтобы узнать, был ли он заполнен 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.

AnonymousUser объект

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 самостоятельно, но они используются в веб-запросах, как описано в следующем разделе.

Permission

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-модель.

Group

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

Это по умолчанию используемый 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)

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

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(self, user_obj, app_label)

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

class RemoteUserBackend

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

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

RemoteUserBackend.create_unknown_user

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

RemoteUserBackend.authenticate(remote_user)

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

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

RemoteUserBackend.clean_username(username)

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

RemoteUserBackend.configure_user(user)

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