جلسات و امنیت

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

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

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