django.contrib.auth

Поля

classmodels.User

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

username

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

Для многих вариантов использования длины max_length будет достаточно. Если вам требуется большая длина, используйте пользовательскую модель пользователя.

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 всегда возвращают False для неактивных пользователей.

is_superuser

Логическое значение. Считает, что у пользователя есть все разрешения, не назначая ему какие-либо разрешения отдельно.

last_login

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

date_joined

Дата и время создания учётной записи.

Атрибуты

classmodels.User

is_authenticated

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

is_anonymous

Атрибут только для чтения, значение которого всегда равно False. Он позволяет различать объекты User и AnonymousUser. Как правило, вместо этого атрибута следует использовать is_authenticated.

Методы

classmodels.User

get_username()

Возвращает имя пользователя. Поскольку модель 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)

acheck_password(raw_password)

Асинхронная версия: acheck_password()

Возвращает True, если указанный исходный пароль верен для пользователя. (При сравнении выполняется хеширование пароля.)

set_unusable_password()

Отмечает пользователя как не имеющего пароля, обновляя метаданные в поле password. Это не то же самое, что пустая строка в качестве пароля. Метод check_password() для этого пользователя никогда не вернёт True. Не сохраняет объект User.

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

Ограничение сброса пароля

Пользователи с непригодным для использования паролем не смогут запросить письмо для сброса пароля через PasswordResetView.

has_usable_password()

Возвращает False, если для этого пользователя был вызван set_unusable_password().

get_user_permissions(obj=None)

aget_user_permissions(obj=None)

Асинхронная версия: aget_user_permissions()

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

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

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

Добавлен метод aget_user_permissions().

get_group_permissions(obj=None)

aget_group_permissions(obj=None)

Асинхронная версия: aget_group_permissions()

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

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

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

Добавлен метод aget_group_permissions().

get_all_permissions(obj=None)

aget_all_permissions(obj=None)

Асинхронная версия: aget_all_permissions()

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

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

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

Добавлен метод aget_all_permissions().

has_perm(perm, obj=None)

ahas_perm(perm, obj=None)

Асинхронная версия: ahas_perm()

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

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

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

Добавлен метод ahas_perm().

has_perms(perm_list, obj=None)

ahas_perms(perm_list, obj=None)

Асинхронная версия: ahas_perms()

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

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

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

Добавлен метод ahas_perms().

has_module_perms(package_name)

ahas_module_perms(package_name)

Асинхронная версия: ahas_module_perms()

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

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

Добавлен метод ahas_module_perms().

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)

acreate_user(username, email=None, password=None, **extra_fields)

Асинхронная версия: acreate_user()

Создаёт, сохраняет и возвращает объект User.

Значения username и password устанавливаются в соответствии с переданными аргументами. Доменная часть значения email автоматически преобразуется в нижний регистр, а у возвращаемого объекта User значение is_active устанавливается в True.

Если пароль не указан, будет вызван set_unusable_password().

Если адрес электронной почты не указан, полю email будет присвоена пустая строка.

Именованные аргументы extra_fields передаются в метод __init__ объекта User, что позволяет задавать произвольные поля пользовательской модели пользователя.

Примеры использования см. в разделе Создание пользователей.

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

Добавлен метод acreate_user().

create_superuser(username, email=None, password=None, **extra_fields)

acreate_superuser(username, email=None, password=None, **extra_fields)

Асинхронная версия: acreate_superuser()

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

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

Добавлен метод acreate_superuser().

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, если он там единственный, или вызывает исключение.

Поля

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

classmodels.Permission

name

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

content_type

Обязательное поле. Внешний ключ на модель ContentType.

codename

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

Методы

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

Поля

У объектов Group есть следующие поля:

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

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

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

class BaseBackend [исходный код]

Базовый класс, предоставляющий реализации по умолчанию для всех необходимых методов. По умолчанию он отклоняет всех пользователей и не предоставляет никаких разрешений.

get_user_permissions(user_obj, obj=None) [исходный код]

aget_user_permissions(user_obj, obj=None)

Асинхронная версия: aget_user_permissions()

Возвращает пустое множество.

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

Добавлена функция aget_user_permissions().

get_group_permissions(user_obj, obj=None) [исходный код]

aget_group_permissions(user_obj, obj=None)

Асинхронная версия: aget_group_permissions()

Возвращает пустое множество.

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

Добавлена функция aget_group_permissions().

get_all_permissions(user_obj, obj=None) [исходный код]

aget_all_permissions(user_obj, obj=None)

Асинхронная версия: aget_all_permissions()

Использует get_user_permissions() и get_group_permissions(), чтобы получить набор строк разрешений, которыми обладает user_obj.

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

Добавлена функция aget_all_permissions().

has_perm(user_obj, perm, obj=None) [исходный код]

ahas_perm(user_obj, perm, obj=None)

Асинхронная версия: ahas_perm()

Использует get_all_permissions(), чтобы проверить, есть ли у user_obj строка разрешения perm.

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

Добавлена функция ahas_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) [исходный код]

aauthenticate(request, username=None, password=None, **kwargs)

Асинхронная версия: aauthenticate()

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

request — это HttpRequest; его значение может быть None, если он не был передан в authenticate() (который передает его бэкенду).

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

Добавлена функция aauthenticate().

get_user_permissions(user_obj, obj=None) [исходный код]

aget_user_permissions(user_obj, obj=None)

Асинхронная версия: aget_user_permissions()

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

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

Добавлена функция aget_user_permissions().

get_group_permissions(user_obj, obj=None) [исходный код]

aget_group_permissions(user_obj, obj=None)

Асинхронная версия: aget_group_permissions()

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

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

Добавлена функция aget_group_permissions().

get_all_permissions(user_obj, obj=None) [исходный код]

aget_all_permissions(user_obj, obj=None)

Асинхронная версия: aget_all_permissions()

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

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

Добавлена функция aget_all_permissions().

has_perm(user_obj, perm, obj=None) [исходный код]

ahas_perm(user_obj, perm, obj=None)

Асинхронная версия: ahas_perm()

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

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

Добавлена функция ahas_perm().

has_module_perms(user_obj, app_label) [исходный код]

ahas_module_perms(user_obj, app_label)

Асинхронная версия: ahas_module_perms()

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

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

Добавлена функция ahas_module_perms().

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) [исходный код]

aauthenticate(request, remote_user)

Асинхронная версия: aauthenticate()

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

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

request — это HttpRequest; его значение может быть None, если он не был передан в authenticate() (который передает его бэкенду).

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

Добавлена функция aauthenticate().

clean_username(username) [исходный код]

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

configure_user(request, user, created=True) [исходный код]

aconfigure_user(request, user, created=True)

Асинхронная версия: aconfigure_user()

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

Настройку можно выполнять однократно при создании пользователя (created имеет значение True) или для уже существующих пользователей (created имеет значение False), чтобы синхронизировать атрибуты удаленной и локальной систем.

request — это HttpRequest; его значение может быть None, если он не был передан в authenticate() (который передает его бэкенду).

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

Добавлена функция aconfigure_user().

user_can_authenticate()

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

class AllowAllUsersRemoteUserBackend [исходный код]

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