Buforowanie w MSAL.js

Gdy MSAL pobiera token, zapisuje go w pamięci podręcznej do późniejszego użycia. Biblioteka MSAL zarządza za Ciebie okresami ważności tokenów i ich odświeżaniem. Interfejs acquireTokenSilent() API pobiera tokeny dostępu z pamięci podręcznej dla danego konta i odnawia je w razie potrzeby.

Pamięć podręczna

Lokalizację pamięci podręcznej można skonfigurować za pomocą obiektu konfiguracji używanego do tworzenia wystąpienia MSAL:

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"
    }
});

Domyślnie MSAL przechowuje różne artefakty związane z uwierzytelnianiem, które uzyskuje od dostawcy tożsamości, w pamięci przeglądarki za pomocą interfejsu API Web Storage, obsługiwanego przez wszystkie nowoczesne przeglądarki. W związku z tym biblioteka MSAL oferuje dwa sposoby trwałego magazynowania: sessionStorage (wartość domyślna) i localStorage. Ponadto biblioteka MSAL udostępnia opcję memoryStorage, która umożliwia wyłączenie przechowywania pamięci podręcznej w pamięci przeglądarki.

Lokalizacja pamięci podręcznej Usunięto dnia Współużytkowany między oknami/kartami Obsługiwany przepływ przekierowania
sessionStorage zamknięcie okna/karty No Yes
localStorage Zamknij przeglądarkę (chyba że użytkownik wybrał opcję Nie wylogowuj mnie) Yes Yes
memoryStorage odświeżanie/nawigacja strony No No

Note

Chociaż stan uwierzytelnienia może zostać utracony odpowiednio w pamięci sesji i pamięci operacyjnej z powodu zamknięcia okna/karty lub odświeżenia strony/nawigacji, użytkownicy nadal mają aktywną sesję u dostawcy tożsamości (IdP), o ile plik cookie sesji nie wygasł, i mogą być w stanie ponownie uwierzytelnić się bez żadnych monitów.

Wybór między różnymi lokalizacjami magazynu odzwierciedla kompromis między lepszym środowiskiem użytkownika a zwiększonymi zabezpieczeniami. Jak wskazano w powyższej tabeli, magazyn lokalny zapewnia najlepsze możliwe środowisko użytkownika, a magazyn pamięci zapewnia najlepsze zabezpieczenia, ponieważ żadne poufne informacje nie są przechowywane w magazynie przeglądarki. Aby uzyskać więcej informacji, zobacz sekcję dotyczącą zabezpieczeń i buforowanych artefaktów poniżej.

Uwagi dotyczące usługi LocalStorage

Od wersji 4, jeśli używasz lokalizacji pamięci podręcznej localStorage, artefakty uwierzytelniania są szyfrowane, chyba że użytkownik podczas logowania wybierze opcję „Pozostań zalogowany”. Używany algorytm szyfrowania to AES-GCMużywający HKDF w celu uzyskania klucza. Klucz podstawowy jest przechowywany w pliku cookie sesji zatytułowanym msal.cache.encryption.

Ten plik cookie jest automatycznie usuwany z chwilą zamknięcia instancji przeglądarki (nie karty), co sprawia, że odszyfrowanie artefaktów uwierzytelniania po zakończeniu sesji jest niemożliwe. Te wygasłe artefakty uwierzytelniania są usuwane podczas następnej inicjalizacji biblioteki MSAL, a użytkownik może musieć uwierzytelnić się ponownie. Lokalizacja localStorage nadal zapewnia trwałość pamięci podręcznej między kartami dla wszystkich użytkowników, ale utrzymuje się tylko w sesjach przeglądarki dla użytkowników, którzy wybrali opcję "Nie wylogowuj mnie" (KMSI).

Ważna

