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 trvá a jaké kontroly UseDoconut() ve výchozím nastavení povoluje.

Co obsahuje relace dokumentu

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

  • načtený formátový prohlížeč (instance dokumentového enginu, která drží 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, když jsou stránky podávány ze sdíleného úložiště),
  • vodoznak relace z DocOptions.Watermark.

Životnost

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

csharp
// Krátkodobá relace pro jednorázový náhled
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í znovu otevřít dokument, aby získal čerstvý token.

Vestavěné vázání tokenu

S UnsafeMode = false (výchozí) OpenDocumentAsync sváže nový token s ASP.NET relací HTTP požadavku, který jej otevřel, tím, že do této relace zapíše marker secure-{token}. Middleware Doconut pak odmítne podávat 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í registrován → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

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

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

Vázání tokenu je řízeno výhradně tímto globálním přepínačem UnsafeMode — ve výchozím nastavení je 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 nastaven na 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 povolí přístup 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, odpovídá také nárok uživatele NameIdentifier.

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."). Tyto možnosti nakonfigurujte přes ASP.NET Core DI před vytvořením aplikace. Pokud není stav relace dostupný, middleware selže uzavřeně 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 před podáním dokumentu ověří marker relace secure-{token}. S UnsafeMode = true, UseDoconut() přeskočí přístupový middleware a kontrola markeru v jádru je také vypnuta.

Zabezpečení napříč několika uzly

Tokeny svázané s relací předpokládají, že uzel podávající stránku také viděl požadavek, který dokument otevřel. Tento předpoklad neplatí, když několik uzlů podává stejné dokumenty ze sdíleného úložiště: požadavek na stránku může dopadnout na uzel, který otevření neviděl, a kontrola na úrovni relace jej odmítne.

Řešením není nechat dokumenty nechráněné. Použijte podepsané přístupové lístky přes AddDoconutDistributedDocumentSecurity(...), které nahradí kontrolu relace pověření, jež může každý uzel ověřit samostatně. Kompletní uspořádání je popsáno v Distribuovaná nasazení.

Revokace

CloseDocument(token) neuvolní jen paměť — také odstraní marker 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í) na jediném uzlu — tento globální přepínač je to, co svazuje tokeny s relacemi.
  • Zaregistrujte AddDistributedMemoryCache() (aplikace MVC a Razor Pages jej již mají) a AddSession() a zavolejte app.UseSession() před větví middleware Doconut.
  • Ujistěte se, že politika vašich session cookies umožňuje požadavkům widgetu přenášet cookie (SameSite, HTTPS).
  • Použijte CloseDocument, když uživatel opustí dokument — paměť i bezpečnost mají prospěch.
  • Nikdy nelogujte ani nesdílejte tokeny; zacházejte s nimi jako s krátkodobými pověřeními.
  • Podáváte z sdíleného úložiště? Přesuňte se na podepsané přístupové lístky místo přijímání nechráněných dokumentů.

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