Oturumlar ve Güvenlik

Belge oturumları ve erişim kontrolü

A Doconut token güçlüdür: onu sunan herkes belgeyi açan oturuma bağlanmamış olsaydı belgenin her sayfasını isteyebilirdi. Bu sayfa bir oturumun ne tuttuğunu, ne kadar süre yaşadığını ve UseDoconut() tarafından varsayılan olarak etkinleştirilen kontrolleri açıklar.

Bir belge oturumu ne tutar

  • yüklenmiş format görüntüleyicisi (ayrıştırılmış belgeyi tutan belge motoru örneği),
  • sayfa başına durum — döndürme, çevirme ve kullanıcının widget'ta uyguladığı açıklama verileri,
  • isteğe bağlı arama dizini, ilk aramada tembelce oluşturulur (veya sayfalar paylaşılan depolamadan sunulduğunda önceden oluşturulmuş bir .srh dosyasından yüklenir),
  • oturum filigranı DocOptions.Watermark'tan.

Ömür

Oturumlar kaydırmalı bir pencere içinde sona erer: DocOptions.TimeOut dakika (varsayılan 60), token sunan her istek tarafından sıfırlanır. Bir oturum süresi dolduğunda — zaman aşımıyla ya da CloseDocument(token) ile — onun kaldırma geri çağrısı belge motorunu serbest bırakır ve ilişkili belleği hemen boşaltır.

csharp
// Tek seferlik önizleme için kısa ömürlü bir oturum
var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

Süresi dolmuş bir token ile yapılan istek, Document session not found. Please re-open document. metnini gösteren bir hata resmi alır — istemcinin yeni bir token elde etmek için belgeyi yeniden açması gerekir.

Yerleşik token bağlama

UnsafeMode = false (varsayılan) olduğunda, OpenDocumentAsync yeni token'ı belgeyi açan HTTP isteğinin ASP.NET oturumuna bağlar; bu oturuma bir secure-{token} işareti yazar. Doconut ara katmanı daha sonra bu işarete sahip olmayan başka bir tarayıcı oturumuna sayfa sunmayı reddeder:

  • Çalınmış bir token sunan farklı tarayıcı/oturum → hata resmi You Are Not Authorized To View This Page.
  • Oturum ara katmanı kaydedilmemiş → HTTP 500 Session middleware not configured. Call UseSession() before UseDoconut().

Bu nedenle Hızlı Başlangıç, Doconut dalından önce AddSession() + app.UseSession() kullanılmasını zorunlu kılar. İki pratik sonuç:

  • İstemci, sayfa isteklerinde ASP.NET oturum çerezini göndermelidir. Çerezleri temizleyen çapraz‑origin yapılandırmaları (veya çerez deposu olmayan bir API istemcisi) kontrolü geçemez — bu bir hata değil, beklenen bir güvenlik davranışıdır.
  • options.UnsafeMode = true bağlamayı tamamen devre dışı bırakır. Bu yalnızca kontrollü senaryolar içindir; üretimde tek düğümde false bırakılmalıdır.

Not: Önceki .NET Standard kütüphanesi bu özelliği UnSafeMode olarak adlandırıyordu ve ara katmana geçirilirdi; burada adı UnsafeMode ve yalnızca AddDoconut() içinde bir kez ayarlanır.

Token bağlama yalnızca bu küresel UnsafeMode anahtarıyla kontrol edilir — varsayılan olarak açıktır (UnsafeMode = false) ve her oturuma uygulanır. Belge bazında bir dışlama seçeneği yoktur; UnsafeMode = true ayarı bağlamayı tüm sistemde kapatır.

Erişim izinleri ve kimlik doğrulamalı kullanıcılar

UnsafeMode = false olduğunda, UseDoconut() belge‑erişim ara katmanını sayfa ara katmanından önce otomatik olarak ekler. İkinci kez kaydetmeyin. Bir istek bir token taşıdığında, belge açıldığında kaydedilen erişim iznini arar ve yalnızca aşağıdaki koşullar sağlandığında yetkilendirir:

  1. token için bir izin mevcut,
  2. izin süresi dolmamış (izin ömrü belgenin TimeOut değerine eşittir),
  3. isteği yapan ASP.NET oturum kimliği belgeyi açan oturum kimliğiyle aynı,
  4. belgeyi açan kullanıcı kimliği doğrulanmışsa, isteği yapan kullanıcının NameIdentifier bildirimi de eşleşir.

Başarısızlıklar 403 döndürür — sayfa/küçük resim isteklerinde PNG hata resmi, diğer durumlarda düz metin. Mesaj ve token sorgu anahtarı DocumentSecurityOptions'tan gelir (TokenQueryKey, varsayılan "token"; UnauthorizedMessage, varsayılan "You Are Not Authorized To View This Page."). Bu seçenekleri uygulamayı oluştururken ASP.NET Core DI üzerinden yapılandırın. Oturum durumu yoksa ara katman HTTP 500 ile kapanır: 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.";
});

Temel sayfa ara katmanı, belgeyi sunmadan önce secure-{token} oturum işaretini doğrular. UnsafeMode = true olduğunda, UseDoconut() erişim ara katmanını atlar ve temel işaret kontrolü de devre dışı bırakılır.

Birden fazla düğümde güvenlik

Oturuma bağlı token'lar, bir sayfayı sunan düğümün belgeyi açan isteği de görmüş olduğunu varsayar. Bu varsayım, aynı belgeler paylaşılan depolamadan birden çok düğüm tarafından sunulduğunda geçerli değildir: bir sayfa isteği, belgeyi hiç açmamış bir düğüme gelebilir ve oturum kontrolü isteği reddeder.

Cevap, belgeleri korumasız bırakmak değildir. AddDoconutDistributedDocumentSecurity(...) aracılığıyla imzalı erişim biletleri kullanın; bu, oturum kontrolünü her düğümün bağımsız olarak doğrulayabileceği bir kimlik bilgisiyle değiştirir. Tam düzenleme Dağıtılmış Dağıtımlar sayfasında açıklanmıştır.

İptal

CloseDocument(token) yalnızca belleği serbest bırakmaz — aynı zamanda secure-{token} işaretini kaldırır ve erişim iznini iptal eder; böylece kapatılan token iki güvenlik katmanında da anında geçersiz olur.

Üretim için Kontrol Listesi

  • Tek bir düğümde UnsafeMode = false (varsayılan) tutun — bu küresel anahtar token'ları oturuma bağlar.
  • AddDistributedMemoryCache() (MVC ve Razor Pages uygulamaları zaten bunu içerir) ve AddSession() kaydedin, ardından Doconut ara katmanı dalından önce app.UseSession() çağırın.
  • Oturum çerezinizin politikası, widget isteklerinin çerezi (SameSite, HTTPS) taşımasına izin versin.
  • Kullanıcı belgeyi terk ettiğinde CloseDocument kullanın — hem bellek hem de güvenlik fayda sağlar.
  • Token'ları asla loglamayın veya paylaşmayın; bunları kısa ömürlü kimlik bilgileri gibi davranın.
  • Paylaşılan depolamadan mı sunuyorsunuz? Korunmasız belgeler kabul etmek yerine imzalı erişim biletlerine geçin.

Bu sayfa yardımcı oldu mu?