Relace a zabezpečení

Relace dokumentu a řízení přístupu

Token Doconut je mocný: kdokoli jej předloží by mohl požadovat každou stránku dokumentu, pokud by nebyl 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ří v IMemoryCache jednu relaci:

  • 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ě),
  • 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 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, 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, zápisem markeru secure-{token} do této relace. 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í 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í posílat session cookie ASP.NET 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í, ne chyba.
  • options.UnsafeMode = true úplně zakáže vázání. Existuje pro řízené scénáře (např. renderování server‑to‑server); nechte jej false v produkci.

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 vztahuje se na každou relaci. Neexistuje možnost odhlášení na úrovni dokumentu; nastavení UnsafeMode = true globálně zakáže vázání.

Přístupová oprávnění a ověření 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řítel ověřen, odpovídá také nárok uživatele NameIdentifier.

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ě 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ěří marker relace secure-{token} před podáním dokumentu. S UnsafeMode = true, UseDoconut() přeskočí přístupový middleware a kontrola jádrového markeru je také zakázána.

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

Tokeny vázané na relaci 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í nikdy 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é nahrazují kontrolu relace pověřením, které může každý uzel ověřit samostatně. Celé uspořádání je popsáno v Distribuovaných nasazeních.

Odvolání

CloseDocument(token) neuvolňuje jen paměť — také odstraňuje marker secure-{token} a odvolává 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

  • Uchovávejte UnsafeMode = false (výchozí) na jediném uzlu — tento globální přepínač je to, co váže tokeny k relacím.
  • 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 zabezpečení mají prospěch.
  • Nikdy neukládejte ani nesdílejte tokeny; považujte je za krátkodobé pověření.
  • Podáváte ze 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á?