Sesi & Keamanan

Sesi dokumen dan kontrol akses

Token Doconut sangat kuat: siapa pun yang menyajikannya dapat meminta setiap halaman dokumen jika tidak terikat pada sesi pembuka. Halaman ini menjelaskan apa yang disimpan dalam sesi, berapa lama sesi tersebut hidup, dan pemeriksaan yang diaktifkan secara default oleh UseDoconut().

Apa yang disimpan dalam sesi dokumen

Setiap OpenDocumentAsync yang berhasil membuat satu sesi di IMemoryCache:

  • loaded format viewer (instansi mesin dokumen yang memuat dokumen yang telah diparse),
  • per-page state — rotasi, flips, dan data anotasi yang diterapkan pengguna di widget,
  • search index opsional, dibangun secara malas pada pencarian pertama (atau dimuat dari file .srh yang sudah dibangun sebelumnya dalam skenario web‑farm),
  • watermark sesi dari DocOptions.Watermark.

Masa Hidup

Sesi berakhir pada sliding window: DocOptions.TimeOut menit (default 60), direset oleh setiap permintaan yang menyajikan token. Ketika sebuah sesi dihapus — karena kedaluwarsa atau oleh CloseDocument(token) — callback penghapusan sesi membuang mesin dokumen dan segera membebaskan memori yang terkait.

csharp
// A short-lived session for a one-shot preview
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

Permintaan dengan token yang kedaluwarsa akan mendapatkan gambar error yang menampilkan Document session not found. Please re-open document. — klien harus membuka kembali untuk memperoleh token baru.

Pengikatan token bawaan

Dengan UnsafeMode = false (default), OpenDocumentAsync mengikat token baru ke ASP.NET session dari permintaan HTTP yang membukanya, dengan menulis penanda secure-{token} ke dalam sesi tersebut. Middleware Doconut kemudian menolak melayani halaman ke sesi peramban lain:

  • Peramban/sesi yang berbeda menyajikan token yang dicuri → gambar error You Are Not Authorized To View This Page.
  • Middleware sesi tidak terdaftar → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

Inilah mengapa Quick Start menekankan penggunaan AddSession() + app.UseSession() sebelum cabang Doconut. Dua konsekuensi praktis:

  • Klien harus mengirim session cookie ASP.NET bersama permintaan halaman. Pengaturan cross‑origin yang menghapus cookie (atau klien API tanpa cookie jar) akan gagal pada pemeriksaan — itu adalah fitur yang berfungsi, bukan bug.
  • options.UnsafeMode = true menonaktifkan pengikatan sepenuhnya. Ini ada untuk skenario terkontrol (mis. rendering server‑ke‑server); biarkan false di produksi.

Pengikatan token dikendalikan sepenuhnya oleh saklar global UnsafeMode ini — aktif secara default (UnsafeMode = false) dan berlaku untuk setiap sesi. Tidak ada opsi opt‑out per dokumen; mengatur UnsafeMode = true menonaktifkan pengikatan secara global.

Hak akses dan pengguna terautentikasi

Ketika UnsafeMode adalah false, UseDoconut() menyisipkan DocumentAccessMiddleware secara otomatis sebelum middleware halaman. Jangan daftarkan lagi. Ketika sebuah permintaan membawa token, ia mencari access grant yang dicatat saat dokumen dibuka dan mengotorisasi hanya jika semua hal berikut terpenuhi:

  1. ada grant untuk token tersebut,
  2. belum kedaluwarsa (masa hidup grant = TimeOut dokumen),
  3. ID sesi ASP.NET yang meminta cocok dengan yang membuka dokumen,
  4. jika pembuka terautentikasi, klaim NameIdentifier pengguna yang meminta juga cocok.

Kegagalan mengembalikan 403 — sebagai gambar error PNG untuk permintaan halaman/thumbnail, atau sebagai teks biasa lainnya. Pesan dan kunci kueri token diambil dari DocumentSecurityOptions (TokenQueryKey, default "token"; UnauthorizedMessage, default "You Are Not Authorized To View This Page."). Konfigurasikan opsi tersebut melalui ASP.NET Core DI sebelum membangun aplikasi. Jika status sesi tidak tersedia, middleware akan menutup dengan 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.";
});

Middleware inti halaman kemudian memverifikasi penanda sesi secure-{token} sebelum menyajikan dokumen. Dengan UnsafeMode = true, UseDoconut() melewati middleware akses dan pemeriksaan penanda inti juga dinonaktifkan.

Pencabutan

CloseDocument(token) tidak hanya membebaskan memori — ia juga menghapus penanda secure-{token} dan mencabut access grant, sehingga token yang ditutup langsung tidak berlaku pada kedua lapisan keamanan.

Daftar Periksa untuk Produksi

  • Pertahankan UnsafeMode = false (default) — saklar global ini yang mengikat token ke sesi.
  • Daftarkan AddSession() dan panggil app.UseSession() sebelum cabang middleware Doconut.
  • Pastikan kebijakan cookie sesi Anda memungkinkan permintaan widget membawa cookie (SameSite, HTTPS).
  • Gunakan CloseDocument ketika pengguna meninggalkan dokumen — memori dan keamanan keduanya diuntungkan.
  • Jangan pernah mencatat atau membagikan token; perlakukan mereka sebagai kredensial berumur pendek.

Apakah halaman ini membantu?