django.contrib.auth

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

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 символов.

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

Длина max_length увеличена с 30 до 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 возвращают 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.

Если 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 передаются методу User’s __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

Обязательно. Длина не более 80 символов. Допустимы любые символы. Пример: '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.

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

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

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

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

configure_user(user)

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

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() не возвращает пользователя или если хэш аутентификации сессии не валиден.