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 zawiera sesja, jak długo trwa i jakie kontrole włącza domyślnie UseDoconut().

Co zawiera sesja dokumentu

Każde udane wywołanie OpenDocumentAsync tworzy jedną sesję w IMemoryCache:

  • załadowany podgląd formatu (instancja silnika dokumentu przechowująca sparsowany dokument),
  • stan per‑strona — rotacja, odbicia i dane adnotacji, które użytkownik stosuje w widżecie,
  • opcjonalny indeks wyszukiwania, tworzony leniwie przy pierwszym wyszukiwaniu (lub ładowany z wstępnie zbudowanego pliku .srh w scenariuszach farmy webowej),
  • znak wodny sesji pochodzący z DocOptions.Watermark.

Okres życia

Sesje wygasają w oknie przesuwającym się: DocOptions.TimeOut minut (domyślnie 60), resetowane przy każdym żądaniu prezentującym token. Gdy sesja zostaje usunięta — z powodu wygaśnięcia lub przez CloseDocument(token) — jej callback usuwający zwalnia silnik dokumentu i natychmiast zwalnia powiązaną pamięć.

csharp
// 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 z napisem Document session not found. Please re-open document. — klient musi ponownie otworzyć dokument, aby uzyskać nowy token.

Wbudowane powiązanie tokena

Przy 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 innym sesjom przeglądarki:

  • Inna przeglądarka/sesja prezentują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 w Quick Start wymaga się wywołania AddSession() + app.UseSession() przed gałęzią Doconut. Dwie praktyczne konsekwencje:

  • Klient musi wysyłać ciasteczko sesji ASP.NET wraz z żądaniami stron. Konfiguracje cross‑origin usuwające ciasteczka (lub klient API bez przechowalni ciasteczek) spowodują niepowodzenie sprawdzenia — to działająca funkcja, a nie błąd.
  • options.UnsafeMode = true wyłącza całkowicie powiązanie. Istnieje dla kontrolowanych scenariuszy (np. renderowanie serwer‑do‑serwera); w produkcji pozostaw false.

Powiązanie tokena jest kontrolowane wyłącznie przez globalny przełącznik UnsafeMode — jest włączone domyślnie (UnsafeMode = false) i dotyczy każdej sesji. Nie ma możliwości wyłączenia go 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 stron. Nie rejestruj go ponownie. Gdy żądanie zawiera token, wyszukuje przyznanie dostępu zapisane podczas otwierania dokumentu i autoryzuje tylko wtedy, gdy spełnione są wszystkie poniższe warunki:

  1. istnieje przyznanie dla tokena,
  2. nie wygasło (czas życia przyznania = TimeOut dokumentu),
  3. identyfikator sesji ASP.NET żądającego pasuje do tego, który otworzył dokument,
  4. jeśli otwierający był uwierzytelniony, roszczenie NameIdentifier żądającego użytkownika również się zgadza.

Niepowodzenia zwracają 403 — jako obraz PNG błędu dla żądań stron/miniatur, w przeciwnym razie jako zwykły tekst. Wiadomość i klucz zapytania tokena 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 budowaniem aplikacji. Jeśli stan sesji jest niedostępny, middleware zamyka się z 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.";
});

Podstawowy middleware stron weryfikuje znacznik sesji secure-{token} przed serwowaniem dokumentu. Przy UnsafeMode = true, UseDoconut() pomija middleware dostępu, a sprawdzanie znacznika jest również wyłączone.

Unieważnienie

CloseDocument(token) nie tylko zwalnia pamięć — usuwa także znacznik secure-{token} i odwołuje 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) — ten globalny przełącznik wiąże tokeny z sesjami.
  • Zarejestruj AddDistributedMemoryCache() (aplikacje MVC i Razor Pages już go mają) oraz AddSession(), i wywołaj app.UseSession() przed gałęzią middleware Doconut.
  • Upewnij się, że polityka ciasteczek sesji pozwala żądaniom widżetu przesyłać ciasteczko (SameSite, HTTPS).
  • Używaj 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.

Czy ta strona była pomocna?