Sitzungen & Sicherheit

Dokumentsitzungen und Zugriffskontrolle

Ein Doconut-Token ist mächtig: Wer ihn vorlegt, könnte jede Seite des Dokuments anfordern, wenn er nicht an die eröffnende Sitzung gebunden wäre. Diese Seite erklärt, was eine Sitzung enthält, wie lange sie lebt und welche Prüfungen UseDoconut() standardmäßig aktiviert.

Was eine Dokumentensitzung enthält

Jeder erfolgreiche OpenDocumentAsync erstellt eine Sitzung in IMemoryCache:

  • der geladene Format-Viewer (die Dokument-Engine-Instanz, die das geparste Dokument hält),
  • der Seitenbezogene Zustand — Drehungen, Spiegelungen und Annotationsdaten, die der Benutzer im Widget anwendet,
  • der optionale Suchindex, der beim ersten Suchen träge erstellt wird (oder aus einer vorgefertigten .srh-Datei in Webfarm-Szenarien geladen wird),
  • das Sitzungs-Wasserzeichen von DocOptions.Watermark.

Lebensdauer

Sitzungen verfallen nach einem gleitenden Fenster: DocOptions.TimeOut Minuten (Standard 60), zurückgesetzt bei jeder Anfrage, die das Token vorlegt. Wenn eine Sitzung verworfen wird — durch Ablauf oder durch CloseDocument(token) — ruft ihr Aufräum-Callback die Dokument-Engine ab und gibt den zugehörigen Speicher sofort frei.

csharp
// Eine kurzlebige Sitzung für eine einmalige Vorschau
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

Eine Anfrage mit einem abgelaufenen Token erhält ein Fehlermotiv mit dem Text Document session not found. Please re-open document. — der Client muss das Dokument erneut öffnen, um ein frisches Token zu erhalten.

Eingebaute Token-Bindung

Mit UnsafeMode = false (der Standard) bindet OpenDocumentAsync das neue Token an die ASP.NET‑Sitzung der HTTP‑Anfrage, die es eröffnet hat, indem ein secure-{token}‑Marker in diese Sitzung geschrieben wird. Die Doconut‑Middleware verweigert dann das Bereitstellen von Seiten für jede andere Browser‑Sitzung:

  • Unterschiedlicher Browser/Sitzung, der ein gestohlenes Token vorlegt → Fehlermotiv You Are Not Authorized To View This Page.
  • Sitzungs‑Middleware nicht registriert → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

Deshalb besteht das Quick‑Start‑Handbuch darauf, dass AddSession() + app.UseSession() vor dem Doconut‑Zweig konfiguriert werden. Zwei praktische Konsequenzen:

  • Der Client muss das ASP.NET‑Sitzungs‑Cookie mit Seitenanfragen senden. Cross‑Origin‑Setups, die Cookies entfernen (oder ein API‑Client ohne Cookie‑Jar), lassen die Prüfung fehlschlagen — das ist ein funktionierendes Feature, kein Bug.
  • options.UnsafeMode = true deaktiviert die Bindung vollständig. Sie existiert für kontrollierte Szenarien (z. B. Server‑zu‑Server‑Rendering); lassen Sie sie false in der Produktion.

Die Token‑Bindung wird ausschließlich durch diesen globalen UnsafeMode‑Schalter gesteuert — er ist standardmäßig aktiviert (UnsafeMode = false) und gilt für jede Sitzung. Es gibt keinen dokumentbezogenen Opt‑Out; das Setzen von UnsafeMode = true deaktiviert die Bindung global.

Zugriffsberechtigungen und authentifizierte Benutzer

Wenn UnsafeMode false ist, fügt UseDoconut() automatisch DocumentAccessMiddleware vor der Seiten‑Middleware ein. Registrieren Sie es nicht ein zweites Mal. Wenn eine Anfrage ein Token enthält, sucht sie die beim Öffnen des Dokuments aufgezeichnete Zugriffsberechtigung und autorisiert nur, wenn alle folgenden Bedingungen erfüllt sind:

  1. Eine Berechtigung für das Token existiert,
  2. Sie ist nicht abgelaufen (Berechtigungsdauer = das Dokument‑TimeOut),
  3. Die anfragende ASP.NET‑Sitzungs‑ID stimmt mit derjenigen überein, die das Dokument eröffnet hat,
  4. Wenn der Eröffner authentifiziert war, stimmt auch der NameIdentifier‑Anspruch des anfragenden Benutzers überein.

Fehler geben 403 zurück — als PNG‑Fehlermotiv für Seiten‑/Thumbnail‑Anfragen, sonst als Klartext. Die Meldung und der Token‑Abfrage‑Schlüssel stammen aus DocumentSecurityOptions (TokenQueryKey, Standard "token"; UnauthorizedMessage, Standard "You Are Not Authorized To View This Page."). Konfigurieren Sie diese Optionen über ASP.NET Core DI, bevor die Anwendung gebaut wird. Ist der Sitzungszustand nicht verfügbar, schlägt die Middleware mit HTTP 500 fehl: 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.";
});

Die Kern‑Seiten‑Middleware prüft dann den secure-{token}‑Sitzungs‑Marker, bevor sie das Dokument bereitstellt. Mit UnsafeMode = true überspringt UseDoconut() die Zugriffs‑Middleware und die Kern‑Marker‑Prüfung wird ebenfalls deaktiviert.

Widerruf

CloseDocument(token) gibt nicht nur Speicher frei — es entfernt auch den secure-{token}‑Marker und widerruft die Zugriffsberechtigung, sodass ein geschlossenes Token sofort auf beiden Sicherheitsebenen ungültig ist.

Checkliste für die Produktion

  • Behalte UnsafeMode = false (der Standard) — dieser globale Schalter bindet Tokens an Sitzungen.
  • Registriere AddDistributedMemoryCache() (MVC‑ und Razor‑Pages‑Apps haben es bereits) und AddSession() und rufe app.UseSession() vor dem Doconut‑Middleware‑Zweig auf.
  • Stelle sicher, dass deine Sitzungs‑Cookie‑Richtlinie die Anfragen des Widgets das Cookie mitführen lässt (SameSite, HTTPS).
  • Verwende CloseDocument, wenn der Benutzer das Dokument verlässt — Speicher und Sicherheit profitieren beide.
  • Logge oder teile Tokens niemals; behandle sie als kurzlebige Anmeldeinformationen.

War diese Seite hilfreich?