הפעלות ואבטחה
הפעלות מסמך ובקרת גישה
אסימון Doconut הוא חזק: כל מי שמציג אותו יכול לבקש כל דף של המסמך אם הוא לא קשור להפעלה הפתוחה. דף זה מסביר מה ההפעלה מכילה, כמה זמן היא חיה, והבדיקות שה‑UseDoconut() מאפשרת כברירת מחדל.
מה שמכילה הפעלת מסמך
כל OpenDocumentAsync מוצלח יוצר הפעלה אחת ב‑IMemoryCache:
- ה‑loaded format viewer (מופע מנוע המסמך המחזיק את המסמך המעובד),
- ה‑per-page state — סיבוב, הפיכות, ונתוני הערות שהמשתמש מיישם בווידג'ט,
- ה‑search index האופציונלי, נבנה באופן עצלני בחיפוש הראשון (או נטען מקובץ
.srhשנבנה מראש כאשר דפים מוגשים מאחסון משותף), - ה‑watermark של ההפעלה מ‑
DocOptions.Watermark.
משך זמן
הפעלות מתפוגגות במסגרת חלון זמן מתגלגל של DocOptions.TimeOut דקות (ברירת מחדל 60), ומתאפסות בכל בקשה המציגה את האסימון. כאשר הפעלה נשלפת — עקב פקיעה או על‑ידי CloseDocument(token) — פונקציית ההחזרה שלה משחררת את מנוע המסמך ומשחררת את הזיכרון המשויך מיידית.
// מושב קצר-זמן לתצוגה חד-פעמית
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().
זה הסיבה שה‑Quick Start מתעקש על AddSession() + app.UseSession() לפני ענף Doconut. שני השלכות מעשיות:
- הלקוח חייב לשלוח את קוביית סשן של ASP.NET עם בקשות הדף. הגדרות cross‑origin שמסירות קבצי cookie (או לקוח API ללא מחסן קבצי cookie) יכשלו בבדיקה — זהו תפקוד תקין, לא באג.
options.UnsafeMode = trueמשביתת את הקשירה לחלוטין. היא קיימת לתרחישים מבוקרים (למשל רינדור server‑to‑server); השאירו אותהfalseבייצור.
קשירת האסימונים נשלטת רק על‑ידי המתג הגלובלי UnsafeMode — הוא פעיל כברירת מחדל (UnsafeMode = false) וחול על כל הפעלה. אין אפשרות לבטל לכל מסמך בנפרד; הגדרת UnsafeMode = true משביתת את הקשירה גלובלית.
מענקי גישה ומשתמשים מאומתים
כאשר UnsafeMode הוא false, UseDoconut() מוסיף את DocumentAccessMiddleware אוטומטית לפני תוכנת הביניים של הדף. אל תירשמו אותה פעמיים. כאשר בקשה נושאת אסימון, היא מחפשת את מתן גישה שנרשם כאשר המסמך נפתח ומאשרת רק אם כל התנאים הבאים מתקיימים:
- קיים מענק עבור האסימון,
- הוא לא פג (משך החיים של המענק =
TimeOutשל המסמך), - מזהה ההפעלה של ASP.NET של הבקשה תואם לזה שפתח את המסמך,
- אם הפותח היה מאומת, תביעת
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.
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. - ודאו שמדיניות קוביית ה‑session שלכם מאפשרת לבקשות הווידג'ט לשאת את הקובייה (
SameSite, HTTPS). - השתמשו ב‑
CloseDocumentכאשר המשתמש עוזב את המסמך — זיכרון ואבטחה נהנים. - לעולם אל תתעדו או תשתפו אסימונים; התייחסו אליהם כאל אישורים קצרים.
- משרתים מאחסון משותף? עברו לכרטיסי גישה חתומים במקום לקבל מסמכים ללא הגנה.
האם דף זה היה מועיל?