Как использовать сессии

Django предоставляет полную поддержку анонимных сессий. Фреймворк сессий позволяет хранить и извлекать произвольные данные для каждого посетителя сайта. Он хранит данные на стороне сервера и абстрагирует отправку и получение куки. Куки содержат идентификатор сессии – а не сами данные (если только вы не используете базовый модуль на основе куки).

Включение сессий

Сессии реализованы с помощью части средств промежуточного слоя.

Для включения функциональности сессий выполните следующие действия:

• Отредактируйте настройку MIDDLEWARE и убедитесь, что она содержит 'django.contrib.sessions.middleware.SessionMiddleware'. По умолчанию settings.py созданный django-admin startproject имеет SessionMiddleware включенным.

Если вы не хотите использовать сессии, можете удалить строку SessionMiddleware из MIDDLEWARE и 'django.contrib.sessions' из INSTALLED_APPS. Это сэкономит немного накладных расходов.

Настройка движка сессий

По умолчанию Django хранит сессии в вашей базе данных (используя модель django.contrib.sessions.models.Session). Хотя это удобно, в некоторых настройках хранение данных сессии в другом месте быстрее, поэтому Django можно настроить на хранение данных сессии на файловой системе или в кэше.

Использование сессий, поддерживаемых базой данных

Если вы хотите использовать сессии, поддерживаемые базой данных, вам нужно добавить 'django.contrib.sessions' в настройку INSTALLED_APPS.

После настройки вашей установки запустите manage.py migrate для установки единственной таблицы базы данных, которая хранит данные сессии.

Использование кэшированных сессий

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

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

Если у вас несколько кэшей, определённых в CACHES, Django будет использовать кэш по умолчанию. Чтобы использовать другой кэш, установите SESSION_CACHE_ALIAS на имя этого кэша.

После настройки кэша у вас есть два варианта хранения данных в кэше:

• Установите SESSION_ENGINE на "django.contrib.sessions.backends.cache" для простого хранилища кэшированных сессий. Данные сессии будут храниться непосредственно в вашем кэше. Однако данные сессии могут не сохраняться: кэшированные данные могут быть удалены, если кэш заполнится или если сервер кэша перезапустится.
• Для постоянных, кэшированных данных установите SESSION_ENGINE на "django.contrib.sessions.backends.cached_db". Это использует кэш «проход через запись» — каждая запись в кэш также запишется в базу данных. Чтение сессий использует только базу данных, если данные уже не находятся в кэше.

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

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

Использование сессий на основе файлов

Для использования сессий на основе файлов установите настройку SESSION_ENGINE на "django.contrib.sessions.backends.file".

Вы также можете настроить настройку SESSION_FILE_PATH (которая по умолчанию соответствует выводу из tempfile.gettempdir(), скорее всего /tmp) для управления тем, где Django хранит файлы сессий. Убедитесь, что ваш веб-сервер имеет разрешения на чтение и запись в этом месте.

Использование куки-базовых сессий

Для использования сессий на основе куки установите настройку SESSION_ENGINE на "django.contrib.sessions.backends.signed_cookies". Данные сессий будут храниться с помощью инструментов Django для криптографической подписи и настройки SECRET_KEY.

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

Когда SessionMiddleware активирован, каждый объект HttpRequest – первый аргумент любой функции представления Django – будет иметь атрибут session, который является объектом, похожим на словарь.

Вы можете читать и записывать в request.session в любой момент в своём представлении. Вы можете редактировать его несколько раз.

class backends.base.SessionBase

Это базовый класс для всех объектов сеанса. Он имеет следующие стандартные методы словаря:

__getitem__(key)

Пример: fav_color = request.session['fav_color']

__setitem__(key, value)

Пример: request.session['fav_color'] = 'blue'

__delitem__(key)

Пример: del request.session['fav_color']. Это вызывает KeyError если заданный key уже не находится в сеансе.

__contains__(key)

Пример: 'fav_color' in request.session

get(key, default=None)

Пример: fav_color = request.session.get('fav_color', 'red')

pop(key, default=__not_given)

Пример: fav_color = request.session.pop('fav_color', 'blue')

keys()

items()

setdefault()

clear()

Также у него есть следующие методы:

flush()

Удаляет текущие данные сеанса из сеанса и удаляет cookie сеанса. Это используется, если вы хотите убедиться, что к предыдущим данным сеанса больше нельзя получить доступ из браузера пользователя (например, функция django.contrib.auth.logout() вызывает ее).

set_test_cookie()

Устанавливает тестовый cookie для определения того, поддерживает ли браузер пользователя cookies. Из-за работы cookies вы не сможете проверить это до следующего запроса страницы пользователя. Подробнее см. раздел «Настройка тестовых cookies» ниже.

