Sesje i bezpieczeństwo

Sesje dokumentów 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 trwa i jakie kontrole domyślnie włącza UseDoconut().

Co przechowuje sesja dokumentu

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

  • załadowany format viewer (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 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 przez CloseDocument(token) — jej callback usuwania zwalnia silnik dokumentu i natychmiast zwalnia powiązaną pamięć.

csharp
// A short-lived session for a one-shot preview
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 tokenów

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 jest zarejestrowany → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

Dlatego w Quick Start wymaga się 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); w produkcji pozostaw false.

Powiązanie tokenów jest kontrolowane wyłącznie przez globalny przełącznik UnsafeMode — jest włączone domyślnie (UnsafeMode = false) i obowiązuje wszystkie sesje. 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 access grant zapisane przy otwieraniu dokumentu i autoryzuje tylko wtedy, gdy spełnione są wszystkie poniższe warunki:

  1. istnieje przyznanie dla tokenu,
  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 z błędem dla żądań stron/miniatur, w przeciwnym razie jako zwykły tekst. Wiadomość 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 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 znacznik sesji secure-{token} przed udostępnieniem dokumentu. Przy UnsafeMode = true, UseDoconut() pomija middleware dostępu, a sprawdzenie znacznika jest również wyłączone.

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) — ten globalny przełącznik wiąże tokeny z sesjami.
  • Zarejestruj 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ż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?