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

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

Токен 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. Два практичні наслідки:

  • Клієнт повинен надсилати cookie сесії ASP.NET разом із запитами сторінок. Налаштування крос‑доменної роботи, які видаляють cookie (або API‑клієнт без cookie‑скриньки), не пройдуть перевірку — це працююча функція, а не помилка.
  • 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."). Налаштуйте ці параметри через 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 (за замовчуванням) — цей глобальний перемикач прив’язує токени до сесій.
  • Зареєструйте AddSession() і викличте app.UseSession() перед гілкою посередницького ПЗ Doconut.
  • Переконайтеся, що політика cookie сесії дозволяє запитам віджета передавати cookie (SameSite, HTTPS).
  • Використовуйте CloseDocument, коли користувач залишає документ — це корисно і для пам’яті, і для безпеки.
  • Ніколи не реєструйте та не діліться токенами; розглядайте їх як короткоживучі облікові дані.

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