Использование системы аутентификации Django

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

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

User объекты

User объекты являются ядром системы аутентификации. Они обычно представляют людей, взаимодействующих с вашим сайтом, и используются для таких задач, как ограничение доступа, регистрация пользовательских профилей, связывание контента с создателями и т. д. В рамках фреймворка аутентификации Django существует только один класс пользователей, то есть 'superusers' или администраторские 'staff' пользователи — это просто пользовательские объекты со специальными атрибутами, а не разные классы пользовательских объектов.

Основные атрибуты стандартного пользователя:

• username
• password
• email
• first_name
• last_name

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

Создание пользователей

Наиболее прямой способ создания пользователей — использование встроенной функции create_user():

>>> from django.contrib.auth.models import User
>>> user = User.objects.create_user("john", "lennon@thebeatles.com", "johnpassword")

# At this point, user is a User object that has already been saved
# to the database. You can continue to change its attributes
# if you want to change other fields.
>>> user.last_name = "Lennon"
>>> user.save()

Если у вас установлен Django админ, вы также можете создать пользователей интерактивно.

Создание суперпользователей

Создайте суперпользователей с помощью команды createsuperuser:

$ python manage.py createsuperuser --username=joe --email=joe@example.com

...\> py manage.py createsuperuser --username=joe --email=joe@example.com

Вам будет предложено ввести пароль. После его ввода пользователь будет создан немедленно. Если вы опустите опции --username или --email, система запросит эти значения.

Изменение паролей

Django не хранит исходные (текстовые) пароли в модели пользователя, а только хэш (см. документацию о том, как обрабатываются пароли для получения полной информации). Поэтому не пытайтесь напрямую изменять атрибут пароля пользователя. Именно поэтому для создания пользователя используется вспомогательная функция.

Чтобы изменить пароль пользователя, у вас есть несколько вариантов:

manage.py changepassword *username* предоставляет способ изменения пароля пользователя из командной строки. Система запросит изменение пароля указанного пользователя, который необходимо ввести дважды. Если они совпадают, новый пароль будет изменён немедленно. Если вы не укажете пользователя, команда попытается изменить пароль пользователя, имя которого совпадает с текущим именем пользователя системы.

Вы также можете изменить пароль программно, используя set_password():

>>> from django.contrib.auth.models import User
>>> u = User.objects.get(username="john")
>>> u.set_password("new password")
>>> u.save()

Если у вас установлен Django админ, вы также можете изменить пароли пользователей на админских страницах системы аутентификации.

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

Изменение пароля пользователя выведет всех его сессии. Для получения подробностей см. Недействительность сеанса при изменении пароля.

Аутентификация пользователей

authenticate(request=None, **credentials)

Используйте authenticate() для проверки набора учетных данных. Она принимает учетные данные в качестве аргументов ключевых слов, username и password для стандартного случая, проверяет их по каждому обработчику аутентификации и возвращает объект User, если учетные данные действительны для обработчика. Если учетные данные недействительны ни для одного обработчика или если обработчик вызывает PermissionDenied, она возвращает None. Например:

from django.contrib.auth import authenticate

user = authenticate(username="john", password="secret")
if user is not None:
    # A backend authenticated the credentials
    ...
else:
    # No backend authenticated the credentials
    ...

request — это необязательный HttpRequest, который передаётся в метод authenticate() обработчиков аутентификации.

Примечание

Это низкоуровневый способ проверки набора учетных данных; например, он используется RemoteUserMiddleware. Если вы не пишете собственную систему аутентификации, вам, вероятно, не потребуется это. Вместо этого, если вы ищете способ входа пользователя, воспользуйтесь LoginView.

Разрешения и авторизация

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

Она используется сайтом Django админ, но вы можете использовать её и в собственном коде.

Сайт Django админ использует разрешения следующим образом:

• Доступ к просмотру объектов ограничен пользователями с разрешением «просмотр» или «изменение» для данного типа объекта.
• Доступ к форме «добавление» и добавлению объекта ограничен пользователями с разрешением «добавление» для данного типа объекта.
• Доступ к списку изменений, форме «изменение» и изменению объекта ограничен пользователями с разрешением «изменение» для данного типа объекта.
• Доступ к удалению объекта ограничен пользователями с разрешением «удаление» для данного типа объекта.

Разрешения могут быть установлены не только для типа объекта, но и для конкретного экземпляра объекта. Используя методы has_view_permission(), has_add_permission(), has_change_permission() и has_delete_permission(), предоставляемые классом ModelAdmin, можно настроить разрешения для различных экземпляров объектов одного типа.

User объекты имеют два поля many-to-many: groups и user_permissions. User объекты могут обращаться к связанным объектам так же, как и любой другой модель Django:

myuser.groups.set([group_list])
myuser.groups.add(group, group, ...)
myuser.groups.remove(group, group, ...)
myuser.groups.clear()
myuser.user_permissions.set([permission_list])
myuser.user_permissions.add(permission, permission, ...)
myuser.user_permissions.remove(permission, permission, ...)
myuser.user_permissions.clear()

Стандартные разрешения

Когда django.contrib.auth указан в настройке INSTALLED_APPS, это гарантирует, что четыре стандартных разрешения — добавление, изменение, удаление и просмотр — создаются для каждой модели Django, определённой в одном из ваших установленных приложений.

Эти разрешения будут созданы при запуске manage.py migrate; в первый раз при запуске migrate после добавления django.contrib.auth в INSTALLED_APPS будут созданы стандартные разрешения для всех ранее установленных моделей, а также для любых новых моделей, которые устанавливаются в этот момент. После этого, он будет создавать стандартные разрешения для новых моделей каждый раз, когда вы запускаете manage.py migrate (функция, создающая разрешения, связана с сигналом post_migrate).

Предполагая, что у вас есть приложение с app_label foo и моделью с именем Bar, для тестирования основных разрешений следует использовать:

• добавление: user.has_perm('foo.add_bar')
• изменение: user.has_perm('foo.change_bar')
• удаление: user.has_perm('foo.delete_bar')
• просмотр: user.has_perm('foo.view_bar')

Модель Permission редко используется напрямую.

Группы

Модели django.contrib.auth.models.Group — это общий способ категоризации пользователей, чтобы вы могли применять разрешения или другие метки к этим пользователям. Пользователь может принадлежать к любому количеству групп.

Пользователь, входящий в группу, автоматически получает разрешения, предоставленные этой группе. Например, если группа Site editors имеет разрешение can_edit_home_page, любой пользователь в этой группе будет иметь это разрешение.

Помимо разрешений, группы являются удобным способом категоризации пользователей для присвоения им метки или расширенных функциональных возможностей. Например, вы можете создать группу 'Special users', и вы можете написать код, который, скажем, предоставит им доступ к закрытой для членов части вашего сайта или отправит им закрытые для членов электронные письма.

Программное создание разрешений

Хотя настраиваемые разрешения можно определять в классе Meta модели, вы также можете создавать разрешения напрямую. Например, вы можете создать разрешение can_publish для модели BlogPost в myapp:

from myapp.models import BlogPost
from django.contrib.auth.models import Permission
from django.contrib.contenttypes.models import ContentType

content_type = ContentType.objects.get_for_model(BlogPost)
permission = Permission.objects.create(
    codename="can_publish",
    name="Can Publish Posts",
    content_type=content_type,
)

Затем разрешение может быть назначено пользователю User через его атрибут user_permissions или группе Group через его атрибут permissions.

content_type = ContentType.objects.get_for_model(
    BlogPostProxy, for_concrete_model=False
)

Кэширование разрешений

Класс ModelBackend кеширует разрешения на объекте пользователя после первого запроса к ним для проверки разрешений. Обычно это нормально для цикла запрос-ответ, так как разрешения обычно не проверяются сразу после добавления (например, в админке). Если вы добавляете разрешения и проверяете их сразу после этого, например, в тесте или представлении, самым простым решением является повторный запрос пользователя из базы данных. Например:

from django.contrib.auth.models import Permission, User
from django.contrib.contenttypes.models import ContentType
from django.shortcuts import get_object_or_404

from myapp.models import BlogPost


def user_gains_perms(request, user_id):
    user = get_object_or_404(User, pk=user_id)
    # any permission check will cache the current set of permissions
    user.has_perm("myapp.change_blogpost")

    content_type = ContentType.objects.get_for_model(BlogPost)
    permission = Permission.objects.get(
        codename="change_blogpost",
        content_type=content_type,
    )
    user.user_permissions.add(permission)

    # Checking the cached permission set
    user.has_perm("myapp.change_blogpost")  # False

    # Request new instance of User
    # Be aware that user.refresh_from_db() won't clear the cache.
    user = get_object_or_404(User, pk=user_id)

    # Permission cache is repopulated from the database
    user.has_perm("myapp.change_blogpost")  # True

    ...

Прокси-модели

Прокси-модели работают точно так же, как и конкретные модели. Разрешения создаются с использованием собственного типа содержимого прокси-модели. Прокси-модели не наследуют разрешения конкретной модели, от которой они унаследованы:

class Person(models.Model):
    class Meta:
        permissions = [("can_eat_pizzas", "Can eat pizzas")]


class Student(Person):
    class Meta:
        proxy = True
        permissions = [("can_deliver_pizzas", "Can deliver pizzas")]

>>> # Fetch the content type for the proxy model.
>>> content_type = ContentType.objects.get_for_model(Student, for_concrete_model=False)
>>> student_permissions = Permission.objects.filter(content_type=content_type)
>>> [p.codename for p in student_permissions]
['add_student', 'change_student', 'delete_student', 'view_student',
'can_deliver_pizzas']
>>> for permission in student_permissions:
...     user.user_permissions.add(permission)
...
>>> user.has_perm("app.add_person")
False
>>> user.has_perm("app.can_eat_pizzas")
False
>>> user.has_perms(("app.add_student", "app.can_deliver_pizzas"))
True

Аутентификация в веб-запросах

Django использует сессии и middleware для подключения системы аутентификации к request objects.

Они предоставляют атрибут request.user в каждом запросе, который представляет текущего пользователя. Если текущий пользователь не вошел в систему, этот атрибут будет установлен на экземпляр AnonymousUser, в противном случае — на экземпляр User.

Вы можете их отличить с помощью is_authenticated, например:

if request.user.is_authenticated:
    # Do something for authenticated users.
    ...
else:
    # Do something for anonymous users.
    ...

Как войти в систему пользователю

Если у вас есть аутентифицированный пользователь, которого вы хотите прикрепить к текущей сессии, это делается с помощью функции login().

login(request, user, backend=None)

Чтобы войти в систему пользователя из представления, используйте login(). Она принимает объект HttpRequest и объект User. login() сохраняет ID пользователя в сессии, используя фреймворк сессий Django.

Обратите внимание, что любые данные, заданные во время анонимной сессии, сохраняются в сессии после входа в систему пользователя.

В этом примере показано, как вы можете использовать как authenticate(), так и login():

from django.contrib.auth import authenticate, login


def my_view(request):
    username = request.POST["username"]
    password = request.POST["password"]
    user = authenticate(request, username=username, password=password)
    if user is not None:
        login(request, user)
        # Redirect to a success page.
        ...
    else:
        # Return an 'invalid login' error message.
        ...

Выбор аутентификационного бэкенда

Когда пользователь входит в систему, ID пользователя и бэкенд, который использовался для аутентификации, сохраняются в сессии пользователя. Это позволяет одному и тому же аутентификационному бэкенду извлекать данные пользователя при последующем запросе. Аутентификационный бэкенд, который будет сохранен в сессии, выбирается следующим образом:

