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

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

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

Чтобы включить функциональность сессий, сделайте следующее:

• Отредактируйте настройку 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 можно настроить на хранение данных сессий на файловой системе или в кэше.

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

Когда 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)

aget(key, default=None)

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

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

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

aget() функция была добавлена.

aset(key, value)

Новое в Django 5.1.

Пример: await request.session.aset('fav_color', 'red')

update(dict)

aupdate(dict)

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

Пример: request.session.update({'fav_color': 'red'})

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

aupdate() функция была добавлена.

pop(key, default=__not_given)

apop(key, default=__not_given)

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

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

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

apop() функция была добавлена.

keys()

akeys()

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

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

akeys() функция была добавлена.

values()

avalues()

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

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

avalues() функция была добавлена.

has_key(key)

ahas_key(key)

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

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

ahas_key() функция была добавлена.

items()

aitems()

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

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

aitems() функция была добавлена.

setdefault()

asetdefault()

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

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

asetdefault() функция была добавлена.

clear()

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

flush()

aflush()

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

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

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

aflush() функция была добавлена.

set_test_cookie()

aset_test_cookie()

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

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

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

aset_test_cookie() функция была добавлена.

test_cookie_worked()

atest_cookie_worked()

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

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

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

atest_cookie_worked() функция была добавлена.

delete_test_cookie()

adelete_test_cookie()

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

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

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

adelete_test_cookie() функция была добавлена.

get_session_cookie_age()

Возвращает значение настройки SESSION_COOKIE_AGE. Это можно переопределить в пользовательском обработчике сессий.

set_expiry(value)

aset_expiry(value)

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

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

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

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

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

aset_expiry() функция была добавлена.

get_expiry_age()

aget_expiry_age()

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

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

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

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

Примечание

Этот метод используется хранилищами сеансов для определения возраста истечения сеанса в секундах при сохранении сеанса. Он не предназначен для использования вне этого контекста.

В частности, хотя возможно определить оставшийся срок действия сеанса только когда у вас есть правильное значение modification и expiry установлено как объект datetime, где у вас есть значение modification, проще рассчитать срок действия вручную:

expires_at = modification + timedelta(seconds=settings.SESSION_COOKIE_AGE)

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

Была добавлена функция aget_expiry_age().

get_expiry_date()

aget_expiry_date()

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

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

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

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

Была добавлена функция aget_expiry_date().

get_expire_at_browser_close()

aget_expire_at_browser_close()

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

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

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

Была добавлена функция aget_expire_at_browser_close().

clear_expired()

aclear_expired()

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

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

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

Была добавлена функция aclear_expired().

cycle_key()

acycle_key()

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

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

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

Была добавлена функция acycle_key().

Настройка тестовых куки

Для удобства 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.
• Данные сессии хранятся в таблице базы данных с именем django_session.
• Django отправляет куки только в случае необходимости. Если вы не установили какие-либо данные сессии, куки сессии не будут отправлены.

Расширение движков сессий с поддержкой базы данных

Создание настраиваемого движка сессий с поддержкой базы данных, построенного на основе тех, которые включены в 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 символов (случайная последовательность цифр и строчных букв ASCII).

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

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

    # ...

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

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