test_cookie_worked()

Возвращает либо True, либо False, в зависимости от того, принял ли браузер пользователя тестовый cookie. Из-за работы cookies вам нужно будет вызвать set_test_cookie() на предыдущем отдельном запросе страницы. Подробнее см. раздел «Настройка тестовых cookies» ниже.

delete_test_cookie()

Удаляет тестовый cookie. Используйте это, чтобы очистить за собой.

set_expiry(value)

Устанавливает время истечения срока действия сеанса. Вы можете передать различные значения:

• Если value является целым числом, сеанс истечёт через указанное количество секунд бездействия. Например, вызов request.session.set_expiry(300) приведет к истечению сеанса через 5 минут.
• Если value является объектом datetime или timedelta, сеанс истечёт в указанную дату/время. Обратите внимание, что значения datetime и timedelta сериализуемы только при использовании PickleSerializer.
• Если value равно 0, cookie сеанса пользователя истечёт при закрытии веб-браузера пользователя.
• Если value равно None, сеанс вернётся к использованию глобальной политики истечения срока действия сеанса.

Чтение сеанса не считается активностью для целей истечения срока действия. Истечение срока действия сеанса вычисляется на основе последнего времени изменения сеанса.

get_expiry_age()

Возвращает количество секунд до истечения срока действия этого сеанса. Для сеансов без пользовательского срока действия (или тех, которые должны истекать при закрытии браузера), это будет равно SESSION_COOKIE_AGE.

Эта функция принимает два необязательных ключевых аргумента:

• modification: последнее изменение сеанса в виде объекта datetime. По умолчанию текущее время.
• expiry: сведения об истечении срока действия сеанса в виде объекта datetime, целого числа (в секундах) или None. По умолчанию значение, хранящееся в сеансе функцией set_expiry(), если оно есть, или None.

get_expiry_date()

Возвращает дату истечения срока действия этого сеанса. Для сеансов без пользовательского срока действия (или тех, которые должны истекать при закрытии браузера), это будет дата, наступившая через SESSION_COOKIE_AGE секунд от текущего момента.

Эта функция принимает те же ключевые аргументы, что и get_expiry_age().

get_expire_at_browser_close()

Возвращает либо True, либо False, в зависимости от того, будет ли cookie сеанса пользователя истекать при закрытии веб-браузера пользователя.

clear_expired()

Удаляет истекшие сеансы из хранилища сеансов. Этот метод класса вызывается функцией clearsessions.

cycle_key()

Создаёт новый ключ сеанса, сохраняя при этом текущие данные сеанса. Функция django.contrib.auth.login() вызывает этот метод для защиты от фиксации сеанса.

Сериализация сеансов

По умолчанию Django сериализует данные сеанса с помощью JSON. Вы можете настроить формат сериализации сеанса с помощью параметра SESSION_SERIALIZER. Даже с оговорками, описанными в Написание собственного сериализатора, мы настоятельно рекомендуем придерживаться JSON-сериализации, особенно если вы используете хранилище сеанса cookie.

Например, вот сценарий атаки, если вы используете pickle для сериализации данных сеанса. Если вы используете хранилище сеанса подписанных cookie и SECRET_KEY известен злоумышленнику (нет встроенной уязвимости в Django, которая бы привела к утечке), злоумышленник может вставить строку в свой сеанс, которая при распаковке выполнит произвольный код на сервере. Способ сделать это прост и легко доступен в интернете. Хотя хранилище сеанса cookie подписывает хранящиеся в cookie данные для предотвращения подмены, утечка SECRET_KEY сразу же приводит к уязвимости удалённого выполнения кода.

Встроенные сериализаторы

class serializers.JSONSerializer

Обёртка над JSON-сериализатором из django.core.signing. Может сериализовать только базовые типы данных.

Кроме того, поскольку JSON поддерживает только строковые ключи, обратите внимание, что использование ключей, отличных от строк, в request.session не будет работать должным образом:

>>> # initial assignment
>>> request.session[0] = 'bar'
>>> # subsequent requests following serialization & deserialization
>>> # of session data
>>> request.session[0]  # KeyError
>>> request.session['0']
'bar'

Аналогично, данные, которые нельзя закодировать в JSON, например, байты, не являющиеся UTF-8, такие как '\xd9' (что вызывает UnicodeDecodeError), не могут быть сохранены.

См. раздел «Написание собственного сериализатора» для получения дополнительной информации о ограничениях JSON-сериализации.

class serializers.PickleSerializer