1. Используйте значение необязательного аргумента backend, если он указан.
2. Используйте значение атрибута user.backend, если он присутствует. Это позволяет сопрячь authenticate() и login(): authenticate() устанавливает атрибут user.backend на возвращаемом объекте пользователя.
3. Используйте значение backend в AUTHENTICATION_BACKENDS, если оно единственное.
4. В противном случае вызовите исключение.

В случаях 1 и 2 значение аргумента backend или атрибута user.backend должно быть строкой импорта с точками (как в AUTHENTICATION_BACKENDS), а не фактический класс бэкенда.

Как выйти из системы пользователю

logout(request)

Чтобы выйти из системы пользователя, вошедшего в систему через django.contrib.auth.login(), используйте django.contrib.auth.logout() в представлении. Она принимает объект HttpRequest и не возвращает значения. Пример:

from django.contrib.auth import logout


def logout_view(request):
    logout(request)
    # Redirect to a success page.

Обратите внимание, что logout() не генерирует никаких ошибок, если пользователь не был авторизован.

При вызове logout() данные сессии текущего запроса полностью очищаются. Все существующие данные удаляются. Это предотвращает использование одного и того же веб-браузера другим человеком для входа в систему и доступа к данным сессии предыдущего пользователя. Если вы хотите поместить что-либо в сессию, что будет доступно пользователю сразу после выхода, сделайте это после вызова django.contrib.auth.logout().

Ограничение доступа для авторизованных пользователей

Прямой способ

Прямой способ ограничить доступ к страницам — проверить request.user.is_authenticated и либо перенаправить на страницу входа:

from django.conf import settings
from django.shortcuts import redirect


def my_view(request):
    if not request.user.is_authenticated:
        return redirect(f"{settings.LOGIN_URL}?next={request.path}")
    # ...

…или отобразить сообщение об ошибке:

from django.shortcuts import render


def my_view(request):
    if not request.user.is_authenticated:
        return render(request, "myapp/login_error.html")
    # ...

Декоратор login_required

login_required(redirect_field_name='next', login_url=None)

В качестве удобного варианта вы можете использовать декоратор login_required():

from django.contrib.auth.decorators import login_required


@login_required
def my_view(request):
    ...

login_required() делает следующее:

• Если пользователь не авторизован, он перенаправляется на settings.LOGIN_URL, передавая текущий абсолютный путь в параметре запроса. Пример: /accounts/login/?next=/polls/3/.
• Если пользователь авторизован, представление выполняется в обычном режиме. Код представления может считать, что пользователь авторизован.

По умолчанию путь, на который должен быть перенаправлен пользователь после успешной аутентификации, хранится в параметре запроса под названием "next". Если вы хотите использовать другое имя для этого параметра, декоратор login_required() принимает необязательный параметр redirect_field_name:

from django.contrib.auth.decorators import login_required


@login_required(redirect_field_name="my_redirect_field")
def my_view(request):
    ...

Обратите внимание, что если вы предоставили значение параметру redirect_field_name, вам, скорее всего, потребуется также настроить свою шаблонную страницу входа в систему, так как переменная контекста шаблона, хранящая путь перенаправления, будет использовать значение redirect_field_name в качестве ключа вместо "next" (значение по умолчанию).

login_required() также принимает необязательный параметр login_url. Пример:

from django.contrib.auth.decorators import login_required


@login_required(login_url="/accounts/login/")
def my_view(request):
    ...

Обратите внимание, что если вы не укажете параметр login_url, вам необходимо убедиться, что settings.LOGIN_URL и ваше представление для входа в систему правильно связаны. Например, используя значения по умолчанию, добавьте следующие строки в ваш файл URLconf:

from django.contrib.auth import views as auth_views

path("accounts/login/", auth_views.LoginView.as_view()),

settings.LOGIN_URL также принимает имена функций представлений и имена URL-шаблонов. Это позволяет свободно переназначить представление входа в систему в вашем файле URLconf, не обновляя настройку.

Миксин LoginRequiredMixin

При использовании представлений на основе классов, вы можете достичь того же результата, что и с декоратором login_required, используя миксин LoginRequiredMixin. Этот миксин должен стоять в самом левом положении в списке наследования.

class LoginRequiredMixin

Если представление использует этот миксин, все запросы от неавторизованных пользователей будут перенаправлены на страницу входа или отобразят ошибку HTTP 403 Forbidden, в зависимости от параметра raise_exception.

Вы можете установить любые параметры AccessMixin, чтобы настроить обработку неавторизованных пользователей:

from django.contrib.auth.mixins import LoginRequiredMixin


class MyView(LoginRequiredMixin, View):
    login_url = "/login/"
    redirect_field_name = "redirect_to"

Ограничение доступа для авторизованных пользователей, прошедших тест

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

Вы можете выполнить свой тест с помощью request.user непосредственно в представлении. Например, это представление проверяет, имеет ли пользователь адрес электронной почты в нужном домене, а если нет, то перенаправляет на страницу входа:

from django.shortcuts import redirect


def my_view(request):
    if not request.user.email.endswith("@example.com"):
        return redirect("/login/?next=%s" % request.path)
    # ...

user_passes_test(test_func, login_url=None, redirect_field_name='next')

В качестве удобного варианта вы можете использовать декоратор user_passes_test, который выполняет перенаправление, когда вызываемая функция возвращает False:

from django.contrib.auth.decorators import user_passes_test


def email_check(user):
    return user.email.endswith("@example.com")


@user_passes_test(email_check)
def my_view(request):
    ...

user_passes_test() принимает обязательный аргумент: вызываемую функцию, которая принимает объект User и возвращает True, если пользователю разрешено просматривать страницу. Обратите внимание, что user_passes_test() не проверяет автоматически, что объект User не является анонимным.

