جلسات و امنیت

جلسات سند و کنترل دسترسی

یک توکن 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 بگذارید.

بایندینگ توکن تنها توسط این سوئیچ جهانی 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 را نگه دارید (پیش‌فرض) — این سوئیچ جهانی همان چیزی است که توکن‌ها را به جلسات بایند می‌کند.
  • AddDistributedMemoryCache() را ثبت کنید (برنامه‌های MVC و Razor Pages از پیش آن را دارند) و AddSession()، و قبل از شاخهٔ میانی‌افزار Doconut، app.UseSession() را فراخوانی کنید.
  • اطمینان حاصل کنید سیاست کوکی جلسهٔ شما اجازه می‌دهد درخواست‌های ویجت کوکی را حمل کنند (SameSite، HTTPS).
  • وقتی کاربر سند را ترک می‌کند از CloseDocument استفاده کنید — هم حافظه و هم امنیت بهره می‌برند.
  • هرگز توکن‌ها را لاگ یا به اشتراک نگذارید؛ آنها را به‌عنوان اعتبارنامه‌های کوتاه‌مدت در نظر بگیرید.

آیا این صفحه مفید بود؟