Relace a zabezpečení

Relace dokumentů 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 relace dokumentu obsahuje

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

  • načtený formátový prohlížeč (instance dokumentového enginu, která drží parsovaný dokument),
  • stav na stránku — 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ší po posuvném okně: DocOptions.TimeOut minut (výchozí 60), které se resetuje každým požadavkem, jenž předloží token. Když je relace vyřazena — vypršením nebo voláním CloseDocument(token) — její vyvolací funkce uvolní dokumentový engine a okamžitě uvolní přidruženou paměť.

csharp
// Krátkodobá relace pro jednorázový náhled
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

Požadavek s prošlý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é 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 vyžaduje 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 zakáže vázání úplně. Existuje pro řízené scénáře (např. renderování server‑to‑server); v produkci jej nechte false.

Vázání tokenu řídí výhradně tento globální přepínač 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 zakáže vázání globálně.

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šela (životnost oprávnění = TimeOut dokumentu),
  3. ID ASP.NET relace požadujícího požadavku se shoduje s tím, které otevřelo dokument,
  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 před podáním dokumentu ověří značku relace secure-{token}. 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 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 cookies relace 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é přihlašovací údaje.

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