Поддерживает произвольные объекты Python, но, как описано выше, может привести к уязвимости удаленного выполнения кода, если SECRET_KEY станет известен злоумышленнику.

Написание собственного сериализатора

Обратите внимание, что в отличие от PickleSerializer, JSONSerializer не может обрабатывать произвольные типы данных Python. Как часто бывает, существует компромисс между удобством и безопасностью. Если вы хотите хранить более сложные типы данных, включая datetime и Decimal в сессиях, основанных на JSON, вам нужно будет написать пользовательский сериализатор (или преобразовать такие значения в сериализуемый в JSON объект перед их сохранением в request.session). Хотя сериализация этих значений довольно проста (DjangoJSONEncoder может быть полезен), написание декодера, который может надежно вернуть то же самое, что вы ввели, более хрупко. Например, вы рискуете вернуть datetime, который на самом деле был строкой, которая просто оказалась в том же формате, который был выбран для datetime.

Ваш класс сериализатора должен реализовать два метода, dumps(self, obj) и loads(self, data), для сериализации и десериализации словаря данных сессии соответственно.

Рекомендации по работе с объектами сессии

• Используйте обычные строки Python в качестве ключей словаря для request.session. Это скорее конвенция, чем жесткое правило.
• Ключи словаря сессии, начинающиеся с подчеркивания, зарезервированы для внутреннего использования Django.
• Не перезаписывайте request.session новым объектом и не обращайтесь к его атрибутам или не изменяйте их. Используйте его как словарь Python.

Примеры

Этот упрощенный вид устанавливает переменную has_commented в значение True после того, как пользователь разместил комментарий. Он не позволяет пользователю размещать комментарий более одного раза:

def post_comment(request, new_comment):
    if request.session.get('has_commented', False):
        return HttpResponse("You've already commented.")
    c = comments.Comment(comment=new_comment)
    c.save()
    request.session['has_commented'] = True
    return HttpResponse('Thanks for your comment!')

Этот упрощенный вид выполняет вход "члена" сайта:

def login(request):
    m = Member.objects.get(username=request.POST['username'])
    if m.password == request.POST['password']:
        request.session['member_id'] = m.id
        return HttpResponse("You're logged in.")
    else:
        return HttpResponse("Your username and password didn't match.")

…И этот выполняет выход члена, согласно login() выше:

def logout(request):
    try:
        del request.session['member_id']
    except KeyError:
        pass
    return HttpResponse("You're logged out.")

Стандартная функция django.contrib.auth.logout() фактически делает немного больше, чем это, чтобы предотвратить непреднамеренную утечку данных. Она вызывает метод flush() объекта request.session. Мы используем этот пример в качестве демонстрации работы с объектами сессии, а не как полное logout() реализацию.

Установка тестовых куки

Для удобства Django предоставляет простой способ проверить, принимает ли браузер пользователя куки. Просто вызовите метод set_test_cookie() объекта request.session в представлении и вызовите test_cookie_worked() в последующем представлении – не в том же вызове представления.

Эта неловкая разделение между set_test_cookie() и test_cookie_worked() необходимо из-за того, как работают куки. Когда вы устанавливаете куки, вы не можете на самом деле сказать, принял ли браузер куки, пока браузер не сделает следующий запрос.

Хорошей практикой является использование delete_test_cookie() для очистки после себя. Сделайте это после того, как вы проверили, что тестовый куки сработал.

Вот пример типичного использования:

from django.http import HttpResponse
from django.shortcuts import render

def login(request):
    if request.method == 'POST':
        if request.session.test_cookie_worked():
            request.session.delete_test_cookie()
            return HttpResponse("You're logged in.")
        else:
            return HttpResponse("Please enable cookies and try again.")
    request.session.set_test_cookie()
    return render(request, 'foo/login_form.html')

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

>>> from importlib import import_module
>>> from django.conf import settings
>>> SessionStore = import_module(settings.SESSION_ENGINE).SessionStore

Доступен API для управления данными сессии за пределами представления:

>>> from django.contrib.sessions.backends.db import SessionStore
>>> s = SessionStore()
>>> # stored as seconds since epoch since datetimes are not serializable in JSON.
>>> s['last_login'] = 1376587691
>>> s.create()
>>> s.session_key
'2b1189a188b44ad18c35e113ac6ceead'
>>> s = SessionStore(session_key='2b1189a188b44ad18c35e113ac6ceead')
>>> s['last_login']
1376587691

SessionStore.create() предназначен для создания новой сессии (т.е. той, которая не загружается из хранилища сессии и с session_key=None). save() предназначен для сохранения существующей сессии (т.е. той, которая загружается из хранилища сессии).

