הפעלות ואבטחה

הפעלות מסמך ובקרת גישה

אסימון Doconut הוא חזק: כל מי שמציג אותו יכול לבקש כל דף של המסמך אם הוא לא קשור להפעלה הפתיחה. דף זה מסביר מה הפעלה מכילה, כמה זמן היא נשארת, והבדיקות שה‑UseDoconut() מאפשרת כברירת מחדל.

מה שמכילה הפעלת מסמך

כל OpenDocumentAsync מוצלח יוצר הפעלה אחת ב‑IMemoryCache:

  • ה‑loaded format viewer (מופע מנוע המסמך המחזיק את המסמך המעובד),
  • per-page state — סיבוב, הפיכות, ונתוני אנוטציה שהמשתמש מיישם בווידג'ט,
  • ה‑search index האופציונלי, נבנה באופן עצלני בחיפוש הראשון (או נטען מקובץ .srh שנבנה מראש כאשר דפים מוגשים מאחסון משותף),
  • ה‑watermark של ההפעלה מ‑DocOptions.Watermark.

משך החיים

הפעלות פוגעות ב‑sliding window: DocOptions.TimeOut דקות (ברירת מחדל 60), מתאפסות בכל בקשה שמציגה את האסימון. כאשר הפעלה נשלפת — עקב פקיעה או על‑ידי CloseDocument(token) — קריאת ההחזרה שלה משחררת את מנוע המסמך ומשחררת את הזיכרון המשויך מיד.

csharp
// הפעלה קצרה לתצוגה מקדימה חד‑פעמית
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

בקשה עם אסימון שפג תציג תמונת שגיאה עם הטקסט Document session not found. Please re-open document. — על הלקוח לפתוח מחדש כדי לקבל אסימון חדש.

קשירת אסימונים מובנית

עם UnsafeMode = false (ברירת המחדל), OpenDocumentAsync קושר את האסימון החדש ל‑ASP.NET session של בקשת ה‑HTTP שפתחה אותו, על‑ידי כתיבת סמן secure-{token} לאותה הפעלה. האמצעי האמצעי של Doconut מסרב אז לשרת דפים לכל הפעלה של דפדפן אחרת:

  • הפעלה/דפדפן שונים המציגים אסימון גנוב → תמונת שגיאה You Are Not Authorized To View This Page.
  • האמצעי האמצעי של ההפעלה לא נרשם → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

זה הסיבה שמדריך ההתחלה המהירה מתעקש על AddSession() + app.UseSession() לפני הענף של Doconut. שני השלכות מעשיות:

  • הלקוח חייב לשלוח את session cookie של ASP.NET עם בקשות הדף. הגדרות cross-origin שמסירות קבצי cookie (או לקוח API ללא קובץ cookie) יכשלו בבדיקה — זהו הפונקציונליות הפועלת, לא באג.
  • options.UnsafeMode = true משבית את הקשירה לחלוטין. הוא קיים לתרחישים מבוקרים (למשל רינדור server‑to‑server); השאירו אותו false בייצור.

קשירת האסימונים נשלטת רק על‑ידי המתג הגלובלי UnsafeMode — הוא פעיל כברירת מחדל (UnsafeMode = false) וחול על כל הפעלה. אין אפשרות ויתור לכל מסמך; הגדרת UnsafeMode = true משביתת את הקשירה גלובלית.

הרשאות גישה ומשתמשים מאומתים

כאשר UnsafeMode הוא false, UseDoconut() מוסיף את DocumentAccessMiddleware אוטומטית לפני האמצעי האמצעי של הדף. אל תירשמו אותו פעמיים. כאשר בקשה נושאת אסימון, היא מחפשת את access grant שנרשם כאשר המסמך נפתח ומאשרת רק אם כל התנאים הבאים מתקיימים:

  1. קיימת הרשאה עבור האסימון,
  2. היא לא פגה (משך החיים של ההרשאה = TimeOut של המסמך),
  3. מזהה ה‑ASP.NET session של המבקש תואם לזה שפתח את המסמך,
  4. אם הפותח היה מאומת, תביעת NameIdentifier של המשתמש המבקש תואמת גם היא.

כישלונות מחזירים 403 — כתמונת שגיאה PNG עבור בקשות דף/תמונה ממוזערת, וטקסט פשוט אחרת. ההודעה ומפתח השאילתה של האסימון מגיעים מ‑DocumentSecurityOptions (‏TokenQueryKey, ברירת מחדל "token"; ‏UnauthorizedMessage, ברירת מחדל "You Are Not Authorized To View This Page."). הגדרו אפשרויות אלו דרך ASP.NET Core DI לפני בניית האפליקציה. אם מצב ההפעלה אינו זמין האמצעי האמצעי נכשל סגור עם 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.";
});

האמצעי האמצעי של הדף המרכזי ואז מאמת את סמן ההפעלה secure-{token} לפני שהוא מגיש את המסמך. עם UnsafeMode = true, UseDoconut() מדלג על האמצעי האמצעי של הגישה ובדיקה של הסמן המרכזי גם היא מושבתת.

אבטחה בין מספר צמתים

אסימונים קשורים להפעלה מניחים שהצומת המגיש דף ראה גם את הבקשה שפתחה את המסמך. הנחה זו אינה מתקיימת כאשר מספר צמתים מגישים את אותם המסמכים מאחסון משותף: בקשת דף יכולה להגיע לצומת שמעולם לא ראה את הפתיחה, והבדיקה לפי הפעלה דוחה אותה.

התשובה היא לא להשאיר מסמכים ללא הגנה. השתמשו בכרטיסי גישה חתומים דרך AddDoconutDistributedDocumentSecurity(...), שמחליפים את בדיקת ההפעלה באישור שכל צומת יכול לאמת באופן עצמאי. הסידור המלא נמצא ב‑פריסות מבוזרות.

שלילה

CloseDocument(token) לא רק משחרר זיכרון — הוא גם מסיר את הסמן secure-{token} ומבטל את הרשאת הגישה, כך שאסימון סגור מת בטלות בשתי שכבות האבטחה מיד.

רשימת בדיקה לייצור

  • שמרו על UnsafeMode = false (ברירת המחדל) בצומת יחיד — מתג גלובלי זה הוא מה שקושר אסימונים להפעלות.
  • רשמו את AddDistributedMemoryCache() (אפליקציות MVC ו‑Razor Pages כבר כוללות אותו) ואת AddSession(), וקראו ל‑app.UseSession() לפני ענף האמצעי האמצעי של Doconut.
  • ודאו שמדיניות קובץ ה‑cookie של ההפעלה מאפשרת לבקשות הווידג'ט לשאת את ה‑cookie (SameSite, HTTPS).
  • השתמשו ב‑CloseDocument כאשר המשתמש עוזב את המסמך — זיכרון ואבטחה משופרים.
  • אל תתעדו או תשתפו אסימונים; התייחסו אליהם כאל אישורים קצרים.
  • מגישים מאחסון משותף? עברו לכרטיסי גישה חתומים במקום לקבל מסמכים ללא הגנה.

האם דף זה היה מועיל?