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

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

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

מה כוללת הפעלת מסמך

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

  • הצופה בפורמט הטעון (מופע מנוע המסמך המחזיק את המסמך המפוענח),
  • מצב לכל דף — סיבוב, הפיכות, ונתוני הערות שהמשתמש מיישם בווידג'ט,
  • האינדקס חיפוש האופציונלי, נבנה באופן עצלני בחיפוש הראשון (או נטען מקובץ .srh שנבנה מראש כאשר דפים מוגשים מאחסון משותף),
  • הסימן מים של ההפעלה מDocOptions.Watermark.

משך החיים

הפעלות פוגעות בחלון גלילה: 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 של בקשת ה‑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. שני תוצאות מעשיות:

  • הלקוח חייב לשלוח את קוקיית ההפעלה של ASP.NET עם בקשות הדף. הגדרות חוצות‑מקור שמסירות קookies (או לקוח API ללא מכולת קookies) יכשלו בבדיקה — זהו הפיצ'ר שעובד, לא באג.
  • options.UnsafeMode = true משבית את הקשירה לחלוטין. היא קיימת לתרחישים מבוקרים; השאר אותה false בייצור על צומת יחיד.

שימו לב לאיות. ספריית .NET Standard הקודמת קראה למאפיין זה UnSafeMode והיא הועברה לאמצעי האמצעי; כאן היא UnsafeMode והיא מוגדרת פעם אחת בתוך AddDoconut().

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

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

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

  1. קיימת הרשאה עבור האסימון,
  2. היא לא פגה (משך ההרשאה = TimeOut של המסמך),
  3. מזהה הפעלת ASP.NET של המבקש תואם לזה שפתח את המסמך,
  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.
  • ודאו שמדיניות קוביית ההפעלה שלכם מאפשרת לבקשות הווידג'ט לשאת את הקוקייה (SameSite, HTTPS).
  • השתמשו בCloseDocument כאשר המשתמש עוזב את המסמך — זיכרון ואבטחה משפרים יחד.
  • לעולם אל תתעדו או תשתפו אסימונים; התייחסו אליהם כלאשרי זמן קצרים.
  • מגישים מאחסון משותף? עברו לכרטיסי גישה חתומים במקום לקבל מסמכים ללא הגנה.

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