Sessioner & Säkerhet

Dokumentsessioner och åtkomstkontroll

Ett Doconut-token är kraftfullt: den som presenterar det kan begära varje sida i dokumentet om det inte var bundet till den öppnande sessionen. Denna sida förklarar vad en session innehåller, hur länge den varar och vilka kontroller UseDoconut() möjliggör som standard.

Vad en dokumentsession innehåller

Varje lyckad OpenDocumentAsync skapar en session i IMemoryCache:

  • den laddade formatvisaren (dokumentmotorinstansen som håller det parsade dokumentet),
  • per-sida tillstånd — rotation, vändningar och annoteringsdata som användaren tillämpar i widgeten,
  • det valfria sökindexet, byggt lat på den första sökningen (eller laddat från en förbyggd .srh-fil när sidor serveras från delat lagring),
  • sessionens vattenstämpel från DocOptions.Watermark.

Livslängd

Sessioner löper ut på ett glidande fönster: DocOptions.TimeOut minuter (standard 60), återställs av varje begäran som presenterar token. När en session blir utkastad — genom utgång eller av CloseDocument(token) — rensar dess utkastningsåteruppringning dokumentmotorn och frigör det tillhörande minnet omedelbart.

csharp
// En kortlivad session för en engångsförhandsgranskning
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

En begäran med en utgången token får en felbild med texten Document session not found. Please re-open document. — klienten måste öppna om för att få en ny token.

Inbyggd tokenbindning

Med UnsafeMode = false (standard) binder OpenDocumentAsync den nya token till ASP.NET-sessionen för HTTP-begäran som öppnade den, genom att skriva en secure-{token}-markör i den sessionen. Doconut-mellanprogramvaran vägrar sedan att leverera sidor till någon annan webbläsarsession:

  • Olika webbläsare/session som presenterar en stulen token → felbild You Are Not Authorized To View This Page.
  • Session-mellanprogramvara inte registrerad → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

Det är därför Quick Start insisterar på AddSession() + app.UseSession() före Doconut-grenen. Två praktiska konsekvenser:

  • Klienten måste skicka ASP.NET sessionskakan med sidförfrågningar. Cross-origin‑inställningar som tar bort kakor (eller en API-klient utan cookie‑behållare) kommer att misslyckas med kontrollen — det är funktionen som fungerar, inte en bugg.
  • options.UnsafeMode = true inaktiverar bindningen helt. Den finns för kontrollerade scenarier; låt den false i produktion på en enda nod.

Observera stavningen. Det tidigare .NET Standard-biblioteket kallade denna egenskap UnSafeMode och den skickades till mellanprogramvaran; här är den UnsafeMode och den sätts en gång i AddDoconut().

Tokenbindning styrs enbart av denna globala UnsafeMode-växel — den är på som standard (UnsafeMode = false) och gäller för varje session. Det finns ingen per-dokument avstängning; att sätta UnsafeMode = true inaktiverar bindningen globalt.

Åtkomsttillstånd och autentiserade användare

När UnsafeMode är false, sätter UseDoconut() in dokument‑åtkomst‑mellanprogramvaran automatiskt före sid‑mellanprogramvaran. Registrera den inte en andra gång. När en begäran bär en token, söker den upp åtkomsttillståndet som registrerades när dokumentet öppnades och godkänner endast om alla dessa gäller:

  1. ett tillstånd finns för token,
  2. det har inte löpt ut (tillståndets livslängd = dokumentets TimeOut),
  3. den begärande ASP.NET‑sessions‑ID:n matchar den som öppnade dokumentet,
  4. om öppnaren var autentiserad, matchar den begärande användarens NameIdentifier‑anspråk också.

Fel returnerar 403 — som en PNG‑felbild för sid‑/miniatyr‑förfrågningar, som vanlig text annars. Meddelandet och token‑fråge‑nyckeln kommer från DocumentSecurityOptions (TokenQueryKey, standard "token"; UnauthorizedMessage, standard "You Are Not Authorized To View This Page."). Konfigurera dessa alternativ via ASP.NET Core DI innan appen byggs. Om sessions‑tillstånd är otillgängligt misslyckas mellanprogramvaran med stängd åtkomst och 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.";
});

Kärn‑sid‑mellanprogramvaran verifierar sedan secure-{token}‑sessions‑markören innan den levererar dokumentet. Med UnsafeMode = true hoppar UseDoconut() över åtkomst‑mellanprogramvaran och kärn‑markör‑kontrollen inaktiveras också.

Säkerhet över flera noder

Session‑bundna token antar att noden som levererar en sida också såg begäran som öppnade dokumentet. Detta antagande gäller inte när flera noder levererar samma dokument från delat lagring: en sid‑begäran kan hamna på en nod som aldrig såg öppningen, och per‑session‑kontrollen avvisar den.

Svaret är inte att lämna dokument oskyddade. Använd signerade åtkomst‑biljetter via AddDoconutDistributedDocumentSecurity(...), vilket ersätter sessions‑kontrollen med ett behörighetsbevis som varje nod kan verifiera oberoende. Den fullständiga arrangemanget finns på Distribuerade distributioner.

Återkallelse

CloseDocument(token) frigör inte bara minne — den tar också bort secure-{token}‑markören och återkallar åtkomsttillståndet, så en stängd token är omedelbart död på båda säkerhetslagren.

Checklista för produktion

  • Behåll UnsafeMode = false (standard) på en enda nod — denna globala växel är vad som binder token till sessioner.
  • Registrera AddDistributedMemoryCache() (MVC‑ och Razor‑Pages‑appar har den redan) och AddSession(), och anropa app.UseSession() före Doconut‑mellanprogramvarans gren.
  • Se till att din sessions‑cookie‑policy låter widgetens förfrågningar bära cookie (SameSite, HTTPS).
  • Använd CloseDocument när användaren lämnar dokumentet — både minne och säkerhet gynnas.
  • Logga eller dela aldrig token; behandla dem som kortlivade autentiseringsuppgifter.
  • Levereras från delat lagring? Gå över till signerade åtkomst‑biljetter istället för att acceptera oskyddade dokument.

Var den här sidan hjälpsam?