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 oraz 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 na stronę — obrót, 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ą po przesuwanym oknie: DocOptions.TimeOut minut (domyślnie 60), resetowanym przy każdym żądaniu, które przedstawia token. Gdy sesja zostaje usunięta — z powodu wygaśnięcia lub przez CloseDocument(token) — jej callback usuwania zwalnia silnik dokumentu i natychmiast zwalnia powiązaną pamięć.

csharp
// Krótkotrwała sesja dla 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ć, 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 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 Quick Start wymaga 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, które usuwają ciasteczka (lub klient API bez pojemnika na ciasteczka), nie przejdą kontroli — to działająca funkcja, a nie błąd.
  • options.UnsafeMode = true wyłącza powiązanie całkowicie. Istnieje dla kontrolowanych scenariuszy (np. renderowanie serwer‑do‑serwera); pozostaw je false w produkcji.

Powiązanie tokenów 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 per dokument; ustawienie UnsafeMode = true wyłącza powiązanie globalnie.

Przyznania dostępu i uwierzytelnieni użytkownicy

Gdy UnsafeMode jest false, UseDoconut() wstawia DocumentAccessMiddleware automatycznie 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:

  1. istnieje przyznanie dla tokena,
  2. nie wygasło (okres 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. Komunikat 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 przez 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 strony weryfikuje następnie znacznik sesji secure-{token} przed dostarczeniem dokumentu. Przy użyciu UnsafeMode = true, UseDoconut() pomija middleware dostępu i sprawdzanie znacznika jest również wyłączone.

Unieważnienie

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

  • Zachowaj 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 przenosić ciasteczko (SameSite, HTTPS).
  • Użyj CloseDocument gdy użytkownik opuszcza dokument — korzyść dla pamięci 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?