الجلسات والأمان
جلسات المستند والتحكم في الوصول
رمز 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في بيئة الإنتاج.
يتم التحكم في ربط الرموز فقط عبر مفتاح global UnsafeMode — يكون مفعلاً افتراضيًا (UnsafeMode = false) وينطبق على كل جلسة. لا يوجد خيار إلغاء per-document؛ ضبط 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عندما يغادر المستخدم المستند — سيفيد ذلك الذاكرة والأمان معًا. - لا تُسجِّل أو تشارك الرموز أبدًا؛ اعتبرها بيانات اعتماد قصيرة الأمد.
- هل تُقدِّم من تخزين مشترك؟ انتقل إلى تذاكر وصول موقعة بدلاً من قبول المستندات غير محمية.
هل كانت هذه الصفحة مفيدة؟