user_passes_test() принимает два необязательных аргумента:

login_url

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

redirect_field_name

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

Например:

@user_passes_test(email_check, login_url="/login/")
def my_view(request):
    ...

class UserPassesTestMixin

При использовании представлений на основе классов, вы можете использовать UserPassesTestMixin, чтобы сделать это.

test_func()

Вам нужно переопределить метод test_func() класса, чтобы предоставить тест, который будет выполняться. Кроме того, вы можете установить любые параметры AccessMixin, чтобы настроить обработку неавторизованных пользователей:

from django.contrib.auth.mixins import UserPassesTestMixin


class MyView(UserPassesTestMixin, View):
    def test_func(self):
        return self.request.user.email.endswith("@example.com")

get_test_func()

Вы также можете переопределить метод get_test_func(), чтобы миксин использовал функцию с другим именем для проверок (вместо test_func()).

Упорядочивание UserPassesTestMixin

Из-за того, как реализован UserPassesTestMixin, вы не можете их объединять в вашем списке наследования. Следующее НЕ работает:

class TestMixin1(UserPassesTestMixin):
    def test_func(self):
        return self.request.user.email.endswith("@example.com")


class TestMixin2(UserPassesTestMixin):
    def test_func(self):
        return self.request.user.username.startswith("django")


class MyView(TestMixin1, TestMixin2, View):
    ...

Если TestMixin1 вызывало бы super() и принимало бы результат во внимание, TestMixin1 больше не работало бы автономно.

Декоратор permission_required

permission_required(perm, login_url=None, raise_exception=False)

Это относительно распространённая задача — проверить, обладает ли пользователь определённым разрешением. По этой причине Django предоставляет для этого ярлык: декоратор permission_required():

from django.contrib.auth.decorators import permission_required


@permission_required("polls.add_choice")
def my_view(request):
    ...

Как и метод has_perm(), имена разрешений имеют вид "<app label>.<permission codename>" (например, polls.add_choice для разрешения на модель в приложении polls).

Декоратор также может принимать итерируемый объект разрешений, в этом случае пользователь должен обладать всеми разрешениями для доступа к представлению.

Обратите внимание, что permission_required() также принимает необязательный параметр login_url:

from django.contrib.auth.decorators import permission_required


@permission_required("polls.add_choice", login_url="/loginpage/")
def my_view(request):
    ...

Как и в декораторе login_required(), параметр login_url по умолчанию равен settings.LOGIN_URL.

Если параметр raise_exception задан, декоратор вызовет исключение PermissionDenied, вызывая представление 403 (HTTP Запрещено) вместо перенаправления на страницу входа в систему.

Если вы хотите использовать raise_exception, но также дать пользователям возможность сначала войти в систему, вы можете добавить декоратор login_required():

from django.contrib.auth.decorators import login_required, permission_required


@login_required
@permission_required("polls.add_choice", raise_exception=True)
def my_view(request):
    ...

Это также предотвращает цикл перенаправления, когда метод LoginView’s redirect_authenticated_user=True и авторизованный пользователь не имеет всех необходимых разрешений.

Миксин PermissionRequiredMixin

Для применения проверок разрешений к представлениям на основе классов можно использовать PermissionRequiredMixin:

class PermissionRequiredMixin

Этот миксин, как и декоратор permission_required, проверяет, обладает ли пользователь, обращающийся к представлению, всеми заданными разрешениями. Вы должны указать разрешение (или итерируемый объект разрешений) с помощью параметра permission_required:

from django.contrib.auth.mixins import PermissionRequiredMixin


class MyView(PermissionRequiredMixin, View):
    permission_required = "polls.add_choice"
    # Or multiple of permissions:
    permission_required = ["polls.view_choice", "polls.change_choice"]

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

Вы также можете переопределить эти методы:

get_permission_required()

Возвращает итерируемый объект имён разрешений, используемых миксином. По умолчанию он равен атрибуту permission_required, преобразованному в кортеж, если необходимо.

has_permission()

Возвращает логическое значение, указывающее, имеет ли текущий пользователь разрешение на выполнение декорированного представления. По умолчанию это возвращает результат вызова has_perms() со списком разрешений, возвращаемым методом get_permission_required().

Перенаправление несанкционированных запросов в представлениях на основе классов

Для упрощения обработки ограничений доступа в представлениях на основе классов можно использовать AccessMixin для настройки поведения представления при отказе в доступе. Авторизованным пользователям отказывается в доступе с ответом HTTP 403 Запрещено. Анонимные пользователи перенаправляются на страницу входа в систему или получают ответ HTTP 403 Запрещено, в зависимости от атрибута raise_exception.

class AccessMixin

login_url

Значение по умолчанию для get_login_url(). По умолчанию равно None, в этом случае get_login_url() обращается к settings.LOGIN_URL.

permission_denied_message

Значение по умолчанию для get_permission_denied_message(). По умолчанию — пустая строка.

redirect_field_name

Значение по умолчанию для get_redirect_field_name(). По умолчанию равно "next".

raise_exception

Если этот атрибут установлен в True, возникает исключение PermissionDenied, когда условия не выполнены. При значении False (по умолчанию) анонимные пользователи перенаправляются на страницу входа в систему.

get_login_url()

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

get_permission_denied_message()

Когда raise_exception равно True, этот метод можно использовать для управления сообщением об ошибке, передаваемым обработчику ошибок для отображения пользователю. По умолчанию возвращает атрибут permission_denied_message.

get_redirect_field_name()

Возвращает имя параметра запроса, который будет содержать URL, на который пользователь должен быть перенаправлен после успешного входа в систему. Если вы установите это значение в None, параметр запроса не будет добавлен. По умолчанию возвращает атрибут redirect_field_name.

handle_no_permission()

