Relace a 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í svázán s otevírací relací. 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ý prohlížeč formátu (instance dokumentového enginu, která drží parsovaný dokument),
  • stav na stránce — otočení, 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‑farm),
  • vodoznak relace pocházející 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 odstraněna — vypršením nebo voláním CloseDocument(token) — její odstraňovací callback uvolní dokumentový engine a okamžitě uvolní přidruženou 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 nový token.

Vestavěné svázání tokenu

S UnsafeMode = false (výchozí) OpenDocumentAsync sváže nový token s ASP.NET relací HTTP požadavku, který jej otevřel, zápisem značky secure-{token} do této relace. Middleware Doconut pak odmítne 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 odesílat cookie relace ASP.NET. Nastavení napříč doménami, která odstraňují cookies (nebo API klient bez úložiště cookies), selže v kontrole — to je zamýšlené chování, ne chyba.
  • options.UnsafeMode = true svázání úplně zakáže. Existuje pro řízené scénáře (např. renderování server‑to‑server); v produkci jej nechte false.

Svá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 svá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 jsou splněny všechny následující podmínky:

  1. existuje oprávnění pro token,
  2. nevypršelo (ž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/miniaturu, 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 k dispozici, 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 secure-{token} v relaci před podáním dokumentu. 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č svazuje tokeny s relacemi.
  • Zaregistrujte AddSession() a zavolejte app.UseSession() před větví middleware Doconut.
  • Ujistěte se, že politika cookie relace umožňuje požadavkům widgetu přenášet cookie (SameSite, HTTPS).
  • Používejte CloseDocument, když uživatel opustí dokument — paměť i bezpečnost těží.
  • Nikdy nelogujte ani nesdílejte tokeny; považujte je za krátkodobé přihlašovací údaje.

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