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

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

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

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

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

  • завантажений переглядач формату (екземпляр движка документа, що містить розпарсений документ),
  • стан для кожної сторінки — обертання, відзеркалення та дані анотацій, які користувач застосовує у віджеті,
  • необов’язковий індекс пошуку, створюваний ліниво під час першого пошуку (або завантажений з попередньо створеного файлу .srh у сценаріях веб‑ферми),
  • водяний знак сесії watermark з 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. Два практичних наслідки:

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

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

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

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

  1. надання існує для токену,
  2. воно не прострочене (термін дії надання = TimeOut документа),
  3. ID 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 (за замовчуванням) — цей глобальний перемикач прив’язує токени до сесій.
  • Зареєструйте AddDistributedMemoryCache() (у MVC та Razor Pages застосунках вже є) та AddSession(), і викличте app.UseSession() перед гілкою посередницького ПЗ Doconut.
  • Переконайтеся, що політика cookie сесії дозволяє запитам віджета передавати cookie (SameSite, HTTPS).
  • Використовуйте CloseDocument, коли користувач залишає документ — це корисно і для пам’яті, і для безпеки.
  • Ніколи не журналюйте і не діліться токенами; розглядайте їх як короткоживучі облікові дані.

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