Сессии и безопасность
Сессии документов и контроль доступа
Токен Doconut мощный: кто бы ни представил его, мог бы запросить каждую страницу документа, если бы он не был привязан к открывающей сессии. Эта страница объясняет, что хранит сессия, как долго она живет и какие проверки UseDoconut() включает по умолчанию.
Что хранит сессия документа
Each successful OpenDocumentAsync creates one session in IMemoryCache:
- загруженный просмотрщик формата (экземпляр движка документа, удерживающий разобранный документ),
- состояние каждой страницы — вращение, отражения и данные аннотаций, которые пользователь применяет в виджете,
- необязательный поисковый индекс, создаваемый лениво при первом поиске (или загружаемый из заранее построенного файла
.srh, когда страницы обслуживаются из общего хранилища), - водяной знак сессии из
DocOptions.Watermark.
Время жизни
Сессии истекают по скользящему окну: DocOptions.TimeOut минут (по умолчанию 60), сбрасываемому каждым запросом, представляющим токен. Когда сессия удаляется — из‑за истечения срока или из‑за CloseDocument(token) — её eviction callback освобождает движок документа и сразу освобождает связанную память.
// Кратковременная сессия для однократного предварительного просмотра
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });Запрос с истёкшим токеном получает изображение ошибки, читающее Document session not found. Please re-open document. — клиент должен заново открыть документ, чтобы получить новый токен.
Встроенная привязка токена
С UnsafeMode = false (по умолчанию) OpenDocumentAsync привязывает новый токен к ASP.NET‑сессии HTTP‑запроса, который его открыл, записывая маркер secure-{token} в эту сессию. Промежуточное ПО Doconut затем отказывает в обслуживании страниц любой другой сессии браузера:
- Другой браузер/сессия, представляющая украденный токен → изображение ошибки
You Are Not Authorized To View This Page. - Промежуточное ПО сессии не зарегистрировано → HTTP 500
Session middleware not configured. Call UseSession() before UseDoconut().
Именно поэтому Quick Start настаивает на использовании AddSession() + app.UseSession() перед веткой Doconut. Два практических следствия:
- Клиент должен отправлять cookie сессии ASP.NET вместе с запросами страниц. Настройки кросс‑домена, которые удаляют cookie (или API‑клиент без cookie‑хранилища), не пройдут проверку — это работа функции, а не ошибка.
options.UnsafeMode = trueполностью отключает привязку. Она существует для контролируемых сценариев (например, рендеринг сервер‑к‑серверу); оставьте еёfalseв продакшн.
Привязка токена контролируется исключительно этим глобальным переключателем UnsafeMode — он включён по умолчанию (UnsafeMode = false) и применяется ко всем сессиям. Отключить её для отдельного документа нельзя; установка UnsafeMode = true отключает привязку глобально.
Права доступа и аутентифицированные пользователи
Когда UnsafeMode имеет значение false, UseDoconut() автоматически вставляет DocumentAccessMiddleware перед промежуточным ПО страницы. Не регистрируйте его повторно. Когда запрос содержит токен, он ищет право доступа, записанное при открытии документа, и авторизует только при выполнении всех следующих условий:
- существует право доступа для токена,
- оно не истекло (срок действия права =
TimeOutдокумента), - ID запрашиваемой ASP.NET‑сессии совпадает с тем, который открыл документ,
- если открывший был аутентифицирован, то требование пользователя
NameIdentifierтакже совпадает.
При ошибках возвращается 403 — в виде PNG‑изображения ошибки для запросов страниц/миниатюр, в виде простого текста в остальных случаях. Сообщение и параметр запроса токена берутся из DocumentSecurityOptions (TokenQueryKey, по умолчанию "token"; UnauthorizedMessage, по умолчанию "You Are Not Authorized To View This Page."). Настройте эти параметры через ASP.NET Core DI перед построением приложения. Если состояние сессии недоступно, промежуточное ПО закрывается с ошибкой HTTP 500: ASP.NET Session is required for Doconut document security.
builder.Services.Configure<Doconut.Security.DocumentSecurityOptions>(options =>
{
options.TokenQueryKey = "token";
options.UnauthorizedMessage = "You Are Not Authorized To View This Page.";
});Основное промежуточное ПО страницы затем проверяет маркер сессии secure-{token} перед обслуживанием документа. При использовании UnsafeMode = true, UseDoconut() пропускает промежуточное ПО доступа, и проверка основного маркера также отключается.
Безопасность на нескольких узлах
Токены, привязанные к сессии, предполагают, что узел, обслуживающий страницу, также видел запрос, открывший документ. Это предположение не верно, когда несколько узлов обслуживают одни и те же документы из общего хранилища: запрос страницы может попасть на узел, который никогда не видел открытие, и проверка по сессии отклонит его.
Ответ не в том, чтобы оставлять документы без защиты. Используйте подписанные билеты доступа через AddDoconutDistributedDocumentSecurity(...), которые заменяют проверку сессии на учётные данные, которые каждый узел может проверять независимо. Полная схема описана в Распределённые развертывания.
Отзыв
CloseDocument(token) не только освобождает память — он также удаляет маркер secure-{token} и отзывает право доступа, так что закрытый токен сразу становится недействительным на обоих уровнях безопасности.
Список проверок для продакшн
- Оставьте
UnsafeMode = false(по умолчанию) на одном узле — этот глобальный переключатель привязывает токены к сессиям. - Зарегистрируйте
AddDistributedMemoryCache()(приложения MVC и Razor Pages уже имеют его) иAddSession(), и вызовитеapp.UseSession()перед веткой промежуточного ПО Doconut. - Убедитесь, что политика cookie сессии позволяет запросам виджета передавать cookie (
SameSite, HTTPS). - Используйте
CloseDocument, когда пользователь покидает документ — это выгодно как для памяти, так и для безопасности. - Никогда не записывайте в журнал и не делитесь токенами; рассматривайте их как краткоживущие учётные данные.
- Обслуживание из общего хранилища? Перейдите на подписанные билеты доступа вместо принятия незащищённых документов.
Была ли эта страница полезной?