Celem tego szyfrowania jest zmniejszenie trwałości artefaktów uwierzytelniania, a nie zapewnienie dodatkowych zabezpieczeń. Jeśli atakujący uzyska dostęp do pamięci przeglądarki, będzie miał również dostęp do klucza lub możliwość żądania tokenów w twoim imieniu bez potrzeby korzystania z pamięci podręcznej. Twoim zadaniem jest zapewnienie, że aplikacja nie jest podatna na ataki XSS. Aby uzyskać więcej informacji, zobacz sekcję zabezpieczeń .

Note

Przechowywanie tymczasowych artefaktów uwierzytelniania w plikach cookie jest oznaczone jako przestarzałe w MSAL.js v4. Ta sekcja jest zachowywana dla aplikacji, które nadal używają MSAL.js w wersji 3 lub starszej.

Przeglądarkę MSAL można skonfigurować tak, aby używała plików cookie do przechowywania tymczasowych artefaktów uwierzytelniania. Ta opcja umożliwia zapewnienie obsługi przeglądarek, które mogą czyścić pamięć lokalną lub pamięć sesji podczas logowania opartego na przekierowaniach (np. Internet Explorer, Firefox w trybie prywatnym). Pamiętaj, że po wybraniu tej opcji tokeny są nadal przechowywane w przeglądarce lub magazynie pamięci. Aby uzyskać więcej informacji, zapoznaj się z konfiguracją .

Zabezpieczenia

Uważamy pamięć sessionStorage/localStorage za bezpieczną, o ile w aplikacji nie występują podatności typu cross-site scripting (XSS) ani powiązane luki w zabezpieczeniach. Zapoznaj się z przewodnikiem OWASP XSS Prevention Cheat Sheet, aby zabezpieczyć swoje aplikacje przed atakami XSS. Jeśli nadal masz wątpliwości, zalecamy zamiast tego skorzystanie z opcji memoryStorage.

Buforowane artefakty

Aby usprawnić efektywne pozyskiwanie tokenów przy zachowaniu dobrego środowiska użytkownika, biblioteka MSAL buforuje różne artefakty wynikające z wywołań interfejsu API. Poniżej znajduje się podsumowanie elementów w pamięci podręcznej biblioteki MSAL:

  • Trwałe artefakty (pozostające po zakończeniu żądania — zobacz także: okresy ważności tokenów)
    • tokeny dostępu
    • tokeny identyfikacyjne
    • odświeżanie tokenów
    • accounts
  • Efemeryczne artefakty (ograniczone do czasu trwania żądania)
    • metadane żądania (np. stan, nonce, urząd)
    • Błędy
    • stan interakcji
  • Telemetria
    • poprzednie żądanie nie powiodło się
    • dane wydajności

Note

Wpisy tymczasowej pamięci podręcznej są zawsze przechowywane w magazynie sesji lub w pamięci. MSAL przechodzi na pamięć, jeśli sessionStorage nie jest dostępny.

Note

Kod autoryzacyjny jest przechowywany wyłącznie w pamięci i usuwany po wymianie go na tokeny.

przesłonięcie funkcji temporaryCacheLocation

Note

temporaryCacheLocation to przestarzała opcja konfiguracji w MSAL.js w wersji 4. Ta sekcja jest zachowywana dla aplikacji, które nadal używają MSAL.js w wersji 3 lub starszej.

Warning

Zastępowanie temporaryCacheLocation należy wykonywać ostrożnie, zwłaszcza przy wyborze localStorage. Korzystanie z więcej niż jednej karty/okna nie jest obsługiwane i mogą niespodziewanie wystąpić błędy interaction_in_progress. To jest obejście awaryjne, a nie funkcja w pełni wspierana.

W przypadku korzystania z MSAL.js z domyślną konfiguracją, w sytuacji gdy użytkownik jest przekierowywany po pomyślnym uwierzytelnieniu do nowego okna lub karty, przepływ kodu autoryzacyjnego OAuth 2.0 z PKCE zostanie przerwany. W takim przypadku oryginalne okno lub karta, na której są przechowywane stany uwierzytelniania (weryfikator kodu i wyzwanie), zostaną utracone, a przepływ uwierzytelniania zakończy się niepowodzeniem.

