MSAL.js'da önbelleğe alma

MSAL bir belirteç edindiğinde, gelecekteki kullanım için önbelleğe alır. MSAL, belirteçlerin kullanım sürelerini ve yenilenmesini sizin için yönetir. API, acquireTokenSilent() belirli bir hesabın önbellekten erişim belirteçlerini alır ve gerekirse bunları yeniler.

Önbellek depolama

Önbellek depolama konumunu MSAL örneği için kullanılan yapılandırma nesnesi aracılığıyla yapılandırabilirsiniz:

import { PublicClientApplication, BrowserCacheLocation } from "@azure/msal-browser";

const pca = new PublicClientApplication({
    auth: {
        clientId: "Enter_the_Application_Id_Here", // e.g. "00001111-aaaa-2222-bbbb-3333cccc4444" (guid)
        authority: "https://login.microsoftonline.com/Enter_the_Tenant_Info_Here", // e.g. "common" or your tenantId (guid),
        redirectUri: "/"
    },
    cache: {
       cacheLocation: BrowserCacheLocation.SessionStorage // "sessionStorage"
    }
});

Varsayılan olarak, MSAL tüm modern tarayıcılar tarafından desteklenen Web Depolama API'sini kullanarak IdP'den aldığı çeşitli kimlik doğrulama yapıtlarını tarayıcı depolama alanında depolar. Buna göre, MSAL iki kalıcı depolama yöntemi sunar: sessionStorage (varsayılan) ve localStorage. Ayrıca MSAL, önbelleği tarayıcı depolama alanında depolamayı geri çevirmenizi sağlayan bir seçenek sunar memoryStorage .

Önbellek Konumu Temizlendikten sonra Pencereler/sekmeler arasında paylaşılan Yeniden yönlendirme akışı destekleniyor
sessionStorage Pencere/sekme kapat Hayır Yes
localStorage tarayıcı kapatıldığında (kullanıcı “oturumumu açık tut” seçeneğini seçmediyse) Yes Yes
memoryStorage sayfa yenileme/gezinti Hayır Hayır

Note

Sırasıyla pencere/sekme kapatma veya sayfa yenileme/gezinti nedeniyle oturum ve bellek depolamada kimlik doğrulama durumu kaybolabilir ancak oturum tanımlama bilgisinin süresi dolmamış olduğu ve herhangi bir istem olmadan yeniden kimlik doğrulaması yapabilecekleri sürece kullanıcılar IdP ile etkin bir oturuma sahip olmaya devam edebilir.

Farklı depolama konumları arasındaki seçim, daha iyi kullanıcı deneyimi ile artırılmış güvenlik arasındaki dengeyi yansıtır. Yukarıdaki tabloda da belirtildiği gibi, yerel depolama mümkün olan en iyi kullanıcı deneyimiyle sonuçlanırken, tarayıcı depolamasında hiçbir hassas bilgi depolanmadığından bellek depolama en iyi güvenliği sağlar. Daha fazla bilgi için aşağıdaki güvenlik ve önbelleğe alınmış yapıtlar bölümüne bakın.

LocalStorage notları

v4'den başlayarak önbellek konumunu kullanıyorsanız localStorage , kullanıcı oturum açma sırasında "Oturumumu açık tut" seçeneğini belirlemediği sürece kimlik doğrulama yapıtları şifrelenir. Kullanılan şifreleme algoritması, anahtarı türetmek için HKDF kullanan AES-GCM'dir. Temel anahtar, adlı msal.cache.encryptionbir oturum tanımlama bilgisinde depolanır.

Tarayıcı örneği (sekme değil) kapatıldığında bu çerez otomatik olarak kaldırılır; böylece oturum sona erdikten sonra herhangi bir kimlik doğrulama verisinin şifresini çözmek imkânsız hâle gelir. Bu süresi dolan kimlik doğrulama yapıtları, MSAL'nin bir sonraki başlatılışında kaldırılır ve kullanıcının yeniden kimlik doğrulaması gerekebilir. Konum localStorage , tüm kullanıcılar için sekmeler arası önbellek kalıcılığı sağlar, ancak "Oturumumu açık tut" (KMSI) seçeneğini seçen kullanıcılar için yalnızca tarayıcı oturumlarında kalıcı olur.

Important

