الجلسات والأمان
جلسات المستند والتحكم في الوصول
رمز Doconut قوي: أي شخص يقدمّه يمكنه طلب كل صفحة من المستند إذا لم يكن مرتبطًا بجلسة الفتح. تشرح هذه الصفحة ما تحتفظ به الجلسة، ومدتها، والفحوصات التي يتيحها UseDoconut() بشكل افتراضي.
ما تحتفظ به جلسة المستند
كل OpenDocumentAsync ناجح ينشئ جلسة واحدة في IMemoryCache:
- عارض الصيغة المحملة (مثيل محرك المستند الذي يحتفظ بالمستند المُحلل)،
- حالة كل صفحة — الدوران، القلب، وبيانات التعليقات التي يضيفها المستخدم في الواجهة،
- فهرس البحث الاختياري، يُبنى ببطء عند أول بحث (أو يُحمَّل من ملف
.srhمُسبق الإنشاء عندما تُقدم الصفحات من تخزين مشترك)، - علامة مائية الجلسة من
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().
هذا هو السبب في إصرار دليل البدء السريع على AddSession() + app.UseSession() قبل فرع Doconut. نتيجتان عمليتان:
- يجب على العميل إرسال ملف تعريف الارتباط لجلسة ASP.NET مع طلبات الصفحات. إعدادات عبر الأصل التي تُزيل ملفات تعريف الارتباط (أو عميل API بدون حاوية ملفات تعريف الارتباط) سيفشل الفحص — هذه ميزة تعمل، ليست عطلًا.
options.UnsafeMode = trueيعطل الربط بالكامل. هو موجود لسيناريوهات مُتحكم فيها (مثل التقديم من خادم إلى خادم)؛ اتركه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. - تأكد من أن سياسة ملف تعريف الارتباط للجلسة تسمح لطلبات الواجهة بحمل الملف (
SameSite، HTTPS). - استخدم
CloseDocumentعندما يغادر المستخدم المستند — سيفيد ذلك الذاكرة والأمان. - لا تُسجِّل أو تُشارك الرموز أبداً؛ اعتبرها بيانات اعتماد قصيرة العمر.
- هل تُقدِّم من تخزين مشترك؟ انتقل إلى تذاكر وصول موقعة بدلاً من قبول مستندات غير محمية.
هل كانت هذه الصفحة مفيدة؟