เซสชันและความปลอดภัย

เซสชันเอกสารและการควบคุมการเข้าถึง

โทเคน Doconut มีพลังมาก: ผู้ใดที่นำเสนอมันสามารถขอรับทุกหน้าของเอกสารได้หากไม่ได้ผูกกับเซสชันที่เปิดเอกสาร หน้านี้อธิบายว่าเซสชันเก็บอะไรไว้, อายุการใช้งานเป็นเท่าไร, และการตรวจสอบที่ UseDoconut() เปิดใช้งานโดยค่าเริ่มต้น.

สิ่งที่เซสชันเอกสารเก็บไว้

แต่ละการเรียก OpenDocumentAsync ที่สำเร็จจะสร้างเซสชันหนึ่งรายการใน IMemoryCache:

  • loaded format viewer – อินสแตนซ์เอนจินเอกสารที่โหลดรูปแบบและเก็บเอกสารที่แปลงแล้ว,
  • per-page state – การหมุน, การพลิก, และข้อมูลคำอธิบายที่ผู้ใช้ใส่ในวิดเจ็ตสำหรับแต่ละหน้า,
  • search index (เป็นตัวเลือก) – ดัชนีการค้นหาที่สร้างแบบ lazy ครั้งแรกที่ทำการค้นหา (หรือโหลดจากไฟล์ .srh ที่สร้างไว้ล่วงหน้าในสภาพแวดล้อมเว็บฟาร์ม),
  • watermark ของเซสชันจาก DocOptions.Watermark.

อายุการใช้งาน

เซสชันจะหมดอายุตาม sliding window: DocOptions.TimeOut นาที (ค่าเริ่มต้น 60) และจะรีเซ็ตทุกครั้งที่มีคำขอที่นำเสนอโทเคน เมื่อเซสชันถูกขับออก — ไม่ว่าจะโดยการหมดอายุหรือโดย CloseDocument(token) — คอลแบ็กการขับออกจะทำลายเอนจินเอกสารและคืนหน่วยความจำที่เกี่ยวข้องทันที.

csharp
// เซสชันสั้น ๆ สำหรับการพรีวิวครั้งเดียว
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

คำขอที่ใช้โทเคนที่หมดอายุจะได้รับภาพข้อผิดพลาดที่แสดงข้อความ ไม่พบเซสชันเอกสาร. โปรดเปิดเอกสารใหม่. — ลูกค้าต้องเปิดเอกสารใหม่เพื่อรับโทเคนใหม่ที่สดใหม่.

การผูกโทเคนในตัว

เมื่อกำหนด UnsafeMode = false (ค่าเริ่มต้น) OpenDocumentAsync จะผูกโทเคนใหม่กับ ASP.NET session ของ HTTP request ที่เปิดเอกสารโดยการเขียนเครื่องหมาย secure-{token} ลงในเซสชันนั้น Middleware ของ Doconut จะปฏิเสธการให้บริการหน้าใด ๆ กับเซสชันเบราว์เซอร์อื่น:

  • เบราว์เซอร์หรือเซสชันที่ต่างกันนำเสนอโทเคนที่ถูกขโมย → ภาพข้อผิดพลาด คุณไม่ได้รับอนุญาตให้ดูหน้านี้.
  • Middleware เซสชันยังไม่ได้กำหนดค่า → HTTP 500 Middleware เซสชันยังไม่ได้กำหนดค่า. เรียก UseSession() ก่อน UseDoconut().

นี่คือเหตุผลที่ Quick Start บังคับให้ใช้ AddSession() + app.UseSession() ก่อนสาขา Middleware ของ Doconut มีผลลัพธ์เชิงปฏิบัติสองประการ:

  • ลูกค้าต้องส่ง session cookie ของ ASP.NET ไปพร้อมกับคำขอหน้า การตั้งค่า cross‑origin ที่ลบคุกกี้ (หรือไคลเอนต์ API ที่ไม่มี cookie jar) จะทำให้การตรวจสอบล้มเหลว — นั่นคือฟีเจอร์ทำงานตามที่ออกแบบ, ไม่ใช่บั๊ก.
  • การตั้งค่า options.UnsafeMode = true จะปิดการผูกโทเคนโดยสมบูรณ์ มีไว้สำหรับสถานการณ์ที่ควบคุมได้ (เช่น การเรนเดอร์ server‑to‑server); ควรตั้งเป็น false ในการผลิต.

