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

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

رمز Doconut قوي: أي شخص يقدم هذا الرمز يمكنه طلب كل صفحات المستند إذا لم يكن مرتبطًا بجلسة الفتح. توضح هذه الصفحة ما تحتويه الجلسة، مدة بقاءها، والفحوصات التي يفعّلها UseDoconut() افتراضيًا.

ما الذي تحتفظ به جلسة المستند

كل استدعاء ناجح لـ OpenDocumentAsync ينشئ جلسة واحدة في IMemoryCache:

  • عارض الصيغة المحملة (مثيل محرك المستند الذي يحتفظ بالمستند المُحلل)،
  • حالة كل صفحة — الدوران، الانعكاسات، وبيانات التعليقات التي يضيفها المستخدم في الواجهة،
  • فهرس البحث الاختياري، يُبنى بشكل كسول عند أول بحث (أو يُحمَّل من ملف .srh مُسبق الإنشاء في سيناريوهات مزرعة الويب)،
  • علامة مائية الجلسة من DocOptions.Watermark.

مدة الجلسة

تنتهي صلاحية الجلسات وفق نافذة انزلاقية: DocOptions.TimeOut دقيقة (الافتراضي 60)؛ تُعاد الضبط عند كل طلب يقدم الرمز. عندما تُطرد الجلسة — إما بانتهاء المدة أو عبر CloseDocument(token) — يقوم رد النداء الخاص بالطرد بتحرير محرك المستند وتحرير الذاكرة المرتبطة فورًا.

csharp
// A short-lived session for a one-shot preview
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 قبل برنامج الوسيط الخاص بالصفحة. لا تُسجِّل هذا البرنامج مرة ثانية. عندما يحمل الطلب رمزًا، يبحث عن منح الوصول المسجلة عند فتح المستند ويُصرّح فقط إذا تحققت جميع الشروط التالية:

  1. وجود منح للوصول للرمز،
  2. لم تنتهِ صلاحيته (مدة المنح = TimeOut للمستند)،
  3. معرف جلسة ASP.NET للطلب يطابق الذي فتح المستند،
  4. إذا كان الفاتح مُصادقًا، فإن مطالبة NameIdentifier للمستخدم المتطلب تتطابق أيضًا.

تُعيد الفشل استجابة 403 — كصورة PNG للخطأ في طلبات الصفحات/الصورة المصغرة، كنص عادي في غير ذلك. الرسالة ومفتاح استعلام الرمز يُستمدان من DocumentSecurityOptions (TokenQueryKey، الافتراضي "token"؛ UnauthorizedMessage، الافتراضي "You Are Not Authorized To View This Page."). اضبط هذه الخيارات عبر DI الخاص بـ ASP.NET Core قبل بناء التطبيق. إذا لم تتوفر حالة الجلسة، يفشل برنامج الوسيط مغلقًا مع 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 (الإعداد الافتراضي) — هذا المفتاح العالمي هو ما يربط الرموز بالجلسات.
  • سجِّل AddSession() واستدعِ app.UseSession() قبل فرع برنامج الوسيط Doconut.
  • تأكد من أن سياسة ملف تعريف الارتباط للجلسة تسمح لطلبات الواجهة بحمل الملف (SameSite، HTTPS).
  • استخدم CloseDocument عندما يغادر المستخدم المستند — سيفيد ذلك الذاكرة والأمان.
  • لا تُسجِّل أو تشارك الرموز أبدًا؛ اعتبرها بيانات اعتماد قصيرة العمر.

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