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:
- penampil format yang dimuat (instansi mesin dokumen yang memuat dokumen yang telah diurai),
- status per halaman — rotasi, pembalikan, dan data anotasi yang diterapkan pengguna di widget,
- indeks pencarian opsional, dibangun secara malas pada pencarian pertama (atau dimuat dari file
.srhyang telah dibangun sebelumnya ketika halaman disajikan dari penyimpanan bersama), - tanda air sesi dari
DocOptions.Watermark.
Umur Sesi
Sesi kedaluwarsa pada jendela geser: DocOptions.TimeOut menit (default 60), direset oleh setiap permintaan yang menyajikan token. Ketika sebuah sesi diusir — karena kedaluwarsa atau oleh CloseDocument(token) — callback pengusiran tersebut membuang mesin dokumen dan segera membebaskan memori yang terkait.
// Sesi singkat untuk pratinjau satu kali
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 sesi ASP.NET dari permintaan HTTP yang membukanya, dengan menulis penanda secure-{token} ke dalam sesi tersebut. Middleware Doconut kemudian menolak menyajikan 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 AddSession() + app.UseSession() sebelum cabang Doconut. Dua konsekuensi praktis:
- Klien harus mengirim cookie sesi ASP.NET bersama permintaan halaman. Pengaturan lintas asal yang menghapus cookie (atau klien API tanpa tempat penyimpanan cookie) akan gagal pada pemeriksaan — itu merupakan fitur yang berfungsi, bukan bug.
options.UnsafeMode = truemenonaktifkan pengikatan sepenuhnya. Ini ada untuk skenario terkontrol (mis. rendering server-ke-server); biarkan tetapfalsedalam produksi.
Pengikatan token dikendalikan sepenuhnya oleh saklar global UnsafeMode ini — secara default aktif (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 berada dalam keadaan 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:
- ada hak akses untuk token tersebut,
- belum kedaluwarsa (masa berlaku hak =
TimeOutdokumen), - ID sesi ASP.NET yang meminta cocok dengan yang membuka dokumen,
- jika pembuka terautentikasi, klaim
NameIdentifierpengguna yang meminta juga cocok.
Kegagalan mengembalikan 403 — sebagai gambar error PNG untuk permintaan halaman/thumbnail, sebagai teks biasa untuk yang lain. Pesan dan kunci kueri token berasal 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 gagal tertutup dengan HTTP 500: ASP.NET Session is required for Doconut document security.
builder.Services.Configure<Doconut.Security.DocumentSecurityOptions>(options =>
{
options.TokenQueryKey = "token";
options.UnauthorizedMessage = "You Are Not Authorized To View This Page.";
});Middleware halaman inti kemudian memverifikasi penanda sesi secure-{token} sebelum menyajikan dokumen. Dengan UnsafeMode = true, UseDoconut() melewati middleware akses dan pemeriksaan penanda inti juga dinonaktifkan.
Keamanan lintas beberapa node
Token yang terikat sesi mengasumsikan bahwa node yang menyajikan halaman juga melihat permintaan yang membuka dokumen. Asumsi tersebut tidak berlaku ketika beberapa node menyajikan dokumen yang sama dari penyimpanan bersama: permintaan halaman dapat mendarat pada node yang tidak pernah melihat pembukaan, dan pemeriksaan per-sesi menolaknya.
Jawabannya bukan meninggalkan dokumen tidak terlindungi. Gunakan tiket akses bertanda tangan melalui AddDoconutDistributedDocumentSecurity(...), yang menggantikan pemeriksaan sesi dengan kredensial yang dapat diverifikasi secara independen oleh setiap node. Pengaturan lengkap ada pada Penyebaran Terdistribusi.
Pencabutan
CloseDocument(token) tidak hanya membebaskan memori — ia juga menghapus penanda secure-{token} dan mencabut hak akses, sehingga token yang ditutup menjadi tidak aktif pada kedua lapisan keamanan secara langsung.
Daftar Periksa untuk Produksi
- Pertahankan
UnsafeMode = false(default) pada satu node — saklar global ini yang mengikat token ke sesi. - Daftarkan
AddDistributedMemoryCache()(aplikasi MVC dan Razor Pages sudah memilikinya) danAddSession(), serta panggilapp.UseSession()sebelum cabang middleware Doconut. - Pastikan kebijakan cookie sesi Anda memungkinkan permintaan widget membawa cookie (
SameSite, HTTPS). - Gunakan
CloseDocumentketika pengguna meninggalkan dokumen — memori dan keamanan keduanya diuntungkan. - Jangan pernah mencatat atau membagikan token; perlakukan mereka sebagai kredensial berumur pendek.
- Menyajikan dari penyimpanan bersama? Beralih ke tiket akses bertanda tangan daripada menerima dokumen yang tidak terlindungi.
Apakah halaman ini membantu?