Вызов save() для новой сессии также может сработать, но существует небольшая вероятность генерации session_key, который конфликтует с существующим. create() вызывает save() и циклически выполняет до тех пор, пока не будет сгенерирована неиспользуемая session_key.

Если вы используете бэкенд django.contrib.sessions.backends.db, каждая сессия представляет собой обычную модель Django. Модель Session определена в django/contrib/sessions/models.py. Поскольку это обычная модель, вы можете получить доступ к сессиям с использованием обычного API базы данных Django:

>>> from django.contrib.sessions.models import Session
>>> s = Session.objects.get(pk='2b1189a188b44ad18c35e113ac6ceead')
>>> s.expire_date
datetime.datetime(2005, 8, 20, 13, 35, 12)

Обратите внимание, что вам необходимо вызвать get_decoded() для получения словаря сессии. Это необходимо, поскольку словарь хранится в закодированном формате:

>>> s.session_data
'KGRwMQpTJ19hdXRoX3VzZXJfaWQnCnAyCkkxCnMuMTExY2ZjODI2Yj...'
>>> s.get_decoded()
{'user_id': 42}

Когда сессии сохраняются

По умолчанию Django сохраняет данные в базе данных сессии только тогда, когда сессия была изменена — то есть, если какие-либо значения её словаря были назначены или удалены:

# Session is modified.
request.session['foo'] = 'bar'

# Session is modified.
del request.session['foo']

# Session is modified.
request.session['foo'] = {}

# Gotcha: Session is NOT modified, because this alters
# request.session['foo'] instead of request.session.
request.session['foo']['bar'] = 'baz'

В последнем случае вышеприведенного примера мы можем явно указать объекту сессии, что он был изменен, установив атрибут modified объекта сессии:

request.session.modified = True

Чтобы изменить это поведение по умолчанию, установите значение параметра SESSION_SAVE_EVERY_REQUEST в True. При установке в значение True, Django сохранит сессию в базе данных на каждом запросе.

Обратите внимание, что куки сессии отправляются только при создании или изменении сессии. Если SESSION_SAVE_EVERY_REQUEST имеет значение True, куки сессии будут отправляться на каждом запросе.

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

Сессия не сохраняется, если код состояния ответа составляет 500.

Сессии с длиной срока действия браузера против постоянных сессий

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

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

Если SESSION_EXPIRE_AT_BROWSER_CLOSE установлено в True, Django будет использовать куки с длиной срока действия браузера — куки, которые истекают как только пользователь закроет свой браузер. Используйте это, если вы хотите, чтобы пользователи каждый раз входили в систему при открытии браузера.

Этот параметр является глобальным значением по умолчанию и может быть переопределен на уровне каждой сессии путем явного вызова метода set_expiry() объекта request.session , как описано выше в разделе использование сессий в представлениях.

Очистка хранилища сессий

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

Чтобы понять эту проблему, рассмотрим, что происходит с бэкендом базы данных. Когда пользователь входит в систему, Django добавляет строку в таблицу базы данных django_session. Django обновляет эту строку каждый раз, когда данные сессии изменяются. Если пользователь выходит из системы вручную, Django удаляет строку. Но если пользователь не выходит из системы, строка никогда не удаляется. Аналогичный процесс происходит с файловым бэкендом.

Django не предоставляет автоматическую очистку просроченных сессий. Поэтому вы должны периодически очищать просроченные сессии. Django предоставляет команду управления для этой цели: clearsessions. Рекомендуется вызывать эту команду регулярно, например, как ежедневную задачу cron.

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

Параметры

Несколько параметров Django позволяют управлять поведением сессии:

• SESSION_CACHE_ALIAS
• SESSION_COOKIE_AGE
• SESSION_COOKIE_DOMAIN
• SESSION_COOKIE_HTTPONLY
• SESSION_COOKIE_NAME
• SESSION_COOKIE_PATH
• SESSION_COOKIE_SAMESITE
• SESSION_COOKIE_SECURE
• SESSION_ENGINE
• SESSION_EXPIRE_AT_BROWSER_CLOSE
• SESSION_FILE_PATH
• SESSION_SAVE_EVERY_REQUEST
• SESSION_SERIALIZER

Безопасность сессий

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

Например, злоумышленник может войти в good.example.com и получить действительную сессию для своей учётной записи. Если злоумышленник контролирует bad.example.com, он может использовать его для отправки своего ключа сессии, так как поддомен может устанавливать куки на *.example.com. При посещении good.example.com, вы войдёте в систему как злоумышленник и можете случайно ввести свои конфиденциальные данные (например, данные кредитной карты) в учётную запись злоумышленника.

