Sessioni & Sicurezza

Sessioni dei documenti e controllo degli accessi

Un token Doconut è potente: chiunque lo presenti 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

Each successful OpenDocumentAsync creates one session in IMemoryCache:

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

Durata

Le sessioni scadono su una finestra mobile: DocOptions.TimeOut minuti (default 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
// A short-lived session for a one-shot preview
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 per ottenere un token nuovo.

Binding del token integrato

Con UnsafeMode = false (impostazione predefinita), 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 diverso 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 — è il funzionamento previsto, 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 ogni sessione. 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 della pagina. Non registrarlo una seconda volta. Quando una richiesta trasporta un token, ricerca 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 richiedente corrisponde a quello che ha aperto il documento,
  4. se chi ha aperto era autenticato, anche il 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, default "token"; UnauthorizedMessage, default "You Are Not Authorized To View This Page."). Configura queste opzioni tramite il DI 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 base della pagina 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 di base è disabilitato.

Revoca

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

Lista di controllo per la produzione

  • Mantieni UnsafeMode = false (impostazione predefinita) — questo interruttore globale è ciò che associa i token alle sessioni.
  • Registra 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 — la memoria e la sicurezza ne traggono beneficio.
  • Non registrare né condividere mai i token; trattali come credenziali a breve durata.

Questa pagina è stata utile?