Sessions et Sécurité
Sessions de documents et contrôle d'accès
Un jeton Doconut est puissant : quiconque le présente pourrait demander chaque page du document s'il n'était pas lié à la session d'ouverture. Cette page explique ce que contient une session, sa durée de vie et les vérifications que UseDoconut() active par défaut.
Ce que contient une session de document
Chaque OpenDocumentAsync réussi crée une session dans IMemoryCache :
- le visualiseur de format chargé (l'instance du moteur de document contenant le document analysé),
- l'état par page — rotation, retournements et données d'annotation que l'utilisateur applique dans le widget,
- l'index de recherche optionnel, construit paresseusement lors de la première recherche (ou chargé depuis un fichier
.srhpré‑construit lorsque les pages sont servies depuis un stockage partagé), - le filigrane de session provenant de
DocOptions.Watermark.
Durée de vie
Les sessions expirent selon une fenêtre glissante : DocOptions.TimeOut minutes (par défaut 60), réinitialisée à chaque requête présentant le jeton. Lorsqu'une session est évincée — par expiration ou par CloseDocument(token) — son rappel d'éviction libère le moteur de document et libère immédiatement la mémoire associée.
// Une session de courte durée pour un aperçu ponctuel
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });Une requête avec un jeton expiré reçoit une image d'erreur affichant Document session not found. Please re-open document. — le client doit rouvrir pour obtenir un nouveau jeton.
Liaison de jeton intégrée
Avec UnsafeMode = false (par défaut), OpenDocumentAsync lie le nouveau jeton à la session ASP.NET de la requête HTTP qui l'a ouverte, en écrivant un marqueur secure-{token} dans cette session. Le middleware Doconut refuse alors de servir les pages à toute autre session de navigateur :
- Un navigateur/session différent présentant un jeton volé → image d'erreur
You Are Not Authorized To View This Page. - Middleware de session non enregistré → HTTP 500
Session middleware not configured. Call UseSession() before UseDoconut().
C'est pourquoi le Quick Start insiste sur AddSession() + app.UseSession() avant la branche Doconut. Deux conséquences pratiques :
- Le client doit envoyer le cookie de session ASP.NET avec les requêtes de page. Les configurations cross‑origin qui suppriment les cookies (ou un client API sans jar de cookies) échoueront le contrôle — c'est le fonctionnement prévu, pas un bug.
options.UnsafeMode = truedésactive complètement la liaison. Elle existe pour des scénarios contrôlés (par ex. rendu serveur‑à‑serveur) ; laissez‑lafalseen production.
La liaison de jeton est contrôlée uniquement par cet interrupteur global UnsafeMode — il est activé par défaut (UnsafeMode = false) et s'applique à chaque session. Il n'existe aucune option de désactivation par document ; définir UnsafeMode = true désactive la liaison globalement.
Autorisations d'accès et utilisateurs authentifiés
Lorsque UnsafeMode est false, UseDoconut() insère DocumentAccessMiddleware automatiquement avant le middleware de page. Ne l'enregistrez pas une seconde fois. Lorsqu'une requête porte un jeton, elle recherche l'autorisation d'accès enregistrée lors de l'ouverture du document et autorise uniquement si toutes les conditions suivantes sont remplies :
- une autorisation existe pour le jeton,
- elle n'a pas expiré (durée de vie de l'autorisation = le
TimeOutdu document), - l'ID de session ASP.NET de la requête correspond à celui qui a ouvert le document,
- si l'ouvreur était authentifié, la revendication
NameIdentifierde l'utilisateur requérant correspond également.
Les échecs renvoient 403 — sous forme d'image PNG d'erreur pour les requêtes de page/vignette, sinon en texte brut. Le message et la clé de requête du jeton proviennent de DocumentSecurityOptions (TokenQueryKey, par défaut "token" ; UnauthorizedMessage, par défaut "You Are Not Authorized To View This Page."). Configurez ces options via l'injection de dépendances ASP.NET Core avant de construire l'application. Si l'état de session est indisponible, le middleware échoue en mode fermé avec HTTP 500 : ASP.NET Session is required for Doconut document security.
builder.Services.Configure<Doconut.Security.DocumentSecurityOptions>(options =>
{
options.TokenQueryKey = "token";
options.UnauthorizedMessage = "You Are Not Authorized To View This Page.";
});Le middleware de page principal vérifie alors le marqueur de session secure-{token} avant de servir le document. Avec UnsafeMode = true, UseDoconut() ignore le middleware d'accès et la vérification du marqueur principal est également désactivée.
Sécurité sur plusieurs nœuds
Les jetons liés à la session supposent que le nœud servant une page a également vu la requête qui a ouvert le document. Cette hypothèse ne tient pas lorsque plusieurs nœuds servent les mêmes documents depuis un stockage partagé : une requête de page peut atterrir sur un nœud qui n'a jamais vu l'ouverture, et le contrôle par session la rejette.
La solution n'est pas de laisser les documents non protégés. Utilisez des tickets d'accès signés via AddDoconutDistributedDocumentSecurity(...), qui remplacent le contrôle de session par un credential que chaque nœud peut vérifier indépendamment. L'ensemble complet est décrit dans Déploiements distribués.
Révocation
CloseDocument(token) ne libère pas seulement la mémoire — il supprime également le marqueur secure-{token} et révoque l'autorisation d'accès, de sorte qu'un jeton fermé est immédiatement inactif sur les deux couches de sécurité.
Checklist pour la production
- Conservez
UnsafeMode = false(par défaut) sur un seul nœud — cet interrupteur global est ce qui lie les jetons aux sessions. - Enregistrez
AddDistributedMemoryCache()(les applications MVC et Razor Pages l'ont déjà) etAddSession(), puis appelezapp.UseSession()avant la branche du middleware Doconut. - Assurez‑vous que votre politique de cookie de session permet aux requêtes du widget de transporter le cookie (
SameSite, HTTPS). - Utilisez
CloseDocumentlorsque l'utilisateur quitte le document — la mémoire et la sécurité en bénéficient. - Ne jamais consigner ou partager les jetons ; traitez‑les comme des credentials à courte durée de vie.
- Vous servez depuis un stockage partagé ? Passez aux tickets d'accès signés plutôt que d'accepter des documents non protégés.
Cette page était-elle utile ?