Sesi & Keamanan

Sesi dokumen dan kontrol akses

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

Apa yang disimpan dalam sesi dokumen

Setiap OpenDocumentAsync yang berhasil membuat satu sesi di IMemoryCache:

  • penampil format yang dimuat (instance mesin dokumen yang menyimpan dokumen yang telah diparse),
  • status per halaman — rotasi, flip, dan data anotasi yang diterapkan pengguna di widget,
  • indeks pencarian opsional, dibangun secara malas pada pencarian pertama (atau dimuat dari file .srh yang telah dibangun sebelumnya dalam skenario web‑farm),
  • watermark sesi dari DocOptions.Watermark.

Masa Hidup

Sesi berakhir berdasarkan jendela geser: DocOptions.TimeOut menit (bawaan 60), yang 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
// Sesi singkat untuk pratinjau satu kali
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

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

Pengikatan token bawaan

Dengan UnsafeMode = false (bawaan), OpenDocumentAsync mengikat token baru ke sesi ASP.NET 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 middleware Doconut. Dua konsekuensi praktis:

  • Klien harus mengirim cookie sesi ASP.NET bersama setiap permintaan halaman. Pengaturan lintas asal yang menghapus cookie (atau klien API tanpa penyimpanan cookie) akan gagal pada pemeriksaan — itu adalah fitur yang berfungsi, bukan bug.
  • options.UnsafeMode = true menonaktifkan pengikatan sepenuhnya. Fitur ini ada untuk skenario terkendali (mis. rendering server‑to‑server); biarkan false dalam produksi.

Pengikatan token dikendalikan sepenuhnya oleh saklar global UnsafeMode ini — saklar ini aktif secara bawaan (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 bernilai false, UseDoconut() secara otomatis menyisipkan DocumentAccessMiddleware sebelum middleware halaman. Jangan daftarkan kembali middleware ini. Ketika sebuah permintaan membawa token, middleware mencari hak akses yang dicatat saat dokumen dibuka dan mengotorisasi hanya bila semua kondisi berikut terpenuhi:

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

Jika gagal, server mengembalikan 403 — sebagai gambar PNG error untuk permintaan halaman/thumbnail, atau sebagai teks biasa untuk permintaan lain. Pesan dan kunci kueri token diambil dari DocumentSecurityOptions (TokenQueryKey, bawaan "token"; UnauthorizedMessage, bawaan "You Are Not Authorized To View This Page."). Konfigurasikan opsi‑opsi ini melalui DI ASP.NET Core sebelum membangun aplikasi. Jika status sesi tidak tersedia, middleware 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 melayani 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 hak akses, sehingga token yang ditutup menjadi tidak berlaku pada kedua lapisan keamanan secara langsung.

Daftar Periksa untuk produksi

  • Pertahankan UnsafeMode = false (bawaan) — saklar global ini yang mengikat token ke sesi.
  • Daftarkan AddDistributedMemoryCache() (aplikasi MVC dan Razor Pages biasanya sudah memilikinya) serta AddSession(), dan panggil app.UseSession() sebelum cabang middleware Doconut.
  • Pastikan kebijakan cookie sesi Anda memperbolehkan widget mengirim cookie (SameSite, HTTPS).
  • Gunakan CloseDocument ketika pengguna meninggalkan dokumen — memori dan keamanan keduanya akan terbantu.
  • Jangan pernah mencatat atau membagikan token; perlakukan mereka sebagai kredensial berumur pendek.

Apakah halaman ini membantu?