Другая возможная атака произойдёт, если good.example.com установит свой SESSION_COOKIE_DOMAIN на "example.com", что приведёт к отправке куки сессии этого сайта на bad.example.com.

Технические подробности

• Словарь сессии принимает любые сериализуемые с помощью json значения при использовании JSONSerializer или любые пиклируемые объекты Python при использовании PickleSerializer. Подробнее см. модуль pickle.
• Данные сессии хранятся в таблице базы данных с именем django_session.
• Django отправляет куки только если это необходимо. Если вы не установили никаких данных сессии, куки сессии не будут отправлены.

Объект SessionStore

Внутренне Django использует объект хранилища сессий из соответствующего движка сессий. По соглашению, класс объекта хранилища сессий называется SessionStore и расположен в модуле, указанном в SESSION_ENGINE.

Все классы SessionStore в Django наследуются от SessionBase и реализуют методы обработки данных, а именно:

• exists()
• create()
• save()
• delete()
• load()
• clear_expired()

Чтобы создать пользовательский движок сессий или настроить существующий, можно создать новый класс, наследующийся от SessionBase или любого другого существующего класса SessionStore.

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

Расширение движков сессий на базе БД

Создание пользовательского движка сессий на базе БД, построенного на базе включённых в Django (а именно db и cached_db), можно осуществить, унаследовав от AbstractBaseSession и либо SessionStore класс.

AbstractBaseSession и BaseSessionManager импортируются из django.contrib.sessions.base_session , чтобы их можно было импортировать без включения django.contrib.sessions в INSTALLED_APPS.

class base_session.AbstractBaseSession

Абстрактная базовая модель сессии.

session_key

Первичный ключ. Само поле может содержать до 40 символов. Текущая реализация генерирует строку из 32 символов (случайная последовательность цифр и строчных латинских букв).

session_data

Строка, содержащая закодированный и сериализованный словарь сессии.

expire_date

Дата и время истечения срока действия сессии.

Истекшие сессии недоступны пользователю, однако они всё ещё могут храниться в базе данных до тех пор, пока не будет выполнена команда управления clearsessions.

classmethod get_session_store_class()

Возвращает класс хранилища сессий для использования с этой моделью сессий.

get_decoded()

Возвращает декодированные данные сессии.

Декодирование выполняется классом хранилища сессий.

Также можно настроить менеджер модели, наследуя от BaseSessionManager:

class base_session.BaseSessionManager

encode(session_dict)

Возвращает сериализованный и закодированный в виде строки словарь сессии.

Кодирование выполняется классом хранилища сессий, связанным с классом модели.

save(session_key, session_dict, expire_date)

Сохраняет данные сессии для предоставленного ключа сессии или удаляет сессию, если данные пусты.

Настройка классов SessionStore достигается путём переопределения методов и свойств, описанных ниже:

class backends.db.SessionStore

Реализует хранилище сессий на базе БД.

classmethod get_model_class()

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

create_model_instance(data)

Возвращает новый экземпляр объекта модели сессии, представляющий текущее состояние сессии.

Переопределение этого метода предоставляет возможность изменять данные модели сессии перед сохранением их в базе данных.

class backends.cached_db.SessionStore

Реализует кэшированное хранилище сессий на базе БД.

cache_key_prefix

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

Пример

Пример ниже демонстрирует пользовательский движок сессий на базе БД, который включает дополнительный столбец базы данных для хранения идентификатора учётной записи (позволяя запросить в базе данных все активные сессии для учётной записи):

from django.contrib.sessions.backends.db import SessionStore as DBStore
from django.contrib.sessions.base_session import AbstractBaseSession
from django.db import models

class CustomSession(AbstractBaseSession):
    account_id = models.IntegerField(null=True, db_index=True)

    @classmethod
    def get_session_store_class(cls):
        return SessionStore

class SessionStore(DBStore):
    @classmethod
    def get_model_class(cls):
        return CustomSession

    def create_model_instance(self, data):
        obj = super().create_model_instance(data)
        try:
            account_id = int(data.get('_auth_user_id'))
        except (ValueError, TypeError):
            account_id = None
        obj.account_id = account_id
        return obj

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

class SessionStore(CachedDBStore):
    cache_key_prefix = 'mysessions.custom_cached_db_backend'

    # ...

Идентификаторы сессий в URL-адресах

Фреймворк сессий Django полностью и исключительно основан на куках. Он не использует URL-адреса для идентификаторов сессий в качестве последнего средства, как PHP. Это умышленное решение. Такое поведение не только ухудшает внешний вид URL-адресов, но и делает ваш сайт уязвимым для кражи идентификаторов сессии через заголовок «Referer».