Sessioni e Sicurezza

Sessioni dei documenti e controllo degli accessi

Un token Doconut è potente: chi lo presenta potrebbe richiedere ogni pagina del documento se non fosse legato alla sessione di apertura. Questa pagina spiega cosa contiene una sessione, quanto dura e i controlli che UseDoconut() abilita per impostazione predefinita.

Cosa contiene una sessione di documento

Ogni chiamata riuscita a OpenDocumentAsync crea una sessione in IMemoryCache:

  • il visualizzatore di formato caricato (l'istanza del motore del documento che contiene il documento analizzato),
  • lo stato per pagina — rotazione, capovolgimenti e dati di annotazione che l'utente applica nel widget,
  • l'indice di ricerca opzionale, costruito pigramente alla prima ricerca (o caricato da un file .srh pre‑costruito in scenari web‑farm),
  • la filigrana della sessione da DocOptions.Watermark.

Durata

Le sessioni scadono su una finestra mobile: DocOptions.TimeOut minuti (predefinito 60), resettata da ogni richiesta che presenta il token. Quando una sessione viene espulsa — per scadenza o da CloseDocument(token) — la sua callback di espulsione rilascia il motore del documento e libera immediatamente la memoria associata.

csharp
// Una sessione di breve durata per un'anteprima unica
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

Una richiesta con un token scaduto restituisce un'immagine di errore con il testo Document session not found. Please re-open document. — il client deve riaprire il documento per ottenere un nuovo token.

Binding del token integrato

Con UnsafeMode = false (il valore predefinito), OpenDocumentAsync associa il nuovo token alla sessione ASP.NET della richiesta HTTP che lo ha aperto, scrivendo un marcatore secure-{token} in quella sessione. Il middleware Doconut rifiuta quindi di servire pagine a qualsiasi altra sessione del browser:

  • Browser/sessione diversa che presenta un token rubato → immagine di errore You Are Not Authorized To View This Page.
  • Middleware di sessione non registrato → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

Questo è il motivo per cui il Quick Start insiste su AddSession() + app.UseSession() prima del ramo Doconut. Due conseguenze pratiche:

  • Il client deve inviare il cookie di sessione ASP.NET con le richieste di pagina. Configurazioni cross‑origin che rimuovono i cookie (o un client API senza contenitore di cookie) falliranno il controllo — è una funzionalità che funziona, non un bug.
  • options.UnsafeMode = true disabilita completamente il binding. Esiste per scenari controllati (ad es. rendering server‑to‑server); lasciarlo false in produzione.

Il binding del token è controllato esclusivamente da questo interruttore globale UnsafeMode — è attivo per impostazione predefinita (UnsafeMode = false) e si applica a tutte le sessioni. Non esiste un'opzione di esclusione per documento; impostare UnsafeMode = true disabilita il binding a livello globale.

Concessioni di accesso e utenti autenticati

Quando UnsafeMode è false, UseDoconut() inserisce automaticamente DocumentAccessMiddleware prima del middleware di pagina. Non registrarlo una seconda volta. Quando una richiesta porta un token, cerca il grant di accesso registrato al momento dell'apertura del documento e autorizza solo se tutti questi criteri sono soddisfatti:

  1. esiste un grant per il token,
  2. non è scaduto (durata del grant = il TimeOut del documento),
  3. l'ID della sessione ASP.NET della richiesta corrisponde a quello che ha aperto il documento,
  4. se chi ha aperto il documento era autenticato, la claim NameIdentifier dell'utente richiedente corrisponde.

I fallimenti restituiscono 403 — come immagine PNG di errore per richieste di pagina/miniatura, altrimenti come testo semplice. Il messaggio e la chiave di query del token provengono da DocumentSecurityOptions (TokenQueryKey, predefinito "token"; UnauthorizedMessage, predefinito "You Are Not Authorized To View This Page."). Configura queste opzioni tramite l'iniezione di dipendenze di ASP.NET Core prima di costruire l'app. Se lo stato della sessione non è disponibile, il middleware fallisce chiuso con 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.";
});

Il middleware di pagina principale verifica quindi il marcatore di sessione secure-{token} prima di servire il documento. Con UnsafeMode = true, UseDoconut() salta il middleware di accesso e anche il controllo del marcatore principale è disabilitato.

Revoca

CloseDocument(token) non libera solo la memoria — rimuove anche il marcatore secure-{token} e revoca il grant di accesso, così un token chiuso è inattivo su entrambi gli strati di sicurezza immediatamente.

Elenco di controllo per la produzione

  • Mantieni UnsafeMode = false (il valore predefinito) — questo interruttore globale è ciò che associa i token alle sessioni.
  • Registra AddDistributedMemoryCache() (le app MVC e Razor Pages lo hanno già) e AddSession(), e chiama app.UseSession() prima del ramo middleware Doconut.
  • Assicurati che la tua politica dei cookie di sessione consenta alle richieste del widget di trasportare il cookie (SameSite, HTTPS).
  • Usa CloseDocument quando l'utente lascia il documento — sia la memoria che la sicurezza ne traggono beneficio.
  • Non registrare né condividere mai i token; trattali come credenziali a breve durata.

Questa pagina è stata utile?