Sitzungen & Sicherheit

Dokumentensitzungen und Zugriffskontrolle

Ein Doconut-Token ist mächtig: Wer ihn präsentiert, könnte jede Seite des Dokuments anfordern, wenn er nicht an die ö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 im IMemoryCache:

  • der geladene Format-Viewer (die Dokument-Engine-Instanz, die das geparste Dokument hält),
  • Seitenbezogener Zustand — Drehungen, Spiegelungen und Anmerkungsdaten, die der Benutzer im Widget anwendet,
  • der optionale Suchindex, der beim ersten Suchen träge erstellt wird (oder aus einer vorgefertigten .srh‑Datei geladen wird, wenn Seiten aus gemeinsam genutztem Speicher bereitgestellt werden),
  • das Sitzungs-Wasserzeichen aus DocOptions.Watermark.

Lebensdauer

Sitzungen verfallen in einem gleitenden Fenster: DocOptions.TimeOut Minuten (Standard 60), zurückgesetzt bei jeder Anfrage, die das Token präsentiert. Wenn eine Sitzung verworfen wird — durch Ablauf oder durch CloseDocument(token) —, entsorgt ihr Eviktions‑Callback die Dokument‑Engine 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 Vorgabe) bindet OpenDocumentAsync das neue Token an die ASP.NET‑Sitzung der HTTP‑Anfrage, die es geöffnet hat, indem ein secure-{token}‑Marker in dieser Sitzung geschrieben wird. Die Doconut‑Middleware verweigert dann das Bereitstellen von Seiten für jede andere Browsersitzung:

  • Anderer Browser/Sitzung präsentiert ein gestohlenes Token → 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, AddSession() + app.UseSession() vor dem Doconut‑Zweig aufzurufen. 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‑Speicher), lassen die Prüfung fehlschlagen — das ist das gewünschte Verhalten, kein Bug.
  • options.UnsafeMode = true deaktiviert die Bindung vollständig. Sie existiert für kontrollierte Szenarien; lassen Sie sie in der Produktion auf einem einzelnen Knoten false.

Hinweis zur Schreibweise. Die vorherige .NET‑Standard‑Bibliothek nannte diese Eigenschaft UnSafeMode und übergab sie an die Middleware; hier heißt sie UnsafeMode und wird einmal innerhalb von AddDoconut() gesetzt.

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

Zugriffsberechtigungen und authentifizierte Benutzer

Wenn UnsafeMode false ist, fügt UseDoconut() die Dokument‑Zugriffs‑Middleware automatisch vor der Seiten‑Middleware ein. Registrieren Sie sie nicht ein zweites Mal. Trägt eine Anfrage ein Token, sucht sie den Zugriffs‑Grant nach, der beim Öffnen des Dokuments aufgezeichnet wurde, und autorisiert nur, wenn alle folgenden Bedingungen erfüllt sind:

  1. ein Grant für das Token existiert,
  2. er nicht abgelaufen ist (Grant‑Lebensdauer = das TimeOut des Dokuments),
  3. die anfragende ASP.NET‑Sitzungs‑ID mit derjenigen übereinstimmt, die das Dokument geöffnet hat,
  4. wenn der Öffner authentifiziert war, stimmt der NameIdentifier‑Anspruch des anfragenden Benutzers ebenfalls überein.

Fehler führen zu 403 — 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. Bei UnsafeMode = true überspringt UseDoconut() die Zugriffs‑Middleware und die Kern‑Marker‑Prüfung wird ebenfalls deaktiviert.

Sicherheit über mehrere Knoten hinweg

Session‑gebundene Tokens setzen voraus, dass der Knoten, der eine Seite bereitstellt, ebenfalls die Anfrage gesehen hat, die das Dokument geöffnet hat. Diese Annahme gilt nicht, wenn mehrere Knoten dieselben Dokumente aus gemeinsam genutztem Speicher bereitstellen: Eine Seitenanfrage kann bei einem Knoten landen, der das Öffnen nie gesehen hat, und die per‑Session‑Prüfung verwirft sie.

Die Lösung besteht nicht darin, Dokumente ungeschützt zu lassen. Verwenden Sie signierte Zugriffstickets über AddDoconutDistributedDocumentSecurity(...), das die Sitzungsprüfung durch ein Anmelde‑Credential ersetzt, das jeder Knoten unabhängig verifizieren kann. Die vollständige Anordnung finden Sie unter Verteilte Deployments.

Widerruf

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

Checkliste für die Produktion

  • Behalten Sie UnsafeMode = false (die Vorgabe) auf einem einzelnen Knoten bei — dieser globale Schalter bindet Tokens an Sitzungen.
  • Registrieren Sie AddDistributedMemoryCache() (MVC‑ und Razor‑Pages‑Apps haben es bereits) und AddSession(), und rufen Sie app.UseSession() vor dem Doconut‑Middleware‑Zweig auf.
  • Stellen Sie sicher, dass Ihre Sitzungs‑Cookie‑Richtlinie die Anfragen des Widgets das Cookie mitführen lässt (SameSite, HTTPS).
  • Verwenden Sie CloseDocument, wenn der Benutzer das Dokument verlässt — Speicher und Sicherheit profitieren beide.
  • Loggen oder teilen Sie Tokens niemals; behandeln Sie sie als kurzlebige Anmeldeinformationen.
  • Aus gemeinsam genutztem Speicher bereitstellen? Wechseln Sie zu signierten Zugriffstickets, anstatt ungeschützte Dokumente zu akzeptieren.

War diese Seite hilfreich?