جلسات و امنیت

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

یک توکن Doconut قدرتمند است: هر کسی که آن را ارائه دهد می‌تواند هر صفحه‌ای از سند را درخواست کند اگر به جلسه باز کردن بایند نشده باشد. این صفحه توضیح می‌دهد یک جلسه چه چیزی نگه می‌دارد، چه مدت زنده می‌ماند و چه بررسی‌هایی را UseDoconut() به‌طور پیش‌فرض فعال می‌کند.

آنچه یک جلسه سند نگه می‌دارد

هر OpenDocumentAsync موفق یک جلسه در IMemoryCache ایجاد می‌کند:

  • نمایشگر فرمت بارگذاری‌شده (نمونهٔ موتور سند که سند تجزیه‌شده را نگه می‌دارد)،
  • وضعیت صفحه به‌صورت per-page — چرخش، وارونه‌سازی و داده‌های حاشیه‌نویسی که کاربر در ویجت اعمال می‌کند،
  • نمایه جستجوی اختیاری، که به‌صورت تنبل در اولین جستجو ساخته می‌شود (یا از یک فایل .srh پیش‌ساخته در سناریوهای وب‌فارم بارگذاری می‌شود)،
  • واترمارک جلسه از DocOptions.Watermark.

طول عمر

جلسات بر پایهٔ پنجره لغزشی منقضی می‌شوند: DocOptions.TimeOut دقیقه (به‌طور پیش‌فرض ۶۰) که با هر درخواست که توکن را ارائه می‌دهد، بازنشانی می‌شود. وقتی یک جلسه تخلیه می‌شود — به‌دلیل انقضا یا 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().

به همین دلیل Quick Start بر AddSession() + app.UseSession() قبل از شاخهٔ Doconut تأکید دارد. دو پیامد عملی:

  • مشتری باید کوکی جلسه ASP.NET را همراه با درخواست‌های صفحه ارسال کند. تنظیمات کراس‑اورین که کوکی‌ها را حذف می‌کنند (یا یک کلاینت API بدون جعبهٔ کوکی) بررسی را شکست می‌دهند — این به‌عنوان ویژگی کار می‌کند، نه یک باگ.
  • options.UnsafeMode = true بایندینگ را به‌طور کامل غیرفعال می‌کند. این گزینه برای سناریوهای کنترل‌شده (مثلاً رندرینگ سرور‑به‑سرور) وجود دارد؛ در محیط تولید آن را false نگه دارید.

بایندینگ توکن صرفاً توسط این سوئیچ سراسری 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."). این گزینه‌ها را قبل از ساخت برنامه از طریق 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 استفاده کنید — هم حافظه و هم امنیت بهره‌مند می‌شوند.
  • هرگز توکن‌ها را لاگ یا به اشتراک نگذارید؛ آن‌ها را به‌عنوان اعتبارنامه‌های کوتاه‌مدت در نظر بگیرید.

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