Relace & Zabezpečení

Relace dokumentu a řízení přístupu

Token Doconut je mocný: kdokoli jej předloží může požadovat každou stránku dokumentu, pokud není vázán na otevírací relaci. Tato stránka vysvětluje, co relace obsahuje, jak dlouho žije a jaké kontroly UseDoconut() ve výchozím nastavení povoluje.

Co obsahuje relace dokumentu

Každé úspěšné volání OpenDocumentAsync vytvoří v IMemoryCache jednu relaci:

  • načtený formátový prohlížeč (instance dokumentového enginu držící parsovaný dokument),
  • stav na stránce — rotace, převrácení a data anotací, která uživatel aplikuje ve widgetu,
  • volitelný vyhledávací index, vytvořený líně při prvním vyhledávání (nebo načtený z předem vytvořeného souboru .srh ve scénářích web‑farmy),
  • relace vodoznak z DocOptions.Watermark.

Životnost

Relace vyprší po posuvném okně: DocOptions.TimeOut minut (výchozí 60), resetováno každým požadavkem, který předloží token. Když je relace vyřazena — vypršením nebo pomocí CloseDocument(token) — její vyvolací funkce uvolní dokumentový engine a okamžitě uvolní přidělenou paměť.

csharp
// A short-lived session for a one-shot preview
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

Požadavek s vypršeným tokenem získá chybový obrázek s textem Document session not found. Please re-open document. — klient musí dokument znovu otevřít, aby získal čerstvý token.

Vestavěné vázání tokenu

S UnsafeMode = false (výchozí) OpenDocumentAsync váže nový token k ASP.NET relaci HTTP požadavku, který jej otevřel, zápisem značky secure-{token} do této relace. Middleware Doconut pak odmítá poskytovat stránky jakékoli jiné relaci prohlížeče:

  • Jiný prohlížeč/relace předkládající odcizený token → chybový obrázek You Are Not Authorized To View This Page.
  • Middleware relace není zaregistrován → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

Proto Quick Start trvá na AddSession() + app.UseSession() před větví Doconut. Dvě praktické důsledky:

  • Klient musí s požadavky na stránky posílat session cookie ASP.NET. Nastavení napříč doménami, která odstraňují cookies (nebo API klient bez úložiště cookies), selže v kontrole — to je funkce, ne chyba.
  • options.UnsafeMode = true zakáže vázání úplně. Existuje pro řízené scénáře (např. server‑to‑server renderování); v produkci nechte false.

Vázání tokenu je řízeno výhradně tímto globálním přepínačem UnsafeMode — je ve výchozím nastavení zapnutý (UnsafeMode = false) a platí pro každou relaci. Neexistuje možnost odhlášení na úrovni dokumentu; nastavení UnsafeMode = true zakáže vázání globálně.

Přístupová oprávnění a autentizovaní uživatelé

Když je UnsafeMode false, UseDoconut() automaticky vloží DocumentAccessMiddleware před middleware stránky. Neregistrujte jej podruhé. Když požadavek nese token, vyhledá přístupové oprávnění zaznamenané při otevření dokumentu a autorizuje pouze pokud platí všechny následující podmínky:

  1. existuje oprávnění pro token,
  2. nevypršela jeho platnost (životnost oprávnění = TimeOut dokumentu),
  3. ID ASP.NET relace požadujícího odpovídá té, která dokument otevřela,
  4. pokud byl otevírač autentizován, shoduje se také claim NameIdentifier požadujícího uživatele.

Selhání vrací 403 — jako PNG chybový obrázek pro požadavky na stránku/miniaturní obrázek, jinak jako prostý text. Zpráva a klíč dotazu tokenu pocházejí z DocumentSecurityOptions (TokenQueryKey, výchozí "token"; UnauthorizedMessage, výchozí "You Are Not Authorized To View This Page."). Nakonfigurujte tyto možnosti přes ASP.NET Core DI před sestavením aplikace. Pokud není stav relace dostupný, middleware selže uzavřením s 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.";
});

Jádrový middleware stránky pak ověří značku relace secure-{token} před tím, než dokument poskytne. S UnsafeMode = true UseDoconut() přeskočí přístupový middleware a kontrola jádrové značky je také zakázána.

Odvolání

CloseDocument(token) neuvolní jen paměť — také odstraní značku secure-{token} a odvolá přístupové oprávnění, takže uzavřený token je okamžitě neplatný na obou bezpečnostních vrstvách.

Kontrolní seznam pro produkci

  • Nechte UnsafeMode = false (výchozí) — tento globální přepínač váže tokeny k relacím.
  • Zaregistrujte AddSession() a zavolejte app.UseSession() před větví middleware Doconut.
  • Ujistěte se, že politika vašich session cookie umožňuje požadavkům widgetu přenášet cookie (SameSite, HTTPS).
  • Použijte CloseDocument, když uživatel opustí dokument — paměť i bezpečnost získají výhodu.
  • Nikdy neukládejte ani nesdílejte tokeny; považujte je za krátkodobé pověření.

Byla tato stránka užitečná?