Сесії та безпека
Сесії документів та контроль доступу
Токен Doconut є потужним: будь-хто, хто його пред'явить, може запросити кожну сторінку документа, якщо він не прив'язаний до відкриваючої сесії. На цій сторінці пояснюється, що містить сесія, як довго вона живе та які перевірки UseDoconut() увімкнено за замовчуванням.
Що містить сесія документа
Кожен успішний OpenDocumentAsync створює одну сесію в IMemoryCache:
- завантажений переглядач формату (екземпляр движка документа, що містить розпарсений документ),
- стан на кожній сторінці — обертання, перевороти та дані анотацій, які користувач застосовує у віджеті,
- необов’язковий пошуковий індекс, створюваний ліниво під час першого пошуку (або завантажений з попередньо створеного файлу
.srh, коли сторінки подаються зі спільного сховища), - водяний знак сесії з
DocOptions.Watermark.
Тривалість життя
Сесії закінчуються за ковзним вікном: DocOptions.TimeOut хвилин (за замовчуванням 60), скидаються кожним запитом, що пред'являє токен. Коли сесія виводиться — через закінчення терміну або через CloseDocument(token) — її колбек виведення звільняє движок документа та одразу звільняє пов'язану пам'ять.
// Короткочасна сесія для одноразового попереднього перегляду
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 перед посередницьким ПЗ сторінки. Не реєструйте його вдруге. Коли запит містить токен, він шукає надання доступу, записане під час відкриття документа, і авторизує лише якщо виконуються всі наступні умови:
- надання існує для токену,
- воно не прострочене (термін дії надання =
TimeOutдокумента), - ідентифікатор сесії ASP.NET у запиті збігається з тим, що відкрив документ,
- якщо відкривач був автентифікований, то претенція користувача
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.
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, коли користувач залишає документ — це корисно і для пам'яті, і для безпеки. - Ніколи не реєструйте та не діліться токенами; розглядайте їх як короткоживучі облікові дані.
- Подача зі спільного сховища? Перейдіть на підписані квитки доступу замість приймання незахищених документів.
Чи була ця сторінка корисною?