Bu şifrelemenin amacı, kimlik doğrulama verilerinin kalıcılığını azaltmaktır; ek güvenlik sağlamak değil. Kötü bir aktör tarayıcı depolamasına erişim kazanırsa, anahtara da erişebilir veya önbelleğe gerek kalmadan sizin yerinize belirteç isteme olanağına sahip olur. Uygulamanızın XSS saldırılarına karşı savunmasız olmadığından emin olmak sizin sorumluluğunuzdadır. Daha fazla bilgi için güvenlik bölümüne bakın.

Note

MSAL.js v4'te, geçici kimlik doğrulama öğeleri için çerez depolama kullanımdan kaldırılmıştır. Bu bölüm, MSAL.js v3 veya önceki sürümleri kullanan uygulamalar için korunur.

MSAL Browser, geçici kimlik doğrulama öğelerini depolamak için tanımlama bilgilerini kullanacak şekilde yapılandırılabilir. Bu seçenek, yeniden yönlendirme tabanlı oturum açma akışları sırasında yerel/oturum depolama alanını temizleyebilecek tarayıcıları (örneğin, özel modda Internet Explorer, Firefox) desteklemenizi sağlar. Bu seçenek belirtildiğinde belirteçlerin kendilerinin hala tarayıcıda veya bellek depolama alanında depolandığını unutmayın. Daha fazla bilgi için lütfen yapılandırmaya bakın.

Security

Uygulamanızın siteler arası betik (XSS) ve ilgili güvenlik açıkları olmadığı sürece oturum/yerel depolamanın güvenli olduğunu düşünüyoruz. Uygulamalarınızı XSS'ye karşı korumak için lütfen OWASP XSS Önleme Bilgi Sayfası'na bakın. Hala endişeleniyorsanız, bunun yerine seçeneğini kullanmanızı memoryStorage öneririz.

Önbelleğe alınmış artefaktlar

MSAL, iyi bir UX’i korurken verimli belirteç edinimini sağlamak için API çağrıları sonucunda oluşan çeşitli öğeleri önbelleğe alır. MSAL önbelleğindeki varlıkların özeti aşağıdadır:

  • Kalıcı artefaktlar (istekten sonra da varlığını sürdüren - ayrıca bkz: belirteç ömürleri)
    • erişim belirteçleri
    • kimlik belirteçleri
    • belirteçleri yenileme
    • accounts
  • Kısa ömürlü yapıtlar (istek ömrüyle sınırlıdır)
    • istek meta verileri (örn. durum, nonce, yetkili)
    • Hata
    • etkileşim durumu
  • Telemetri
    • önceki başarısız istek
    • performans verileri

Note

Geçici önbellek girdileri her zaman oturum depolama alanında veya bellekte depolanır. Oturum depolaması kullanılamıyorsa MSAL bellek depolama alanına geri döner.

Note

Yetkilendirme kodu yalnızca bellekte depolanır ve belirteç almak için kullanıldıktan sonra silinir.

temporaryCacheLocation geçersiz kılma

Note

yapılandırma temporaryCacheLocation seçeneği MSAL.js v4'te kullanım dışıdır. Bu bölüm, MSAL.js v3 veya önceki sürümleri kullanan uygulamalar için korunur.

Warning

temporaryCacheLocation geçersiz kılma işlemi, özellikle localStorage seçerken dikkatle yapılmalıdır. Birden fazla sekme/penceredeki etkileşim desteklenmez ve beklenmedik hatalar alabilirsiniz interaction_in_progress . Bu tam olarak desteklenen bir özellik değil, bir kaçış kapağıdır.

Yeni bir pencerede veya sekmede başarılı bir kimlik doğrulamasından sonra kullanıcının yeniden yönlendirildiği bir senaryoda varsayılan yapılandırmayla MSAL.js kullanırken, PKCE ile OAuth 2.0 Yetkilendirme Kodu akışı kesintiye uğrar. Bu durumda, kimlik doğrulama durumunun (kod doğrulayıcı ve sınama) depolandığı özgün pencere veya sekme kaybolur ve kimlik doğrulama akışı başarısız olur.

