الجلسات والأمان

جلسات المستند والتحكم في الوصول

رمز 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 مع طلبات الصفحات. إعدادات عبر الأصل التي تزيل ملفات تعريف الارتباط (أو عميل API بدون حاوية ملفات تعريف الارتباط) سيفشل في الفحص — وهذا يعني أن الميزة تعمل، وليس خطأ.
  • options.UnsafeMode = true يعطل الربط تمامًا. وهو موجود لسيناريوهات مُتحكم فيها (مثل التقديم من خادم إلى خادم)؛ اتركه false في بيئة الإنتاج.

يتم التحكم في ربط الرموز فقط عبر مفتاح global UnsafeMode — يكون مفعَّلًا افتراضيًا (UnsafeMode = false) وينطبق على كل جلسة. لا يوجد خيار إلغاء per-document؛ ضبط UnsafeMode = true يعطل الربط عالميًا.

أذونات الوصول والمستخدمين المصادق عليهم

عند كون UnsafeMode هو false، يضيف UseDoconut() تلقائيًا DocumentAccessMiddleware قبل وسيط الصفحة. لا تقم بتسجيله مرة ثانية. عندما يحمل الطلب رمزًا، يبحث عن إذن الوصول المسجل عند فتح المستند ويصادق فقط إذا تحققت جميع الشروط التالية:

  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() وسيط الوصول وتُعطل أيضًا فحص العلامة الأساسي.

إلغاء

CloseDocument(token) لا يحرّر الذاكرة فقط — بل يزيل أيضًا علامة secure-{token} ويلغي إذن الوصول، لذا يصبح الرمز المغلق غير صالح على كلا طبقتي الأمان فورًا.

قائمة التحقق للإنتاج

  • احتفظ بـ UnsafeMode = false (الافتراضي) — هذا المفتاح العالمي هو ما يربط الرموز بالجلسات.
  • سجِّل AddDistributedMemoryCache() (تطبيقات MVC و Razor Pages لديها بالفعل) و AddSession()، واستدعِ app.UseSession() قبل فرع وسيط Doconut.
  • تأكد من أن سياسة ملف تعريف الارتباط للجلسة تسمح لطلبات الواجهة بحمل الملف (SameSite، HTTPS).
  • استخدم CloseDocument عندما يغادر المستخدم المستند — سيفيد ذلك الذاكرة والأمان.
  • لا تُسجِّل أو تُشارك الرموز أبدًا؛ اعتبرها بيانات اعتماد قصيرة العمر.

هل كانت هذه الصفحة مفيدة؟