Sessions et Sécurité

Sessions de document 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 qu'une session contient, combien de temps elle vit, et les vérifications que UseDoconut() active par défaut.

Ce que contient une session de document

Chaque appel réussi à OpenDocumentAsync crée une session dans IMemoryCache :

  • le visualiseur de format chargé (l'instance du moteur de document contenant le document analysé),
  • é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 .srh pré‑construit dans les scénarios de ferme web),
  • 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.

csharp
// A short-lived session for a one-shot preview
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 le document pour obtenir un nouveau jeton.

Liaison de jeton intégrée

Avec UnsafeMode = false (la valeur par défaut), OpenDocumentAsync lie le nouveau jeton à la session ASP.NET de la requête HTTP qui l’a ouvert, en écrivant un marqueur secure-{token} dans cette session. Le middleware Doconut refuse alors de servir les pages à toute autre session de navigateur :

  • 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 = true désactive complètement la liaison. Elle existe pour des scénarios contrôlés (par ex. rendu serveur‑à‑serveur) ; laissez‑la à false en 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 aucun désengagement 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 automatiquement DocumentAccessMiddleware 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 n’autorise que si toutes les conditions suivantes sont remplies :

  1. une autorisation existe pour le jeton,
  2. elle n’a pas expiré (durée de l’autorisation = le TimeOut du document),
  3. l’ID de session ASP.NET de la requête correspond à celui qui a ouvert le document,
  4. si l’initiateur était authentifié, la revendication NameIdentifier de l’utilisateur demandeur correspond également.

Les échecs renvoient 403 — sous forme d’image PNG d’erreur pour les requêtes de page/miniatature, sinon en texte brut. Le message et la clé de requête du jeton proviennent de DocumentSecurityOptions (TokenQueryKey, valeur par défaut "token" ; UnauthorizedMessage, valeur par défaut "You Are Not Authorized To View This Page."). Configurez ces options via le DI ASP.NET Core avant de construire l’application. Si l’état de session n’est pas disponible, le middleware échoue en fermant avec 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.";
});

Le middleware de page principal vérifie alors le marqueur de session secure-{token} avant de servir le document. Avec UnsafeMode = true, UseDoconut() saute le middleware d’accès et la vérification du marqueur principal est également désactivée.

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 mort sur les deux couches de sécurité.

Liste de contrôle pour la production

  • Conservez UnsafeMode = false (la valeur par défaut) — cet interrupteur global lie les jetons aux sessions.
  • Enregistrez AddSession() et appelez app.UseSession() avant la branche middleware Doconut.
  • Assurez‑vous que la politique de cookie de session permet aux requêtes du widget de transmettre le cookie (SameSite, HTTPS).
  • Utilisez CloseDocument lorsque 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 identifiants à courte durée de vie.

Cette page vous a-t-elle été utile ?