Bu senaryoyu ele almak için, temporaryCacheLocation yapılandırma özelliğini geçersiz kılarak MSAL'yi önbellek konumu olarak localStorage kullanacak şekilde yapılandırabilirsiniz. Bu, kod doğrulayıcının ve kod sorgusunun, birden çok sekme ve pencere arasında kalıcı olan tarayıcının localStorage içinde depolanmasını sağlar.

MSAL.js yükseltmeleri ve geri dönüşleri sırasında önbellek kalıcılığı

Bazen MSAL.js yeni gereksinimleri, özellikleri veya hata düzeltmelerini desteklemek için önbelleğe alınmış yapıtların şeklinde değişiklik yapması gerekir. Mümkün olduğunca sık, bu değişiklikler geriye dönük uyumlu bir şekilde yapılır, böylece bir uygulama yeni bir sürüme yükseltildiğinde veya eski bir sürüme geri döndüğünde, kullanıcının tarayıcısında bulunan önbelleğin hala kullanılabildiğinden emin olun. Ancak, bu her zaman mümkün değildir ve önbelleğin birden çok kopyasının eşzamanlı olarak mevcut olduğu bir duruma gelebilirsiniz, biri çalışan MSAL.js geçerli sürümü tarafından kullanılır ve diğeri yükseltmeden önce kullanılan sürüm tarafından yazılmıştır. Bu, gerekirse uygulamaların sorunsuzca geri alınabilmesi için yapılır. Yükseltmelerin büyük çoğunluğunda, MSAL.js sorunsuz bir yükseltme deneyimi için mevcut önbellekleri yeni biçime geçirir. v3'ten v4'e yükseltme gibi nadir durumlarda, güvenlik veya gizlilik gereksinimleri nedeniyle bu mümkün olmayabilir ve bu durum her zaman ana sürümde bir çarpmayla sonuçlanır.

Önbellekte hataya neden olan bir değişiklik yapıldığında, gerekirse geri alma işlemine izin vermek için eski önbellek varsayılan olarak 5 gün boyunca tutulur. Eski önbelleğin ne kadar süreyle tutulacağı, PublicClientApplication üzerindeki cacheRetentionDays önbellek yapılandırması kullanılarak yapılandırılabilir. Önbellek bu süre içinde etkin olarak kullanılmadıysa, MSAL.js bir sonraki başlatışında temizlenir. Ayrıca, geri almanız gerekmediğini düşünüyorsanız, eski önbelleğin yeni bir MSAL.jssürümüne yükselttikten sonra her zaman hemen kaldırılması gerektiğini belirtmek için bu değeri 0 ayarlayabilirsiniz. Buna karşılık, yükseltmeler için daha uzun bir dağıtım pencereniz varsa, bunu daha uzun bir değere ayarlamayı seçebilirsiniz.

Note

Erişim ve yenileme belirteçlerinin süresi dolduktan sonra, yapılandırılmış cacheRetentionDays belirteçlere henüz ulaşılmamış olsa bile kaldırılır. Tarayıcı depolama alanı depolama kotasına ulaşırsa, geçerli erişim belirteçleri de herhangi bir zamanda kaldırılabilir. Depolama kotalarına ulaşıldığında, erişim belirteçleri ilk giren ilk çıkar esasına göre kaldırılır; önce MSAL.js’nin önceki bir sürümü tarafından yazılan girdilerden başlanır, ardından MSAL.js’nin geçerli sürümü tarafından yazılan girdilere geçilir.

const config = {
    auth: {
        clientId: "<your-client-id>"
    },
    cache: {
        cacheLocation: "localStorage",
        cacheRetentionDays: 0 // Set this to the number of days you want old cache to be preserved in the event a rollback is needed (Default 5 days)
    }
}

const pca = new PublicClientApplication(config);
await pca.initialize();

Açıklamalar

  • Önbellekteki varlıkların doğrudan kullanımına bağlı iş mantığına sahip uygulamaların kullanılmasını önermiyoruz. Bunun yerine, belirteç edinmeniz veya hesapları almanız gerektiğinde uygun MSAL API’sini kullanın.
  • Sahip olma kanıtı (PoP) belirteçlerini şifrelemek için kullanılan anahtarlar , IndexedDB API'sinin ve bellek depolamanın bir bileşimi kullanılarak depolanır. Daha fazla bilgi için lütfen access-token-proof-of-possession başlığına bakın.

Daha fazla bilgi

  • Last updated on