Relace a zabezpečení

Relace dokumentů a řízení přístupu

Token Doconut je mocný: kdokoli ho 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ří 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 ve scénářích web‑farmy),
  • vodoznak relace z DocOptions.Watermark.

Životnost

Relace vyprší na 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ř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í dokument znovu otevřít, aby získal čerstvý token.

Vestavěné svázání tokenu

V režimu 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 volání AddSession() + app.UseSession() před větví Doconut. Dvě praktické důsledky:

  • Klient musí s požadavky na stránky posí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ě vypne. Existuje pro řízené scénáře (např. server‑to‑server renderování); v produkci jej nechte false.

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

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 obsahuje 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, 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."). Tyto možnosti nakonfigurujte pomocí 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 před podáním dokumentu ověří značku relace secure-{token}. Při UnsafeMode = true UseDoconut() přeskočí přístupový middleware a kontrola jádrové značky je také vypnuta.

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 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žívejte CloseDocument, když uživatel opustí dokument — zlepšuje to jak paměť, tak bezpečnost.
  • Nikdy nelogujte ani nesdílejte tokeny; považujte je za krátkodobé přihlašovací údaje.

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