В зависимости от значения raise_exception, метод либо вызывает исключение PermissionDenied, либо перенаправляет пользователя на login_url, при необходимости включая redirect_field_name.

Невалидация сессии при смене пароля

Если ваш AUTH_USER_MODEL наследуется от AbstractBaseUser или реализует собственный метод get_session_auth_hash(), аутентифицированные сессии будут содержать хеш, возвращаемый этой функцией. В случае с AbstractBaseUser, это HMAC поля пароля. Django проверяет, что хеш в сессии для каждого запроса соответствует хешу, вычисленному во время запроса. Это позволяет пользователю выйти из всех своих сессий, изменив пароль.

Встроенные представления для смены пароля в Django, PasswordChangeView и представление user_change_password в админке django.contrib.auth обновляют сессию с новым хэшем пароля, чтобы пользователь, меняющий свой пароль, не выходил из системы. Если у вас есть пользовательское представление для смены пароля и вы хотите получить подобное поведение, используйте функцию update_session_auth_hash().

update_session_auth_hash(request, user)

Эта функция принимает текущий запрос и обновлённый объект пользователя, от которого будет получен новый хэш сессии, и соответствующим образом обновляет хэш сессии. Она также вращает ключ сессии, чтобы украденный куки сессии стал недействительным.

Пример использования:

from django.contrib.auth import update_session_auth_hash


def password_change(request):
    if request.method == "POST":
        form = PasswordChangeForm(user=request.user, data=request.POST)
        if form.is_valid():
            form.save()
            update_session_auth_hash(request, form.user)
    else:
        ...

Представления аутентификации

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

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

Использование представлений

Существует несколько способов реализации этих представлений в вашем проекте. Самый простой способ — включить предоставленный URLconf в django.contrib.auth.urls в вашем собственном URLconf, например:

urlpatterns = [
    path("accounts/", include("django.contrib.auth.urls")),
]

Это добавит следующие шаблоны URL:

accounts/login/ [name='login']
accounts/logout/ [name='logout']
accounts/password_change/ [name='password_change']
accounts/password_change/done/ [name='password_change_done']
accounts/password_reset/ [name='password_reset']
accounts/password_reset/done/ [name='password_reset_done']
accounts/reset/<uidb64>/<token>/ [name='password_reset_confirm']
accounts/reset/done/ [name='password_reset_complete']

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

Если вы хотите больше контроля над своими URL, вы можете обратиться к конкретному представлению в вашем URLconf:

from django.contrib.auth import views as auth_views

urlpatterns = [
    path("change-password/", auth_views.PasswordChangeView.as_view()),
]

Представления имеют необязательные аргументы, которые можно использовать для изменения поведения представления. Например, если вы хотите изменить имя шаблона, используемого представлением, вы можете указать аргумент template_name. Способ сделать это — предоставить ключевые аргументы в URLconf, эти аргументы будут переданы представлению. Например:

urlpatterns = [
    path(
        "change-password/",
        auth_views.PasswordChangeView.as_view(template_name="change-password.html"),
    ),
]

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

Все представления аутентификации

Это список всех представлений, которые предоставляет django.contrib.auth. Подробности реализации см. в Использование представлений.

class LoginView

Имя URL: login

Подробности использования именованных шаблонов URL см. в документации URL.

Методы и атрибуты

template_name

Имя шаблона для отображения представления, используемого для входа пользователя. По умолчанию registration/login.html.

next_page

URL для перенаправления после входа. По умолчанию LOGIN_REDIRECT_URL.

redirect_field_name

Имя поля GET, содержащего URL для перенаправления после входа. По умолчанию next. Переопределяет URL get_default_redirect_url(), если передан параметр GET.

authentication_form

Вызываемый объект (обычно класс формы) для аутентификации. По умолчанию AuthenticationForm.

extra_context

Словарь данных контекста, который будет добавлен к стандартным данным контекста, переданным в шаблон.

redirect_authenticated_user

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

Предупреждение

Если вы включите redirect_authenticated_user, другие веб-сайты смогут определить, авторизованы ли их посетители на вашем сайте, запросив URL-адреса перенаправления к файлам изображений на вашем сайте. Чтобы избежать утечки информации о «социальном отпечатке», разместите все изображения и значок вашего сайта на отдельном домене.

Включение redirect_authenticated_user также может привести к циклу перенаправления при использовании декоратора permission_required(), если не используется параметр raise_exception.

success_url_allowed_hosts

set хостов, помимо request.get_host(), которые безопасны для перенаправления после входа. По умолчанию пустой set.

get_default_redirect_url()

Возвращает URL для перенаправления после входа. Реализация по умолчанию разрешает и возвращает next_page, если задано, или LOGIN_REDIRECT_URL в противном случае.

Вот что делает LoginView:

• Если вызывается через GET, отображается форма входа, которая отправляет POST-запрос на тот же URL. Подробнее об этом чуть позже.
• Если вызывается через POST с предоставленными пользователем учетными данными, происходит попытка входа в систему. Если вход успешен, представление перенаправляет на URL, указанный в next. Если next не указан, происходит перенаправление на settings.LOGIN_REDIRECT_URL (по умолчанию /accounts/profile/). Если вход не удался, отображается форма входа.

Вы должны предоставить html для шаблона входа, который по умолчанию называется registration/login.html. Этот шаблон получает четыре переменные контекста шаблона:

• form: объект Form, представляющий собой AuthenticationForm.
• next: URL для перенаправления после успешного входа. Он также может содержать строку запроса.
• site: текущий Site в соответствии с настройкой SITE_ID. Если фреймворк сайта не установлен, он будет настроен на экземпляр RequestSite, который получает имя сайта и домен из текущего HttpRequest.
• site_name: псевдоним для site.name. Если фреймворк сайта не установлен, он будет настроен на значение request.META['SERVER_NAME']. Дополнительные сведения о сайтах см. в рамке «сайты».

