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

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

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

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

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

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

Термін життя

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

csharp
// A short-lived session for a one-shot preview
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. якщо відкривач був автентифікований, то claim NameIdentifier користувача, що робить запит, також збігається.

У випадку невдачі повертається 403 — у вигляді PNG‑зображення помилки для запитів сторінок/мініатюр, у іншому випадку — простим текстом. Повідомлення та ключ запиту токену беруться з DocumentSecurityOptions (TokenQueryKey, за замовчуванням "token"; UnauthorizedMessage, за замовчуванням "You Are Not Authorized To View This Page."). Налаштуйте ці параметри через DI ASP.NET Core перед створенням застосунку. Якщо стан сесії недоступний, посередницьке ПЗ завершує роботу з 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 (за замовчуванням) — цей глобальний перемикач прив’язує токени до сесій.
  • Зареєструйте AddSession() і викличте app.UseSession() перед гілкою посередницького ПЗ Doconut.
  • Переконайтеся, що ваша політика кукі сесії дозволяє запитам віджета передавати кукі (SameSite, HTTPS).
  • Використовуйте CloseDocument, коли користувач залишає документ — це корисно і для пам’яті, і для безпеки.
  • Ніколи не журналюйте і не діліться токенами; розглядайте їх як короткострокові облікові дані.

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