Sitzungen & Sicherheit
Dokumentensitzungen 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:
- den geladenen Format-Viewer (die Dokument-Engine-Instanz, die das geparste Dokument hält),
- Seitenbezogenen Zustand — Drehungen, Spiegelungen und Anmerkungsdaten, die der Benutzer im Widget anwendet,
- den optionalen Suchindex, der beim ersten Suchen träge erstellt wird (oder aus einer vorgefertigten
.srh-Datei geladen wird, wenn Seiten aus gemeinsamem Speicher bereitgestellt werden), - das Sitzungs-Wasserzeichen von
DocOptions.Watermark.
Lebensdauer
Sitzungen verfallen nach einem gleitenden Zeitfenster: 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) — löst ihr Verwerfungs-Callback die Dokument-Engine und gibt den zugehörigen Speicher sofort frei.
// 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 (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 dieser Sitzung geschrieben wird. Die Doconut‑Middleware verweigert dann das Bereitstellen von Seiten an 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 der Quick‑Start darauf, dass AddSession() + app.UseSession() vor dem Doconut‑Zweig verwendet 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‑Speicher), lassen die Prüfung fehlschlagen — das ist die beabsichtigte Funktionsweise, kein Fehler.
options.UnsafeMode = truedeaktiviert die Bindung vollständig. Sie existiert für kontrollierte Szenarien (z. B. Server‑zu‑Server‑Rendering); lassen Sie sie in der Produktionfalse.
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.
Zugriffsrechte 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 das beim Öffnen des Dokuments aufgezeichnete Zugriffsrecht und autorisiert nur, wenn alle folgenden Bedingungen erfüllt sind:
- ein Zugriffsrecht für das Token existiert,
- es ist nicht abgelaufen (Zugriffsrecht-Lebensdauer = das Dokument‑
TimeOut), - die anfragende ASP.NET‑Sitzungs‑ID mit derjenigen übereinstimmt, die das Dokument geöffnet hat,
- wenn der Öffner authentifiziert war, stimmt der
NameIdentifier‑Anspruch des anfragenden Benutzers ebenfalls ü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 von 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. Wenn der Sitzungszustand nicht verfügbar ist, schlägt die Middleware mit HTTP 500 fehl: ASP.NET Session is required for Doconut document security.
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.
Sicherheit über mehrere Knoten hinweg
Sitzungsgebundene Tokens gehen davon aus, dass der Knoten, der eine Seite bereitstellt, auch die Anfrage gesehen hat, die das Dokument geöffnet hat. Diese Annahme gilt nicht, wenn mehrere Knoten dieselben Dokumente aus gemeinsamem Speicher bereitstellen: Eine Seitenanfrage kann bei einem Knoten landen, der die Öffnung nie gesehen hat, und die sitzungsbezogene Prüfung verwirft sie.
Die Lösung besteht nicht darin, Dokumente ungeschützt zu lassen. Verwenden Sie signierte Zugriffs‑Tickets über AddDoconutDistributedDocumentSecurity(...), die die Sitzungsprüfung durch ein Anmelde‑Token ersetzen, das jeder Knoten unabhängig verifizieren kann. Die vollständige Anordnung finden Sie unter
Verteilte Bereitstellungen.
Widerruf
CloseDocument(token) gibt nicht nur Speicher frei — es entfernt auch den secure-{token}‑Marker und widerruft das Zugriffsrecht, sodass ein geschlossenes Token sofort auf beiden Sicherheitsebenen ungültig ist.
Checkliste für die Produktion
- Halten Sie
UnsafeMode = false(Standard) auf einem einzelnen Knoten — dieser globale Schalter bindet Tokens an Sitzungen. - Registrieren Sie
AddDistributedMemoryCache()(MVC‑ und Razor‑Pages‑Apps haben es bereits) undAddSession()und rufen Sieapp.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.
- Bereitstellung aus gemeinsamem Speicher? Wechseln Sie zu signierten Zugriffs‑Tickets, anstatt ungeschützte Dokumente zu akzeptieren.
War diese Seite hilfreich?