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í 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ý prohlížeč formátu (instance enginu dokumentu, 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), resetované každým požadavkem, který token předloží. Když je relace odstraněna — vypršením nebo voláním CloseDocument(token) — její odstraňovací callback uvolní engine dokumentu 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

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 podávat stránky jakékoli jiné relaci prohlížeče:

  • Jiný prohlížeč/relace předkládá odcizený token → chybový obrázek You Are Not Authorized To View This Page.
  • Middleware pro relaci 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 cookie relace ASP.NET s požadavky na stránky. Nastavení napříč doménami, která odstraňují cookies (nebo API klient bez cookie jar), selže — to je funkce, ne chyba.
  • options.UnsafeMode = true svázání zcela vypne. Existuje pro řízené scénáře; v produkci na jediném uzlu jej nechte false.

Všimněte si pravopisu. Předchozí knihovna .NET Standard tuto vlastnost nazývala UnSafeMode a předávala ji middleware; zde je to UnsafeMode a nastavuje se jednou uvnitř AddDoconut().

Svázání tokenu řídí výhradně tento globální přepínač UnsafeMode — je zapnutý ve výchozím nastavení (UnsafeMode = false) a platí pro každou relaci. Neexistuje odvolání na úrovni dokumentu; nastavení UnsafeMode = true vypne svázání globálně.

Přístupová oprávnění a autentizovaní uživatelé

Když je UnsafeMode nastaveno na false, UseDoconut() automaticky vloží middleware pro přístup k dokumentu před middleware pro 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 jen pokud jsou splněny všechny následující podmínky:

  1. oprávnění pro token existuje,
  2. nevypršelo (životnost oprávnění = TimeOut dokumentu),
  3. ID ASP.NET relace požadujícího uživatele odpovídá té, která dokument otevřela,
  4. pokud byl otevírač autentizován, shoduje se i claim NameIdentifier požadujícího uživatele.

Selhání vrací 403 — jako PNG chybový obrázek pro požadavky na stránku/miniaturní náhled, 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 pro stránky pak ověří značku secure-{token} v relaci, než dokument podá. S UnsafeMode = true UseDoconut() přeskočí přístupový middleware a kontrola značky je také vypnuta.

Zabezpečení napříč více 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í 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é nahradí kontrolu relace pověřením, jež může každý uzel ověřit samostatně. Kompletní uspořádání najdete v Distribuovaných nasazeních.

Revokace

CloseDocument(token) neuvolní jen paměť — odstraní také 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 úrovní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 cookie relace umožňuje 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; 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á?