Aby obsłużyć ten scenariusz, możesz skonfigurować bibliotekę MSAL tak, aby używała localStorage jako lokalizacji pamięci podręcznej, przez nadpisanie właściwości konfiguracji temporaryCacheLocation. Dzięki temu kod weryfikujący i parametr challenge mogą być przechowywane w localStorage przeglądarki, który jest współdzielony między wieloma kartami i oknami.

Trwałość pamięci podręcznej podczas aktualizacji i cofania aktualizacji MSAL.js

Czasami MSAL.js musi wprowadzać zmiany kształtu buforowanych artefaktów w celu obsługi nowych wymagań, funkcji lub poprawek błędów. Tak często, jak to możliwe, te zmiany są wprowadzane w sposób zgodny z poprzednimi wersjami, tak aby zapewnić, że gdy aplikacja uaktualnia ją do nowej wersji lub cofa się do starszej wersji, pamięć podręczna obecna w przeglądarce użytkownika nadal może być używana. Jednak nie zawsze jest to możliwe i może się skończyć w stanie, w którym istnieje wiele kopii pamięci podręcznej jednocześnie, jedna używana przez bieżącą wersję MSAL.js uruchomiona, a druga, która została zapisana przez wersję używaną przed uaktualnieniem. Jest to możliwe, aby umożliwić aplikacjom bezproblemowe wycofywanie w razie potrzeby. W zdecydowanej większości uaktualnień MSAL.js migruje dowolną istniejącą pamięć podręczną do nowego formatu w celu zapewnienia bezproblemowego środowiska uaktualniania. W rzadkich przypadkach, takich jak uaktualnienie z wersji 3 do wersji 4, może to nie być możliwe ze względu na wymagania dotyczące zabezpieczeń lub prywatności, a to zawsze powoduje wzrost wersji głównej.

Po wprowadzeniu zmiany pamięci podręcznej powodującej niezgodność starsza wersja pamięci podręcznej jest domyślnie przechowywana przez 5 dni, aby w razie potrzeby umożliwić wycofanie zmian. Czas przechowywania starej pamięci podręcznej można skonfigurować za pomocą konfiguracji pamięci podręcznej cacheRetentionDays w PublicClientApplication. Jeśli pamięć podręczna nie była aktywnie używana w tym czasie, zostanie wyczyszczona przy następnej inicjalizacji MSAL.js. Ponadto, jeśli nie przewidujesz konieczności wycofania zmian, możesz ustawić tę wartość na 0, aby wskazać, że stara pamięć podręczna powinna być zawsze usuwana natychmiast po uaktualnieniu do nowej wersji MSAL.js. Z drugiej strony, jeśli masz dłuższe okno wdrażania dla uaktualnień, możesz ustawić tę wartość na dłuższą.

Note

Tokeny dostępu i odświeżania są usuwane po wygaśnięciu terminu ważności, nawet jeśli skonfigurowany cacheRetentionDays nie został jeszcze osiągnięty. Ważne tokeny dostępu mogą również zostać usunięte w dowolnym momencie, jeśli pamięć przeglądarki osiągnie przydzielony limit miejsca. Po osiągnięciu limitów przydziału magazynu tokeny dostępu są najpierw usuwane na początku, począwszy od wpisów zapisanych przez poprzednią wersję MSAL.js, a następnie przechodząc do wpisów zapisanych przez bieżącą wersję MSAL.js.

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();

Uwagi

  • Nie zalecamy aplikacji mających logikę biznesową zależną od bezpośredniego używania jednostek w pamięci podręcznej. Zamiast tego użyj odpowiedniego interfejsu API biblioteki MSAL, gdy musisz uzyskać tokeny lub pobrać konta.
  • Klucze używane do szyfrowania tokenów dowodu posiadania (PoP) są przechowywane z wykorzystaniem połączenia interfejsu API IndexedDB i pamięci operacyjnej. Aby uzyskać więcej informacji, zobacz access-token-proof-of-possession.

Więcej informacji

  • Last updated on