Если вы предпочитаете не вызывать шаблон registration/login.html, вы можете передать параметр template_name через дополнительные аргументы к методу as_view в вашем URLconf. Например, эта строка URLconf будет использовать myapp/login.html вместо:

path("accounts/login/", auth_views.LoginView.as_view(template_name="myapp/login.html")),

Также можно указать имя поля GET которое содержит URL для перенаправления после входа с помощью redirect_field_name. По умолчанию поле называется next.

Вот пример шаблона registration/login.html, который вы можете использовать в качестве отправной точки. Предполагается, что у вас есть шаблон base.html, который определяет блок content:

{% extends "base.html" %}

{% block content %}

{% if form.errors %}
<p>Your username and password didn't match. Please try again.</p>
{% endif %}

{% if next %}
    {% if user.is_authenticated %}
    <p>Your account doesn't have access to this page. To proceed,
    please login with an account that has access.</p>
    {% else %}
    <p>Please login to see this page.</p>
    {% endif %}
{% endif %}

<form method="post" action="{% url 'login' %}">
{% csrf_token %}
<table>
<tr>
    <td>{{ form.username.label_tag }}</td>
    <td>{{ form.username }}</td>
</tr>
<tr>
    <td>{{ form.password.label_tag }}</td>
    <td>{{ form.password }}</td>
</tr>
</table>

<input type="submit" value="login">
<input type="hidden" name="next" value="{{ next }}">
</form>

