Sessioner & Säkerhet

Dokumentsessioner och åtkomstkontroll

En Doconut token är kraftfull: den som presenterar den kan begära varje sida i dokumentet om den inte var bunden till den öppningssession som skapade den. Den här sidan förklarar vad en session innehåller, hur länge den lever och vilka kontroller UseDoconut() aktiverar som standard.

Vad en dokumentsession innehåller

Varje lyckad OpenDocumentAsync skapar en session i IMemoryCache:

  • den laddade format‑visaren (dokumentmotor‑instansen som håller det parsade dokumentet),
  • per‑sidostatus — rotation, speglingar och annoteringsdata som användaren applicerar i widgeten,
  • den valfria sökindexen, byggd lazily vid den första sökningen (eller laddad från en förbyggd .srh‑fil i web‑farm‑scenarier),
  • 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 tokenen. När en session blir borttagen — genom utgång eller genom CloseDocument(token) — rensar dess eviktions‑callback 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 som visar Document session not found. Please re-open document. — klienten måste öppna igen för att få en ny token.

Inbyggd tokenbindning

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

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

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

  • Klienten måste skicka ASP.NET session‑cookie med sidbegäran. Cross‑origin‑inställningar som tar bort cookies (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 (t.ex. server‑till‑server‑rendering); låt den false i produktion.

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 DocumentAccessMiddleware automatiskt före sid‑middleware. Registrera den inte en andra gång. När en begäran bär en token, slår den upp åtkomsttillståndet som registrerades när dokumentet öppnades och godkänner bara om alla följande gäller:

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

Fel returnerar 403 — som en PNG‑felbild för sid‑/miniatyr‑begäran, 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 middleware med stängt läge 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‑middleware verifierar sedan secure-{token}‑sessions‑markören innan den levererar dokumentet. Med UnsafeMode = true hoppar UseDoconut() över åtkomst‑middleware och kontrollen av kärn‑markören inaktiveras också.

Återkallelse

CloseDocument(token) frigör inte bara minnet — 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) — den här globala växeln är det som binder token till sessioner.
  • Registrera AddDistributedMemoryCache() (MVC‑ och Razor‑Pages‑appar har den redan) och AddSession(), och anropa app.UseSession() innan Doconut‑middleware‑grenen.
  • Se till att din session‑cookie‑policy låter widgetens begäran bära cookie:n (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.

Var den här sidan hjälpsam?