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

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

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

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