การผูกโทเคนถูกควบคุมโดยสวิตช์ระดับโลก UnsafeMode เพียงอย่างเดียว — เปิดตามค่าเริ่มต้น (UnsafeMode = false) และใช้กับทุกเซสชัน ไม่มีการยกเว้นตามเอกสาร; การตั้งค่า UnsafeMode = true จะปิดการผูกโทเคนทั่วทั้งระบบ.

การให้สิทธิ์เข้าถึงและผู้ใช้ที่ผ่านการรับรอง

เมื่อ UnsafeMode เป็น false UseDoconut() จะใส่ DocumentAccessMiddleware เข้าไปโดยอัตโนมัติก่อน Middleware ของหน้า อย่าลงทะเบียนซ้ำ เมื่อคำขอมีโทเคน มันจะค้นหา access grant ที่บันทึกไว้เมื่อเปิดเอกสารและจะให้สิทธิ์เฉพาะเมื่อเงื่อนไขต่อไปนี้เป็นจริงทั้งหมด:

  1. มี grant สำหรับโทเคนนั้นอยู่,
  2. ยังไม่หมดอายุ (อายุของ grant เท่ากับ TimeOut ของเอกสาร),
  3. ID ของ ASP.NET session ที่ส่งคำขอเท่ากับ ID ของเซสชันที่เปิดเอกสาร,
  4. หากผู้เปิดเอกสารผ่านการรับรองแล้ว claim NameIdentifier ของผู้ใช้ที่ส่งคำขอตรงกันด้วย.

หากตรวจสอบไม่ผ่านจะคืนค่า 403 — เป็นภาพ PNG ข้อผิดพลาดสำหรับคำขอหน้า/thumbnail, หรือเป็นข้อความธรรมดาสำหรับกรณีอื่น ๆ ข้อความและคีย์ query ของโทเคนมาจาก DocumentSecurityOptions (TokenQueryKey ค่าเริ่มต้น "token"; UnauthorizedMessage ค่าเริ่มต้น "คุณไม่ได้รับอนุญาตให้ดูหน้านี้."). กำหนดค่าตัวเลือกเหล่านี้ผ่าน DI ของ ASP.NET Core ก่อนสร้างแอป หากสถานะเซสชันไม่พร้อมใช้งาน Middleware จะปิดการทำงานด้วย HTTP 500: ต้องมี ASP.NET Session เพื่อความปลอดภัยของเอกสาร Doconut.

csharp
builder.Services.Configure<Doconut.Security.DocumentSecurityOptions>(options =>
{
    options.TokenQueryKey = "token";
    options.UnauthorizedMessage = "คุณไม่ได้รับอนุญาตให้ดูหน้านี้.";
});

Middleware หลักของหน้า จะตรวจสอบเครื่องหมาย secure-{token} ในเซสชันก่อนให้บริการเอกสาร หากตั้งค่า UnsafeMode = true UseDoconut() จะข้าม Middleware การเข้าถึงและการตรวจสอบเครื่องหมายหลักก็ถูกปิดด้วยเช่นกัน.

การเพิกถอน

การเรียก CloseDocument(token) ไม่ได้เพียงแค่คืนหน่วยความจำ — มันยังลบเครื่องหมาย secure-{token} และเพิกถอน access grant ด้วย ทำให้โทเคนที่ปิดแล้วไม่มีผลทั้งสองชั้นความปลอดภัยทันที.

รายการตรวจสอบสำหรับการผลิต

  • รักษา UnsafeMode = false (ค่าเริ่มต้น) — สวิตช์ระดับโลกนี้เป็นตัวผูกโทเคนกับเซสชัน.
  • ลงทะเบียน AddSession() และเรียก app.UseSession() ก่อนสาขา Middleware ของ Doconut.
  • ตรวจสอบให้แน่ใจว่า policy ของคุกกี้เซสชันอนุญาตให้คำขอของวิดเจ็ตส่งคุกกี้ (SameSite, HTTPS).
  • ใช้ CloseDocument เมื่อผู้ใช้ออกจากเอกสาร — ทั้งหน่วยความจำและความปลอดภัยจะได้ประโยชน์.
  • อย่าเก็บบันทึกหรือแชร์โทเคน; ปฏิบัติกับมันเหมือนข้อมูลประจำตัวที่มีอายุสั้น.

หน้านี้เป็นประโยชน์หรือไม่?