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

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

Токен 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 з запитами сторінок. Налаштування крос‑доменної роботи, які видаляють cookies (або API‑клієнт без сховища cookies), не пройдуть перевірку — це працююча функція, а не помилка.
  • options.UnsafeMode = true повністю вимикає прив'язування. Воно існує для контрольованих сценаріїв (наприклад, рендеринг сервер‑до‑сервера); залиште його false у продакшн.

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

Доступи та автентифіковані користувачі

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

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

Безпека на кількох вузлах

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

Відповіддю не є залишати документи незахищеними. Використовуйте підписані квитки доступу через AddDoconutDistributedDocumentSecurity(...), які замінюють перевірку сесії на облікові дані, які кожен вузол може перевіряти самостійно. Повна схема описана у розділі Розподілені розгортання.

Відкликання

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

Чек‑лист для продакшну

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

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