Сесії та безпека

Сесії документів та контроль доступу

Токен Doconut потужний: будь-хто, хто його пред'явить, може запросити кожну сторінку документа, якщо він не прив'язаний до відкриваючої сесії. Ця сторінка пояснює, що містить сесія, як довго вона живе та які перевірки UseDoconut() вмикає за замовчуванням.

Що містить сесія документа

Кожен успішний OpenDocumentAsync створює одну сесію у IMemoryCache:

  • завантажений переглядач формату (екземпляр движка документа, що тримає розпарсений документ),
  • стан на кожній сторінці — обертання, перевороти та дані анотацій, які користувач застосовує у віджеті,
  • необов’язковий індекс пошуку, створюваний ліниво під час першого пошуку (або завантажений з попередньо створеного файлу .srh у сценаріях веб-ферми),
  • водяний знак сесії з DocOptions.Watermark.

Термін дії

Сесії закінчуються за ковзним вікном: DocOptions.TimeOut хвилин (за замовчуванням 60), скидається кожним запитом, що пред'являє токен. Коли сесія видаляється — через закінчення терміну або через CloseDocument(token) — її зворотний виклик видалення звільняє движок документа та одразу звільняє пов'язану пам'ять.

csharp
// Короткоживуча сесія для одноразового попереднього перегляду
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. Два практичних наслідки:

  • Клієнт повинен надсилати кукі сесії ASP.NET разом із запитами сторінок. Налаштування крос‑доменної роботи, які видаляють кукі (або API‑клієнт без сховища кукі), не пройдуть перевірку — це працююча функція, а не помилка.
  • options.UnsafeMode = true повністю вимикає прив’язку. Вона існує для контрольованих сценаріїв (наприклад, рендеринг сервер‑до‑сервера); залиште її false у продакшн.

Прив’язка токенів контролюється виключно цим глобальним перемикачем UnsafeMode — вона ввімкнена за замовчуванням (UnsafeMode = false) і застосовується до кожної сесії. Відмова від прив’язки на рівні окремого документа неможлива; встановлення UnsafeMode = true вимикає прив’язку глобально.

Надання доступу та автентифіковані користувачі

Коли UnsafeMode є false, UseDoconut() автоматично вставляє DocumentAccessMiddleware перед посередником сторінки. Не реєструйте його вдруге. Коли запит містить токен, він шукає надання доступу, записане під час відкриття документа, і авторизує лише за умови виконання всіх наступних пунктів:

  1. існує надання доступу для токену,
  2. його термін не закінчився (тривалість надання = TimeOut документа),
  3. ідентифікатор сесії ASP.NET, що запитує, збігається з тим, що відкрив документ,
  4. якщо відкривач був автентифікований, то вимога користувача 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.

csharp
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() пропускає посередник доступу, і перевірка основного маркера також вимикається.

Відкликання

CloseDocument(token) не лише звільняє пам'ять — вона також видаляє маркер secure-{token} і відкликає надання доступу, тому закритий токен негайно стає недійсним на обох рівнях безпеки.

Контрольний список для продакшн

  • Залиште UnsafeMode = false (за замовчуванням) — цей глобальний перемикач прив'язує токени до сесій.
  • Зареєструйте AddDistributedMemoryCache() (MVC та Razor Pages вже мають його) та AddSession(), і викличте app.UseSession() перед гілкою посередника Doconut.
  • Переконайтеся, що ваша політика кукі сесії дозволяє запитам віджету передавати кукі (SameSite, HTTPS).
  • Використовуйте CloseDocument, коли користувач залишає документ — це корисно для пам'яті та безпеки.
  • Ніколи не реєструйте та не діліться токенами; розглядайте їх як короткоживучі облікові дані.

Чи була ця сторінка корисною?