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

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

رمز 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 عندما يغادر المستخدم المستند — سيفيد ذلك الذاكرة والأمان.
  • لا تُسجِّل أو تُشارك الرموز أبدًا؛ اعتبرها بيانات اعتماد قصيرة الأمد.

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