Sesje i bezpieczeństwo
Sesje dokumentu i kontrola dostępu
Token Doconut jest potężny: każdy, kto go przedstawi, mógłby żądać każdej strony dokumentu, gdyby nie był powiązany z sesją otwierającą. Ta strona wyjaśnia, co przechowuje sesja, jak długo żyje i jakie kontrole UseDoconut() włącza domyślnie.
Co przechowuje sesja dokumentu
Każde udane OpenDocumentAsync tworzy jedną sesję w IMemoryCache:
- załadowany podgląd formatu (instancja silnika dokumentu przechowująca przetworzony dokument),
- stan per-strony — rotacja, odbicia i dane adnotacji, które użytkownik stosuje w widżecie,
- opcjonalny indeks wyszukiwania, budowany leniwie przy pierwszym wyszukiwaniu (lub ładowany z wstępnie zbudowanego pliku
.srh, gdy strony są serwowane z współdzielonego magazynu), - znak wodny sesji z
DocOptions.Watermark.
Okres życia
Sesje wygasają w przesuwanym oknie: DocOptions.TimeOut minut (domyślnie 60), resetowane przy każdym żądaniu, które przedstawia token. Gdy sesja zostaje usunięta — z powodu wygaśnięcia lub CloseDocument(token) — jej callback usuwania zwalnia silnik dokumentu i natychmiast zwalnia powiązaną pamięć.
// Krótkotrwała sesja do jednorazowego podglądu
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });Żądanie z wygasłym tokenem otrzymuje obraz błędu wyświetlający Document session not found. Please re-open document. — klient musi ponownie otworzyć, aby uzyskać nowy token.
Wbudowane powiązanie tokenów
Przy użyciu UnsafeMode = false (domyślnie), OpenDocumentAsync wiąże nowy token z sesją ASP.NET żądania HTTP, które go otworzyło, zapisując znacznik secure-{token} w tej sesji. Middleware Doconut odmawia wtedy serwowania stron jakiejkolwiek innej sesji przeglądarki:
- Inna przeglądarka/sesja przedstawiająca skradziony token → obraz błędu
You Are Not Authorized To View This Page. - Middleware sesji nie zarejestrowany → HTTP 500
Session middleware not configured. Call UseSession() before UseDoconut().
Dlatego Quick Start wymaga AddSession() + app.UseSession() przed gałęzią Doconut. Dwa praktyczne konsekwencje:
- Klient musi wysyłać ciasteczko sesji ASP.NET wraz z żądaniami stron. Konfiguracje cross-origin, które usuwają ciasteczka (lub klient API bez pojemnika na ciasteczka), nie przejdą kontroli — to działa zgodnie z przeznaczeniem, a nie jest błędem.
options.UnsafeMode = truewyłącza całkowicie powiązanie. Istnieje dla kontrolowanych scenariuszy (np. renderowanie serwer‑do‑serwera); pozostaw jefalsew produkcji.
Powiązanie tokenów jest kontrolowane wyłącznie przez ten globalny przełącznik UnsafeMode — jest włączony domyślnie (UnsafeMode = false) i dotyczy każdej sesji. Nie ma możliwości wyłączenia per‑dokument; ustawienie UnsafeMode = true wyłącza powiązanie globalnie.
Przyznania dostępu i uwierzytelnieni użytkownicy
Gdy UnsafeMode jest false, UseDoconut() automatycznie wstawia DocumentAccessMiddleware przed middleware strony. Nie rejestruj go ponownie. Gdy żądanie zawiera token, wyszukuje przyznanie dostępu zapisane przy otwieraniu dokumentu i autoryzuje tylko wtedy, gdy spełnione są wszystkie poniższe warunki:
- przyznanie istnieje dla tokenu,
- nie wygasło (czas życia przyznania =
TimeOutdokumentu), - identyfikator sesji ASP.NET żądającego pasuje do tego, który otworzył dokument,
- jeśli otwierający był uwierzytelniony, roszczenie
NameIdentifierżądającego użytkownika również się zgadza.
Błędy zwracają 403 — jako obraz PNG błędu dla żądań stron/miniatur, w przeciwnym razie jako zwykły tekst. Komunikat i klucz zapytania tokenu pochodzą z DocumentSecurityOptions (TokenQueryKey, domyślnie "token"; UnauthorizedMessage, domyślnie "You Are Not Authorized To View This Page."). Skonfiguruj te opcje poprzez ASP.NET Core DI przed zbudowaniem aplikacji. Jeśli stan sesji jest niedostępny, middleware zamyka się z HTTP 500: 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.";
});Podstawowy middleware strony weryfikuje znacznik sesji secure-{token} przed udostępnieniem dokumentu. Przy użyciu UnsafeMode = true, UseDoconut() pomija middleware dostępu, a sprawdzenie podstawowego znacznika jest również wyłączone.
Bezpieczeństwo w kilku węzłach
Tokeny powiązane z sesją zakładają, że węzeł serwujący stronę również widział żądanie, które otworzyło dokument. To założenie nie obowiązuje, gdy kilka węzłów serwuje te same dokumenty z współdzielonego magazynu: żądanie strony może trafić na węzeł, który nigdy nie widział otwarcia, a kontrola per‑sesja odrzuca je.
Rozwiązaniem nie jest pozostawianie dokumentów niechronionych. Użyj podpisanych biletów dostępu poprzez AddDoconutDistributedDocumentSecurity(...), które zastępują kontrolę sesji poświadczeniem, które każdy węzeł może zweryfikować niezależnie. Pełna konfiguracja znajduje się w Rozproszone wdrożenia.
Unieważnianie
CloseDocument(token) nie tylko zwalnia pamięć — usuwa także znacznik secure-{token} i unieważnia przyznanie dostępu, więc zamknięty token jest natychmiast nieaktywny na obu warstwach bezpieczeństwa.
Lista kontrolna dla produkcji
- Utrzymuj
UnsafeMode = false(domyślnie) na jednym węźle — ten globalny przełącznik wiąże tokeny z sesjami. - Zarejestruj
AddDistributedMemoryCache()(aplikacje MVC i Razor Pages już go mają) orazAddSession(), i wywołajapp.UseSession()przed gałęzią middleware Doconut. - Upewnij się, że polityka ciasteczek sesji pozwala żądaniom widżetu przenosić ciasteczko (
SameSite, HTTPS). - Użyj
CloseDocument, gdy użytkownik opuszcza dokument — korzyść zarówno dla pamięci, jak i bezpieczeństwa. - Nigdy nie loguj ani nie udostępniaj tokenów; traktuj je jako krótkotrwałe poświadczenia.
- Serwujesz z współdzielonego magazynu? Przejdź na podpisane bilety dostępu zamiast akceptować niechronione dokumenty.
Czy ta strona była pomocna?