Sesi & Keamanan

Sesi dokumen dan kontrol akses

A Doconut token mengidentifikasi dokumen yang terbuka. Jika ada permintaan yang membawa token tersebut dilayani, siapa pun yang mendapatkannya dapat membaca setiap halaman. Halaman ini menjelaskan apa yang disimpan dalam sesi dokumen, berapa lama sesi tersebut hidup, dan bagaimana DocImage.axd memutuskan siapa yang dapat melihat halamannya — pada satu server dan di web farm.

Apa yang disimpan dalam sesi dokumen

Setiap OpenDocumentAsync yang berhasil membuat satu sesi, disimpan dalam memori:

  • penampil format yang dimuat — instance mesin yang menyimpan dokumen yang diparsing,
  • status per‑halaman — rotasi, flip, dan data anotasi yang diterapkan pengguna di widget,
  • indeks pencarian opsional, dibangun pada pencarian pertama (atau dimuat dari berkas .srh yang sudah dibangun),
  • watermark sesi dari DocOptions.Watermark.

Masa Hidup

Sesi berakhir pada jendela geser: DocOptions.TimeOut menit (bawaan 60), direset oleh setiap permintaan yang menyertakan token. Ketika sesi berakhir — karena kedaluwarsa atau oleh CloseDocument(token) — mesin dokumen dilepaskan dan memorinya dibebaskan segera.

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. Halaman harus membuka dokumen kembali untuk mendapatkan token baru. Pada satu server, daur ulang application pool juga mengakhiri semua sesi.

Halaman hanya dilayani ke sesi yang membukanya

Dengan UnsafeMode = false — bawaan — membuka dokumen memberikan akses ke sesi ASP.NET dari permintaan yang membukanya, dengan menulis entri secure-{token} ke dalam sesi tersebut. DocImage.axd memerlukan status sesi itu sendiri, dan hanya melayani halaman ketika sesi yang meminta memiliki entri tersebut. Browser lain yang menyajikan token yang sama akan mendapatkan gambar error yang menampilkan You Are Not Authorized To View This Page.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    // false (the default): DocImage.axd serves a page only to the ASP.NET session that opened
    // the document. The handler asks for session state itself; it only needs the site not to
    // turn session state off in Web.config.
    options.UnsafeMode = false;
});

Tiga konsekuensi praktis:

  • Endpoint pembukaan memerlukan session state. Kontroler MVC dan halaman Web Forms memilikinya secara default. IHttpHandler khusus tidak memilikinya kecuali mengimplementasikan System.Web.SessionState.IRequiresSessionState. Pembukaan yang berjalan tanpa sesi tidak memiliki apa‑apa untuk diberikan, sehingga penampil menampilkan "You Are Not Authorized To View This Page." pada setiap halaman.
  • Session state harus tetap aktif. <sessionState mode="Off" /> di Web.config menonaktifkan baik pemberian maupun pemeriksaan, sehingga setiap halaman ditolak.
  • Browser harus mengirim cookie sesi. Permintaan widget bersifat asal yang sama, sehingga secara otomatis membawa ASP.NET_SessionId. Klien tanpa cookie jar — skrip, panggilan server‑ke‑server, pengaturan cross‑origin yang menghapus cookie — akan ditolak. Itulah fitur yang berfungsi.

UnsafeMode = true mematikan pemeriksaan: setiap permintaan yang membawa token akan dilayani. Ini adalah saklar global untuk setiap dokumen, tanpa pengecualian per dokumen. Biarkan tetap false.

Pencabutan

CloseDocument(token) melakukan lebih dari sekadar membebaskan memori: ia menghapus entri secure-{token} dari sesi permintaan saat ini dan mencabut token, sehingga token yang ditutup langsung ditolak.

Web farm: tiket bertanda tangan

Di dalam farm, permintaan berikutnya dapat tiba di server yang belum pernah melihat dokumen, di proses pekerja yang berbeda, dengan sesi ASP.NET miliknya sendiri. Pemberian sesi tidak dapat mengikutinya. Mode terdistribusi menggantinya dengan tiket bertanda tangan yang terikat pada browser: setiap node berbagi satu penyimpanan untuk sesi dokumen dan satu kunci penandatanganan, dan DocImage.axd menerima permintaan ketika tiketnya valid untuk token tersebut, browser tersebut, dan — ketika pengguna sudah masuk — pengguna tersebut.

Pengaturan, identik pada setiap node:

csharp
// Global.asax.cs - Application_Start
Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,     // the ticket check only runs when this is false
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";  // a folder every node can reach
        d.SigningKey        = farmKey;                          // at least 32 bytes, the SAME on every node
    }));

Endpoint pembukaan kemudian mengikat tiket ke browser sebelum membuka, dan mengembalikan tiket bersama token:

  • atur DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(System.Web.HttpContext.Current, securityOptions) — yang mengeluarkan cookie doconut-client yang menjadi ikatan tiket — dan DocOptions.UserId = DoconutFarmBinding.ResolveUserId(System.Web.HttpContext.Current);
  • setelah OpenDocumentAsync, kembalikan viewer.AccessToken bersamaan dengan token;
  • di halaman, kirimkan keduanya ke widget: objViewer.View(token, access).

Doconut.MvcSample.WebFarm dalam paket contoh adalah node farm yang lengkap dan dapat dijalankan, dan panduan migrasi di sampingnya menjelaskan setiap langkah.

Simpan kunci penandatanganan di luar kontrol sumber: kunci tersebut menandatangani tiket dan mengenkripsi dokumen di penyimpanan bersama. Node dengan kunci yang berbeda menolak setiap tiket yang dikeluarkan oleh node lain.

Uji farm dengan browser nyata, atau skrip yang menyimpan cookie. Klien tanpa cookie doconut-client tidak dijawab dengan 401: ia menerima gambar error "not authorized" dengan status 200, sekitar 2 KB, sementara halaman nyata berukuran puluhan hingga ratusan kilobyte.

Daftar periksa produksi

  • Pertahankan UnsafeMode = false (bawaan).
  • Buka dokumen dari permintaan yang memiliki session state, dan jangan pernah mematikan session state.
  • Pastikan cookie sesi mencapai DocImage.axd (asal yang sama, HTTPS, kebijakan SameSite yang mengizinkannya).
  • Di farm, gunakan mode terdistribusi dengan satu kunci penandatanganan yang dibagikan oleh setiap node.
  • Panggil 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?