{# Assumes you set up the password_reset view in your URLconf #}
<p><a href="{% url 'password_reset' %}">Lost password?</a></p>

{% endblock %}

Если вы настроили аутентификацию (см. Настройка аутентификации), вы можете использовать пользовательскую форму аутентификации, установив атрибут authentication_form. Эта форма должна принимать ключевой аргумент request в своем методе __init__() и предоставлять метод get_user(), который возвращает объект аутентифицированного пользователя (этот метод вызывается только после успешной проверки формы).

class LogoutView

Выводит пользователя из системы по POST запросам.

Устаревшая с версии 4.1: Поддержка выхода из системы по GET запросам устарела и будет удалена в Django 5.0.

Имя URL: logout

Атрибуты:

next_page

URL для перенаправления после выхода. По умолчанию LOGOUT_REDIRECT_URL.

template_name

Полное имя шаблона для отображения после выхода пользователя. По умолчанию registration/logged_out.html.

redirect_field_name

Имя поля GET содержащего URL для перенаправления после выхода. По умолчанию 'next'. Переопределяет URL next_page, если передан параметр GET.

extra_context

Словарь данных контекста, которые будут добавлены к стандартным данным контекста, передаваемым шаблону.

success_url_allowed_hosts

set хостов, помимо request.get_host(), которые безопасны для перенаправления после выхода. По умолчанию пустой set.

Контекст шаблона:

• title: Строка “Выход выполнен”, локализованная.
• site: Текущий Site в соответствии с настройкой SITE_ID. Если фреймворк сайтов не установлен, будет установлена инстанция RequestSite, которая получает имя сайта и домен из текущего HttpRequest.
• site_name: Псевдоним для site.name. Если фреймворк сайтов не установлен, будет установлено значение request.META['SERVER_NAME']. Для получения дополнительной информации о сайтах, см. Фреймворк «сайты».

logout_then_login(request, login_url=None)

Выводит пользователя из системы по POST запросам, затем перенаправляет на страницу входа.

Имя URL: Не предоставлено значение по умолчанию

Дополнительные аргументы:

• login_url: URL страницы входа для перенаправления. По умолчанию settings.LOGIN_URL, если не указано.

Устаревшая с версии 4.1: Поддержка выхода из системы по GET запросам устарела и будет удалена в Django 5.0.

class PasswordChangeView

Имя URL: password_change

Разрешает пользователю изменить свой пароль.

Атрибуты:

template_name

Полное имя шаблона для отображения формы изменения пароля. По умолчанию registration/password_change_form.html если не указано.

success_url

URL для перенаправления после успешного изменения пароля. По умолчанию 'password_change_done'.

form_class

Пользовательская форма «изменение пароля», которая должна принимать параметр user. Форма отвечает за фактическое изменение пароля пользователя. По умолчанию PasswordChangeForm.

extra_context

Словарь данных контекста, которые будут добавлены к стандартным данным контекста, передаваемым шаблону.

Контекст шаблона:

• form: Форма изменения пароля (см. form_class выше).

class PasswordChangeDoneView

Имя URL: password_change_done

Страница, отображаемая после изменения пользователем пароля.

Атрибуты:

template_name

Полное имя шаблона для использования. По умолчанию registration/password_change_done.html если не указано.

extra_context

Словарь данных контекста, которые будут добавлены к стандартным данным контекста, передаваемым шаблону.

class PasswordResetView

Имя URL: password_reset

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

Этот виджет отправит электронное письмо, если выполнены следующие условия:

• Адрес электронной почты, предоставленный пользователем, существует в системе.
• Запрашиваемый пользователь активен (User.is_active является True).
• У запрашиваемого пользователя есть используемый пароль. Пользователи с помеченным неиспользуемым паролем (см. set_unusable_password()) не могут запросить сброс пароля, чтобы предотвратить злоупотребление при использовании внешнего источника аутентификации, например, LDAP.

Если какое-либо из этих условий не выполняется, электронное письмо не будет отправлено, но пользователь также не получит никаких сообщений об ошибках. Это предотвращает утечку информации потенциальным злоумышленникам. Если вы хотите вывести сообщение об ошибке в этом случае, вы можете создать подкласс PasswordResetForm и использовать атрибут form_class.

Примечание

Обратите внимание, что отправка электронного письма занимает дополнительное время, поэтому вы можете быть уязвимы к атакам на перечисление адресов электронной почты из-за разницы во времени между запросом на сброс для существующего адреса электронной почты и запросом на сброс для несуществующего адреса электронной почты. Чтобы уменьшить нагрузку, вы можете использовать сторонний пакет, который позволяет отправлять электронные письма асинхронно, например, django-mailer.

Атрибуты:

template_name

Полное имя шаблона для отображения формы сброса пароля. По умолчанию значение registration/password_reset_form.html если не указано.

form_class

Форма, которая будет использоваться для получения адреса электронной почты пользователя для сброса пароля. По умолчанию PasswordResetForm.

email_template_name

Полное имя шаблона для создания электронного письма со ссылкой на сброс пароля. По умолчанию registration/password_reset_email.html если не указано.

subject_template_name

Полное имя шаблона для темы электронного письма со ссылкой на сброс пароля. По умолчанию registration/password_reset_subject.txt если не указано.

token_generator

Экземпляр класса для проверки одноразовой ссылки. По умолчанию default_token_generator, это экземпляр django.contrib.auth.tokens.PasswordResetTokenGenerator.

success_url

URL для перенаправления после успешного запроса на сброс пароля. По умолчанию 'password_reset_done'.

from_email

Действительный адрес электронной почты. По умолчанию Django использует DEFAULT_FROM_EMAIL.

extra_context

Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым в шаблон.

html_email_template_name

Полное имя шаблона для создания text/html многочастного электронного письма со ссылкой на сброс пароля. По умолчанию HTML-электронное письмо не отправляется.

extra_email_context

Словарь данных контекста, которые будут доступны в шаблоне электронного письма. Он может быть использован для перезаписи стандартных значений контекста шаблона, например domain.

Контекст шаблона:

• form: Форма (см. form_class выше) для сброса пароля пользователя.

Контекст шаблона электронного письма:

• email: Псевдоним для user.email
• user: Текущий User, согласно полю формы email. Только активные пользователи могут сбросить свои пароли (User.is_active is True).
• site_name: Псевдоним для site.name. Если у вас не установлен фреймворк сайтов, это будет значение request.META['SERVER_NAME']. Для получения дополнительной информации о сайтах см. Фреймворк «сайты».
• domain: Псевдоним для site.domain. Если у вас не установлен фреймворк сайтов, это будет значение request.get_host().
• protocol: http или https
• uid: Первичный ключ пользователя, закодированный в base 64.
• token: Токен для проверки валидности ссылки на сброс пароля.

Пример registration/password_reset_email.html (шаблон тела электронного письма):

Someone asked for password reset for email {{ email }}. Follow the link below:
{{ protocol}}://{{ domain }}{% url 'password_reset_confirm' uidb64=uid token=token %}

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

class PasswordResetDoneView

Имя URL: password_reset_done

Страница, отображаемая после того, как пользователю было отправлено электронное письмо со ссылкой на сброс пароля. Этот виджет вызывается по умолчанию, если у PasswordResetView нет явно заданного URL-адреса success_url.

Примечание

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

Атрибуты:

template_name

Полное имя шаблона. По умолчанию registration/password_reset_done.html если не указано.

extra_context

Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым в шаблон.

class PasswordResetConfirmView

Имя URL: password_reset_confirm

Отображает форму для ввода нового пароля.

Ключевые аргументы из URL:

• uidb64: Идентификатор пользователя, закодированный в base 64.
• token: Токен для проверки валидности пароля.

Атрибуты:

template_name

Полное имя шаблона для отображения представления подтверждения пароля. Значение по умолчанию registration/password_reset_confirm.html.

token_generator

Экземпляр класса для проверки пароля. По умолчанию default_token_generator, это экземпляр django.contrib.auth.tokens.PasswordResetTokenGenerator.

post_reset_login

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

post_reset_login_backend

Путь с точками до используемого бэкенда аутентификации при аутентификации пользователя, если post_reset_login равно True. Требуется только если у вас настроено несколько AUTHENTICATION_BACKENDS. По умолчанию None.

form_class

Форма, которая будет использоваться для установки пароля. По умолчанию SetPasswordForm.

success_url

URL для перенаправления после сброса пароля. По умолчанию 'password_reset_complete'.

extra_context

Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым в шаблон.

reset_url_token

Параметр токена, отображаемый как часть URL-адресов сброса пароля. По умолчанию 'set-password'.

Контекст шаблона:

• form: Форма (см. form_class выше) для установки нового пароля пользователя.
• validlink: Булево значение, True, если ссылка (комбинация uidb64 и token) действительна или еще не использовалась.

class PasswordResetCompleteView

Имя URL: password_reset_complete

Отображает представление, информирующее пользователя о том, что пароль успешно изменён.

Атрибуты:

template_name

Полное имя шаблона для отображения представления. По умолчанию registration/password_reset_complete.html.

extra_context

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

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

redirect_to_login(next, login_url=None, redirect_field_name='next')

Перенаправляет на страницу входа в систему, а затем обратно на другую URL после успешного входа в систему.

Обязательные аргументы:

• next: URL для перенаправления после успешного входа в систему.

Необязательные аргументы:

• login_url: URL страницы входа в систему для перенаправления. По умолчанию settings.LOGIN_URL, если не указано.
• redirect_field_name: Имя поля GET, содержащего URL для перенаправления после выхода. Переопределяет next, если задан аргумент GET.

Встроенные формы

Если вы не хотите использовать встроенные представления, но хотите воспользоваться удобством, не написав формы для этой функциональности, система аутентификации предоставляет несколько встроенных форм, расположенных в django.contrib.auth.forms:

class AdminPasswordChangeForm

Форма, используемая в интерфейсе администрирования для изменения пароля пользователя.

Принимает user в качестве первого позиционного аргумента.

class AuthenticationForm

Форма для входа пользователя.

Принимает request в качестве первого позиционного аргумента, который хранится в экземпляре формы для использования подклассами.

confirm_login_allowed(user)

По умолчанию, AuthenticationForm отклоняет пользователей, у которых флаг is_active установлен в значение False. Вы можете переопределить это поведение с помощью пользовательской политики, определяющей, какие пользователи могут войти в систему. Сделайте это с помощью пользовательской формы, которая наследуется от AuthenticationForm и переопределяет метод confirm_login_allowed(). Этот метод должен вызывать ValidationError, если данный пользователь не может войти в систему.

Например, чтобы разрешить вход всем пользователям независимо от статуса «активный»:

from django.contrib.auth.forms import AuthenticationForm


class AuthenticationFormWithInactiveUsersOkay(AuthenticationForm):
    def confirm_login_allowed(self, user):
        pass

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

Или чтобы разрешить вход только некоторым активным пользователям:

class PickyAuthenticationForm(AuthenticationForm):
    def confirm_login_allowed(self, user):
        if not user.is_active:
            raise ValidationError(
                _("This account is inactive."),
                code="inactive",
            )
        if user.username.startswith("b"):
            raise ValidationError(
                _("Sorry, accounts starting with 'b' aren't welcome here."),
                code="no_b_users",
            )

class PasswordChangeForm

Форма, позволяющая пользователю изменить свой пароль.

class PasswordResetForm

Форма для генерации и отправки по электронной почте одноразовой ссылки для сброса пароля пользователя.

send_mail(subject_template_name, email_template_name, context, from_email, to_email, html_email_template_name=None)

Использует аргументы для отправки EmailMultiAlternatives. Можно переопределить, чтобы настроить способ отправки электронной почты пользователю.

Параметры:

subject_template_name – шаблон для темы. email_template_name – шаблон для тела электронной почты. context – контекст, передаваемый в subject_template, email_template, и html_email_template (если он не None). from_email – электронная почта отправителя. to_email – электронная почта запрашивающего. html_email_template_name – шаблон для HTML-тела; по умолчанию None, в этом случае отправляется обычное текстовое письмо.

По умолчанию, save() заполняет context теми же переменными, что PasswordResetView передает в свой контекст электронной почты.

class SetPasswordForm

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

class UserChangeForm

Форма, используемая в интерфейсе администрирования для изменения информации и разрешений пользователя.

class BaseUserCreationForm

Новое в Django 4.2.

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

Он имеет три поля: username (из модели пользователя), password1, и password2. Он проверяет, что password1 и password2 совпадают, проверяет пароль с помощью validate_password() и устанавливает пароль пользователя с помощью set_password().

class UserCreationForm

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

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

В более старых версиях UserCreationForm не сохраняла поля формы many-to-many для пользовательской модели.

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

Данные аутентификации в шаблонах

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

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

При рендеринге шаблона RequestContext, текущий вошедший в систему пользователь, либо экземпляр User, либо экземпляр AnonymousUser, хранится в переменной шаблона {{ user }}:

{% if user.is_authenticated %}
    <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
{% else %}
    <p>Welcome, new user. Please log in.</p>
{% endif %}

Эта переменная контекста шаблона недоступна, если используется RequestContext.

Разрешения

Разрешения текущего вошедшего в систему пользователя хранятся в переменной шаблона {{ perms }}. Это экземпляр django.contrib.auth.context_processors.PermWrapper, который представляет собой удобную для шаблонов оболочку разрешений.

Вычисление одноуровневого поиска {{ perms }} как булевого значения является заменой для User.has_module_perms(). Например, чтобы проверить, имеет ли вошедший в систему пользователь какие-либо разрешения в приложении foo:

{% if perms.foo %}

Вычисление двухуровневого поиска как булевого значения является заменой для User.has_perm(). Например, чтобы проверить, имеет ли вошедший в систему пользователь разрешение foo.add_vote:

{% if perms.foo.add_vote %}

Вот более полный пример проверки разрешений в шаблоне:

{% if perms.foo %}
    <p>You have permission to do something in the foo app.</p>
    {% if perms.foo.add_vote %}
        <p>You can vote!</p>
    {% endif %}
    {% if perms.foo.add_driving %}
        <p>You can drive!</p>
    {% endif %}
{% else %}
    <p>You don't have permission to do anything in the foo app.</p>
{% endif %}

Также можно искать разрешения по {% if in %} операторам. Например:

{% if 'foo' in perms %}
    {% if 'foo.add_vote' in perms %}
        <p>In lookup works, too.</p>
    {% endif %}
{% endif %}

Управление пользователями в админке

Когда у вас установлены как django.contrib.admin , так и django.contrib.auth , админка предоставляет удобный способ просмотра и управления пользователями, группами и разрешениями. Пользователей можно создавать и удалять как любые модели Django. Группы можно создавать, а разрешения можно назначать пользователям или группам. Также хранится и отображается журнал изменений, внесенных пользователями в модели в админке.

Создание пользователей

Вы должны увидеть ссылку на «Пользователи» в разделе «Auth» на главной странице админки. Страница админки «Добавить пользователя» отличается от стандартных страниц админки тем, что требует выбора имени пользователя и пароля перед редактированием остальных полей пользователя.

Обратите также внимание: если вы хотите, чтобы учётная запись пользователя могла создавать пользователей через сайт Django admin, вам нужно предоставить им разрешение на добавление пользователей и изменение пользователей (т.е. разрешения «Добавить пользователя» и «Изменить пользователя»). Если у учётной записи есть разрешение на добавление пользователей, но нет разрешения на изменение, эта учётная запись не сможет добавлять пользователей. Почему? Потому что если у вас есть разрешение на добавление пользователей, у вас есть возможность создавать суперпользователей, которые, в свою очередь, могут изменять других пользователей. Поэтому Django требует разрешений на добавление и изменение как меры безопасности.

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

Изменение паролей

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