Использование системы аутентификации 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 admin, вы также можете создавать пользователей интерактивно.

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

Создайте суперпользователей, используя команду createsuperuser:

$ python 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 admin, вы также можете изменить пароли пользователей на страницах администрирования системы аутентификации системы аутентификации.

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

Изменение пароля пользователя выведет всех его сеансы, если включён SessionAuthenticationMiddleware. См. Недействительность сеанса при изменении пароля для получения подробностей.

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

authenticate(**credentials) [source]

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

from django.contrib.auth import authenticate
user = authenticate(username='john', password='secret')
if user is not None:
    # the password verified for the user
    if user.is_active:
        print("User is valid, active and authenticated")
    else:
        print("The password is valid, but the account has been disabled!")
else:
    # the authentication system was unable to verify the username and password
    print("The username and password were incorrect.")

Примечание

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

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

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

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

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

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

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

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

myuser.groups = [group_list]
myuser.groups.add(group, group, ...)
myuser.groups.remove(group, group, ...)
myuser.groups.clear()
myuser.user_permissions = [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')

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

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

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

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

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

    permission = Permission.objects.get(codename='change_bar')
    user.user_permissions.add(permission)

    # Checking the cached permission set
    user.has_perm('myapp.change_bar')  # 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_bar')  # 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) [source]

Для входа пользователя из представления используйте 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(username=username, password=password)
    if user is not None:
        if user.is_active:
            login(request, user)
            # Redirect to a success page.
        else:
            # Return a 'disabled account' error message
            ...
    else:
        # Return an 'invalid login' error message.
        ...

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

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

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

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

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

logout(request) [source]

Чтобы выйти из системы пользователю, вошедшему через 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('%s?next=%s' % (settings.LOGIN_URL, 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) [source]

В качестве альтернативы можно использовать удобный декоратор 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

url(r'^accounts/login/$', auth_views.login),

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

Миксин LoginRequired

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

class LoginRequiredMixin

Если представление использует этот миксин, все запросы от неавторизованных пользователей будут перенаправлены на страницу входа или показано сообщение об ошибке HTTP 403 «Запрещено», в зависимости от параметра 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') [source]

В качестве альтернативы можно использовать удобный декоратор 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) [source]

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

from django.contrib.auth.decorators import permission_required

@permission_required('polls.can_vote')
def my_view(request):
    ...

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

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

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

from django.contrib.auth.decorators import permission_required

@permission_required('polls.can_vote', login_url='/loginpage/')
def my_view(request):
    ...

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

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

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

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

@login_required
@permission_required('polls.can_vote', raise_exception=True)
def my_view(request):
    ...

В более старых версиях параметр permission работал только со строками, списками и кортежами вместо строк и любого итерируемого объекта.

Миксин PermissionRequiredMixin

Чтобы применить проверки разрешений к классно-ориентированным представлениям, вы можете использовать PermissionRequiredMixin:

class PermissionRequiredMixin

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

from django.contrib.auth.mixins import PermissionRequiredMixin

class MyView(PermissionRequiredMixin, View):
    permission_required = 'polls.can_vote'
    # Or multiple of permissions:
    permission_required = ('polls.can_open', 'polls.can_edit')

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

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

get_permission_required()

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

has_permission()

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

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

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

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 поля пароля. Если SessionAuthenticationMiddleware включена, Django проверяет, что хеш, переданный вместе с каждым запросом, соответствует хешу, вычисленному на стороне сервера. Это позволяет пользователю выйти из всех своих сеансов, изменив пароль.

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

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:
        ...

Если вы обновляете существующий сайт и хотите включить этот middleware без необходимости повторного входа в систему всем пользователям, сначала обновите Django до версии 1.7 и запустите его некоторое время, чтобы при естественном пересоздании сеансов по мере входа пользователей они включали хеш сеанса, как описано выше. После запуска сайта с SessionAuthenticationMiddleware, сеансы тех пользователей, которые не вошли в систему и не обновили свой сеанс с помощью хеша проверки, будут аннулированы, и им потребуется войти заново.

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

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

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

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

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

urlpatterns = [
    url('^', include('django.contrib.auth.urls')),
]

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

^login/$ [name='login']
^logout/$ [name='logout']
^password_change/$ [name='password_change']
^password_change/done/$ [name='password_change_done']
^password_reset/$ [name='password_reset']
^password_reset/done/$ [name='password_reset_done']
^reset/(?P<uidb64>[0-9A-Za-z_\-]+)/(?P<token>[0-9A-Za-z]{1,13}-[0-9A-Za-z]{1,20})/$ [name='password_reset_confirm']
^reset/done/$ [name='password_reset_complete']

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

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

from django.contrib.auth import views as auth_views

urlpatterns = [
    url('^change-password/$', auth_views.password_change),
]

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

urlpatterns = [
    url(
        '^change-password/$',
        auth_views.password_change,
        {'template_name': 'change-password.html'}
    ),
]

Все представления возвращают экземпляр TemplateResponse, что позволяет легко настроить данные ответа перед рендерингом. Один из способов сделать это — обернуть представление своим собственным представлением:

from django.contrib.auth import views

def change_password(request):
    template_response = views.password_change(request)
    # Do something with `template_response`
    return template_response

Дополнительную информацию см. в документации по TemplateResponse.

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

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

login(request, template_name=`registration/login.html`, redirect_field_name='next', authentication_form=AuthenticationForm, current_app=None, extra_context=None)

Имя URL: login

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

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

• template_name: Имя шаблона для отображения представления, используемого для входа пользователя. По умолчанию registration/login.html.
• redirect_field_name: Имя поля GET содержащего URL для перенаправления после входа. По умолчанию next.
• authentication_form: Вызываемый объект (обычно просто класс формы) для аутентификации. По умолчанию AuthenticationForm.
• current_app: Подсказка, указывающая, в каком приложении находится текущее представление. См. стратегию разрешения URL с именами пространств для получения дополнительной информации.
• extra_context: Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым шаблону.

Устарело начиная с версии 1.9: Параметр current_app устарел и будет удален в Django 2.0. Вызывающие стороны должны задать request.current_app вместо этого.

Вот что делает django.contrib.auth.views.login:

• Если вызывается через 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 через дополнительные аргументы представления в вашем файле URLconf. Например, эта строка URLconf будет использовать myapp/login.html вместо этого:

url(r'^accounts/login/$', auth_views.login, {'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 setup the password_reset view in your URLconf #}
<p><a href="{% url 'password_reset' %}">Lost password?</a></p>

{% endblock %}

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

logout(request, next_page=None, template_name='registration/logged_out.html', redirect_field_name='next', current_app=None, extra_context=None)

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

Имя URL: logout

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

• next_page: URL для перенаправления после выхода.
• template_name: Полное имя шаблона для отображения после выхода пользователя. По умолчанию registration/logged_out.html если не указано.
• redirect_field_name: Имя поля GET содержащего URL для перенаправления после выхода. По умолчанию next. Переопределяет URL next_page если передан параметр GET.
• current_app: Подсказка, указывающая, в каком приложении находится текущее представление. См. стратегию разрешения URL с именами пространств для получения дополнительной информации.
• extra_context: Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым шаблону.

Устарело начиная с версии 1.9: Параметр current_app устарел и будет удален в Django 2.0. Вызывающие стороны должны задать request.current_app вместо этого.

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

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

logout_then_login(request, login_url=None, current_app=None, extra_context=None)

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

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

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

• login_url: URL страницы входа для перенаправления. По умолчанию settings.LOGIN_URL если не указано.
• current_app: Подсказка, указывающая, в каком приложении находится текущее представление. См. стратегию разрешения URL с именами пространств для получения дополнительной информации.
• extra_context: Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым шаблону.

Устарело начиная с версии 1.9: Параметр current_app устарел и будет удален в Django 2.0. Вызывающие стороны должны задать request.current_app вместо этого.

password_change(request, template_name='registration/password_change_form.html', post_change_redirect=None, password_change_form=PasswordChangeForm, current_app=None, extra_context=None)

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

Имя URL: password_change

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

• template_name: Полное имя шаблона для отображения формы смены пароля. По умолчанию registration/password_change_form.html если не указано.
• post_change_redirect: URL для перенаправления после успешной смены пароля.
• password_change_form: Пользовательская форма «смены пароля», которая должна принимать ключевой аргумент user. Форма отвечает за фактическое изменение пароля пользователя. По умолчанию PasswordChangeForm.
• current_app: Подсказка, указывающая, в каком приложении находится текущее представление. См. стратегию разрешения URL с именами пространств для получения дополнительной информации.
• extra_context: Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым шаблону.

Устарело начиная с версии 1.9: Параметр current_app устарел и будет удален в Django 2.0. Вызывающие стороны должны задать request.current_app вместо этого.

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

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

password_change_done(request, template_name='registration/password_change_done.html', current_app=None, extra_context=None)

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

Имя URL: password_change_done

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

• template_name: Полное имя шаблона для использования. По умолчанию registration/password_change_done.html, если не указано.
• current_app: Подсказка, указывающая, в каком приложении находится текущий вид. Для получения дополнительной информации см. стратегию разрешения URL с именованными пространствами имён.
• extra_context: Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым шаблону.

Устаревшая начиная с версии 1.9: Параметр current_app устарел и будет удален в Django 2.0. Звонящие должны установить request.current_app вместо этого.

password_reset(request, is_admin_site=False, template_name='registration/password_reset_form.html', email_template_name='registration/password_reset_email.html', subject_template_name='registration/password_reset_subject.txt', password_reset_form=PasswordResetForm, token_generator=default_token_generator, post_reset_redirect=None, from_email=None, current_app=None, extra_context=None, html_email_template_name=None, extra_email_context=None)

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

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

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

Имя URL: password_reset

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

• template_name: Полное имя шаблона для отображения формы сброса пароля. По умолчанию registration/password_reset_form.html, если не указано.
• email_template_name: Полное имя шаблона для создания письма со ссылкой на сброс пароля. По умолчанию registration/password_reset_email.html, если не указано.
• subject_template_name: Полное имя шаблона для темы письма со ссылкой на сброс пароля. По умолчанию registration/password_reset_subject.txt, если не указано.
• password_reset_form: Форма, которая будет использоваться для получения адреса электронной почты пользователя для сброса пароля. По умолчанию PasswordResetForm.
• token_generator: Экземпляр класса для проверки одноразовой ссылки. По умолчанию default_token_generator, это экземпляр django.contrib.auth.tokens.PasswordResetTokenGenerator.
• post_reset_redirect: URL для перенаправления после успешного запроса сброса пароля.
• from_email: Действительный адрес электронной почты. По умолчанию Django использует DEFAULT_FROM_EMAIL.
• current_app: Подсказка, указывающая, в каком приложении находится текущий вид. Для получения дополнительной информации см. стратегию разрешения URL с именованными пространствами имён.
• extra_context: Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым шаблону.
• html_email_template_name: Полное имя шаблона для создания многокомпонентного письма text/html со ссылкой на сброс пароля. По умолчанию письмо HTML не отправляется.
• extra_email_context: Словарь данных контекста, доступных в шаблоне письма.

Устаревшая начиная с версии 1.8: Аргумент is_admin_site устарел и будет удален в Django 1.10.

Устаревшая начиная с версии 1.9: Параметр current_app устарел и будет удален в Django 2.0. Звонящие должны установить request.current_app вместо этого.

Параметр extra_email_context был добавлен.

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

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

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

• 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 %}

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

password_reset_done(request, template_name='registration/password_reset_done.html', current_app=None, extra_context=None)

Страница, отображаемая после отправки пользователю письма со ссылкой на сброс пароля. Этот вид вызывается по умолчанию, если у вида password_reset() не задан явный URL post_reset_redirect.

Имя URL: password_reset_done

Примечание

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

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

• template_name: Полное имя шаблона для использования. По умолчанию registration/password_reset_done.html, если не указано.
• current_app: Подсказка, указывающая, в каком приложении находится текущий вид. Для получения дополнительной информации см. стратегию разрешения URL с именованными пространствами имён.
• extra_context: Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым шаблону.

Устаревшая начиная с версии 1.9: Параметр current_app устарел и будет удален в Django 2.0. Звонящие должны установить request.current_app вместо этого.

password_reset_confirm(request, uidb64=None, token=None, template_name='registration/password_reset_confirm.html', token_generator=default_token_generator, set_password_form=SetPasswordForm, post_reset_redirect=None, current_app=None, extra_context=None)

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

Имя URL: password_reset_confirm

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

• uidb64: Идентификатор пользователя, закодированный в base 64. По умолчанию None.
• token: Токен для проверки валидности пароля. По умолчанию None.
• template_name: Полное имя шаблона для отображения вида подтверждения пароля. Значение по умолчанию registration/password_reset_confirm.html.
• token_generator: Экземпляр класса для проверки пароля. По умолчанию default_token_generator, это экземпляр django.contrib.auth.tokens.PasswordResetTokenGenerator.
• set_password_form: Форма для установки пароля. По умолчанию SetPasswordForm
• post_reset_redirect: URL для перенаправления после завершения сброса пароля. По умолчанию None.
• current_app: Подсказка, указывающая, в каком приложении находится текущий вид. Для получения дополнительной информации см. стратегию разрешения URL с именованными пространствами имён.
• extra_context: Словарь данных контекста, который будет добавлен к стандартным данным контекста, передаваемым шаблону.

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

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

Устаревшая начиная с версии 1.9: Параметр current_app устарел и будет удален в Django 2.0. Звонящие должны установить request.current_app вместо этого.

password_reset_complete(request, template_name='registration/password_reset_complete.html', current_app=None, extra_context=None)

Представляет представление, которое информирует пользователя о том, что пароль успешно изменен.

Имя URL: password_reset_complete

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

• template_name: Полное имя шаблона для отображения представления. По умолчанию registration/password_reset_complete.html.
• current_app: Подсказка, указывающая, какое приложение содержит текущее представление. Для получения дополнительной информации см. стратегию разрешения URL с именованными пространствами.
• extra_context: Словарь данных контекста, которые будут добавлены к стандартным данным контекста, передаваемым шаблону.

Устарело начиная с версии 1.9: Параметр current_app устарел и будет удален в Django 2.0. Вызывающие стороны должны установить request.current_app вместо него.

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

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

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

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

class PasswordChangeForm

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

class PasswordResetForm

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

send_email(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 теми же переменными, что password_reset() передает в свой контекст электронного письма.

class SetPasswordForm

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

class UserChangeForm

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

class UserCreationForm

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

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

Текущий вошедший в систему пользователь и его разрешения доступны в контексте шаблона, когда вы используете 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. Этот пример отобразит True если вошедший в систему пользователь имеет какие-либо разрешения в приложении foo.

{{ perms.foo }}

Поиск по двухуровневому атрибуту — это псевдоним для User.has_perm. Этот пример отобразит True если вошедший в систему пользователь имеет разрешение foo.can_vote.

{{ perms.foo.can_vote }}

Таким образом, вы можете проверять разрешения в операторах шаблона {% if %}:

{% if perms.foo %}
    <p>You have permission to do something in the foo app.</p>
    {% if perms.foo.can_vote %}
        <p>You can vote!</p>
    {% endif %}
    {% if perms.foo.can_drive %}
        <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.can_vote' in perms %}
        <p>In lookup works, too.</p>
    {% endif %}
{% endif %}

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

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

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

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

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

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

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

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