Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Jeśli dopiero zaczynasz korzystać z biblioteki MSAL, zacznij tutaj.
Jeśli pochodzisz z biblioteki MSAL w wersji 2, najpierw zapoznaj się z tym przewodnikiem , aby przeprowadzić migrację do biblioteki MSAL w wersji 3. Jeśli pochodzisz z biblioteki MSAL w wersji 3, najpierw zapoznaj się z tym przewodnikiem , aby przeprowadzić migrację do biblioteki MSAL w wersji 4, a następnie wykonaj następne kroki.
Jeśli pochodzisz z biblioteki MSAL w wersji 4, możesz skorzystać z tego przewodnika, aby zaktualizować kod, aby użyć biblioteki MSAL w wersji 5.
Zmiany powodujące niezgodność interfejsu API
Typ zwracania SignedHttpRequest.removeKeys został zmieniony
Funkcja removeKeys w klasie SignedHttpRequest zwraca teraz Promise<void> zamiast Promise<boolean>. Pomyślne spełnienie obietnicy jest teraz równoważne temu, co wcześniej było wartością zwracaną przez true. Jeśli wystąpi błąd, teraz zgłaszany jest wyjątek zamiast zwracania false.
// BEFORE
const shr = new SignedHttpRequest(shrParameters, shrOptions);
const result = await shr.removeKeys(thumbprint);
if (result) {
// do something on success
} else {
// do something on failure
}
// AFTER
const shr = new SignedHttpRequest(shrParameters, shrOptions);
await shr
.removeKeys(thumbprint)
.then(() => {
// do something on success
})
.catch((e) => {
// do something on failure
console.log(e);
});
TokenCache i loadExternalTokens
Interfejs API MSAL JS dla loadExternalTokens został zmodyfikowany. Zmiany obejmują:
-
TokenCacheobiekt igetTokenCache()zostały usunięte - API
loadExternalTokens()jest teraz eksportowane osobno i wymaga parametruConfiguration
// BEFORE
const pca = new PublicClientApplication(config);
await pca
.getTokenCache()
.loadExternalTokens(silentRequest, serverResponse, loadTokenOptions);
//AFTER
await loadExternalTokens(
config,
silentRequest,
serverResponse,
loadTokenOptions
);
handleRedirectPromise Zmieniono podpis interfejsu API
Wcześniej PublicClientApplication.handleRedirectPromise przyjmował opcjonalny parametr hash. Wprowadzono nowy typ opcji o nazwie HandleRedirectPromiseOptions . Od wersji 5 biblioteki MSAL Browser jedynym parametrem akceptowanym przez handleRedirectPromise() jest opcjonalny obiekt typu HandleRedirectPromiseOptions.
// BEFORE
const hash = window.location.hash; // Arbitrary example value
pca.handleRedirectPromise(hash);
// AFTER
pca.handleRedirectPromise({
hash: window.location.hash, // Option nested inside a `HandleRedirectPromiseOptions` object
navigateToLoginRequestUrl: true, // Additional option
});
Usuwanie niektórych funkcji w programie PublicClientApplication
Następujące funkcje w PublicClientApplication zostały usunięte:
enableAccountStorageEvents()idisableAccountStorageEvents(): zdarzenia związane z przechowywaniem kont są teraz zawsze włączone. Te wywołania funkcji nie są już niezbędne.getAccountByHomeId(),getAccountByLocalId()igetAccountByUsername(): zamiast tego użyjgetAccount().// BEFORE const account1 = accountManager.getAccountByHomeId(yourHomeAccountId); const account2 = accountManager.getAccountByLocalId(yourLocalAccountId); const account3 = accountManager.getAccountByUsername(yourUsername); // AFTER const account1 = accountManager.getAccount({ homeAccountId: yourHomeAccountId, }); const account2 = accountManager.getAccount({ localAccountId: yourLocalAccountId, }); const account3 = accountManager.getAccount({ username: yourUsername });logout(): użyj polecenialogoutRedirect()lublogoutPopup()zamiast tego.
Usunięcie startPerformanceMeasurement()
startPerformanceMeasurement() został usunięty. Zamiast tego użyj startMeasurement().
Usunięcie PublicClientNext
Klasa PublicClientNext i jej metoda createPublicClientApplication() statyczna zostały usunięte w formacie MSAL w wersji 5. Należy użyć jednej z następujących alternatyw w zależności od wymagań aplikacji:
-
PublicClientApplication: Użyj tego w przypadku standardowych scenariuszy z jedną aplikacją. Jest to domyślne i najbardziej typowe użycie. -
createNestablePublicClientApplication: Użyj tej opcji, jeśli potrzebujesz obsługi aplikacji zagnieżdżonych (NAA). Ta funkcja automatycznie wraca do standardowego elementu PublicClientApplication, jeśli zagnieżdżony mostek aplikacji jest niedostępny lub centrum nie jest skonfigurowane do obsługi uwierzytelniania zagnieżdżonych aplikacji. Aby uzyskać więcej informacji, zobacz Zagnieżdżona konfiguracja aplikacji . -
createStandardPublicClientApplication: Służy do tworzenia i inicjowania standardowego wystąpienia PublicClientApplication (innego niż NAA).
Przykład migracji
// BEFORE (using PublicClientNext)
import { PublicClientNext } from "@azure/msal-browser";
const pca = PublicClientNext.createPublicClientApplication(config);
// AFTER (standard usage)
import { PublicClientApplication } from "@azure/msal-browser";
const pca = new PublicClientApplication(config);
await pca.initialize();
// AFTER (nested app support)
import { createNestablePublicClientApplication } from "@azure/msal-browser";
const pca = await createNestablePublicClientApplication(config);
// AFTER (standard)
import { createStandardPublicClientApplication } from "@azure/msal-browser";
const pca = await createStandardPublicClientApplication(config);
W przypadku większości aplikacji zamiana PublicClientNext.createPublicClientApplication(config) na new PublicClientApplication(config) jest wystarczająca. Jeśli wcześniej używano opcji konfiguracji supportsNestedAppAuth, przejdź na createNestablePublicClientApplication(config).
Usuwanie funkcji statycznej PublicClientApplication.createPublicClientApplication
Funkcja statyczna createPublicClientApplication w PublicClientApplication została usunięta i zastąpiona osobno eksportowanym createStandardPublicClientApplication.
Przykład migracji
// BEFORE
import { PublicClientApplication } from "@azure/msal-browser";
const pca = await PublicClientApplication.createPublicClientApplication(config);
// AFTER
import { createStandardPublicClientApplication } from "@azure/msal-browser";
const pca = await createStandardPublicClientApplication(config);
Zmiany konfiguracji
Zmiany w BrowserAuthOptions
Parametr
skipAuthorityMetadataCachezostał usunięty z elementu BrowserAuthOptions w konfiguracji.Parametr
protocolModezostał przeniesiony do elementu SystemOptions zamiast BrowserAuthOptions w konfiguracji.Parametr
supportsNestedAppAuthzostał usunięty. Zamiast tego użyj interfejsucreateNestablePublicClientApplicationAPI dla zagnieżdżonych aplikacji. Przeczytaj więcej na temat aplikacji zagnieżdżonych tutaj.Parametr
navigateTologinRequestUrlzostał usunięty z BrowserAuthOptions w Configuration i zamiast tego można go teraz przekazać w obiekcie opcji jako parametr wywołaniahandleRedirectPromise:pca.handleRedirectPromise({ navigateToLoginRequestUrl: false });Parametr
encodeExtraQueryParamszostał usunięty. Wszystkie dodatkowe parametry zapytań są kodowane.Parametr
supportsNestedAppAuthzostał usunięty. UżyjcreateNestablePublicClientApplication()zamiast tego.// BEFORE const pca = new PublicClientApplication({ auth: { clientId: "your-client-id", authority: "https://login.microsoftonline.com/common" supportsNestedAppAuth: true }, }); // AFTER const pca = await createNestablePublicClientApplication({ auth: { clientId: "your-client-id", authority: "https://login.microsoftonline.com/common" } });Parametr
OIDCOptionsprzyjmuje teraz wartośćResponseModezamiastServerResponseType. UżyjResponseMode.QUERYzamiastServerResponseType.QUERYelementu iResponseMode.FRAGMENTzamiastServerResponseType.FRAGMENT.
Zmiany CacheOptions
Następujące parametry zostały uznane za przestarzałe w przeglądarce MSAL w wersji 4 i zostały usunięte z CacheOptions programu w wersji 5:
temporaryCacheLocation-
claimsBasedCachingEnabled— Tokeny dostępu nie są już przechowywane na podstawie żądanych oświadczeń. storeAuthStateInCookie-
secureCookies- Wszystkie pliki cookie są teraz zawsze bezpiecznie wysyłane za pośrednictwem protokołu HTTPS. cacheMigrationEnabled
SystemOpcje
- Parametr
protocolModezostał przeniesiony zBrowserAuthOptionsdoSystemOptionsw sekcji Konfiguracja. Nie ma żadnych zmian w opcjach ani funkcjach. - Parametr
navigateFrameWaitzostał usunięty. Wcześniej były one potrzebne przez starsze przeglądarki, które nie są już obsługiwane przez MSAL.js. - Parametry
iframeHashTimeoutiwindowHashTimeoutzostały zastąpione odpowiednio parametramiiframeBridgeTimeoutipopupBridgeTimeout. Te limity czasu kontrolują teraz czas oczekiwania na odpowiedź z mostka przekierowania za pośrednictwem interfejsu API BroadcastChannel.
asyncPopups
Nazwa parametru asyncPopups została zmieniona na navigatePopups w , SystemOptions a opcje zostały odwrócone. To określa, czy wyskakujące okna są otwierane i czy następuje przejście do nich później. Po ustawieniu wartości true otwierane są puste wyskakujące okna i następuje przejście do domeny logowania. Po ustawieniu wartości false wyskakujące okienka są otwierane bezpośrednio w domenie logowania. Może to być wartość false w scenariuszach, w których about:blank nie jest obsługiwana, np. aplikacje klasyczne lub progresywne aplikacje internetowe.
Ważna
Domyślnie dla navigatePopups ustawiono teraz wartość true. Jeśli używasz asyncPopups wcześniej, musisz teraz zmienić ją na navigatePopups i odwrócić konfigurację.
Aby uzyskać więcej informacji, zobacz dokument dotyczący konfiguracji .
Zmiany na żądanie
Usuwanie parametru onRedirectNavigate
Parametr onRedirectNavigate jest obsługiwany tylko począwszy od obiektu Configuration i został usunięty z obiektów RedirectRequest i EndSessionRequest. Pamiętaj, aby ustawić to w konfiguracji MSAL, jeśli chcesz z tego korzystać.
Konsolidacja dodatkowych parametrów żądania
Usunięto następujące parametry żądania:
authorizePostBodyParamstokenBodyParameterstokenQueryParameters
Aby uprościć dodatkowe parametry żądania, ogólne dodatkowe parametry powinny być dostępne w nowej extraParameters opcji żądania. Gdy w żądaniu ustawiono extraParameters, są one wysyłane we wszystkich wywołaniach usługi tokenów — albo w parametrach zapytania adresu URL, albo w treści żądania, w zależności od wartości httpMethod skonfigurowanej w żądaniu (wartość domyślna to GET).
Aby przesłać dodatkowe parametry, które MUSZĄ znaleźć się w ciągu zapytania URL, nadal dostępny jest extraQueryParameters.
Note
Jeśli nie masz pewności, czy dodatkowy parametr powinien znaleźć się w extraQueryStringParameters czy w extraParameters, to najprawdopodobniej powinien trafić do extraParameters.
Przykład żądania w wersji 4 (poprzedniej):
// Example of a GET request with extra parameters
const authRequest = {
scopes: ["SAMPLE_SCOPE"],
extraQueryParamters: {
"dc": "DC_VALUE" // This was sent on the query string on GET /authorize
},
tokenBodyParameters: {
"extra_parameters_assertion": "ASSERTION_VALUE" // This was sent on the POST body to /token
},
tokenQueryParamters: {
"slice": "SLICE_VALUE" // This was sent on the query string on POST /token
}
}
// Example of a POST request with extra parameters
const authRequest = {
scopes: ["SAMPLE_SCOPE"],
httpMethod: "POST", // default is "GET" -> Determines method for "/authorize" call. Calls to "/token" are always POST
extraQueryParamters: {
"dc": "DC_VALUE" // This was sent on the query string on POST /authorize
},
authorizePostBodyParameters: {
"extra_parameters_assertion": "ASSERTION_VALUE", // This was sent on the body on POST /authorize
}
tokenBodyParameters: {
"extra_parameters_assertion": "ASSERTION_VALUE" // This was sent on the POST body to /token
},
tokenQueryParamters: {
"slice": "SLICE_VALUE" // This was sent on the query string on POST /token
}
}
Przykład żądania v5
// Example of a GET request with extra parameters
const authRequest = {
scopes: ["SAMPLE_SCOPE"],
extraQueryParamters: {
// Will be sent in query string to /authorize and /token
"dc": "DC_VALUE",
"slice": "SLICE_VALUE"
},
extraParameters: {
"extra_parameters_assertion": "ASSERTION_VALUE", // Will be sent in query string to /authorize and in body to /token
},
};
// Example of a POST request with extra parameters
const authRequest = {
scopes: ["SAMPLE_SCOPE"],
httpMethod: "POST", // default is "GET" -> Determines method for "/authorize" call. Calls to "/token" are always POST
extraQueryParamters: {
// Will be sent in query string to /authorize and /token
"dc": "DC_VALUE",
"slice": "SLICE_VALUE"
},
extraParameters: {
extra_parameter_assertion: "assertion_value", // Will be sent in post body to /authorize and /token
},
};
Note
W przypadkach, gdy MSAL stwierdza, że element extraParameters musi zostać zakodowany w ciągu adresu URL, element extraParameters jest scalany z elementem extraQueryParams w sposób, który powoduje nadpisanie parametrów o tej samej nazwie. W takich przypadkach wartość parametru w extraParameters ma pierwszeństwo przed wartością w extraQueryParams.
Obsługa Cross-Origin-Opener-Policy (COOP)
MSAL Browser w wersji 5 wprowadza wbudowaną obsługę mechanizmu Cross-Origin-Opener-Policy (COOP), który zwiększa bezpieczeństwo poprzez izolację kontekstów przeglądania. Gdy usługa uwierzytelniania (Microsoft Entra ID lub Azure AD B2C) zwraca nagłówki COOP, tradycyjne przepływy uwierzytelniania z użyciem wyskakujących okien i ukrytych ramek iframe są ograniczone. MSAL v5 udostępnia mechanizm pomostu przekierowania do obsługi uwierzytelniania w środowiskach z włączonym mechanizmem COOP.
Note
Microsoft Entra ID (dawniej Azure AD) ma domyślnie włączoną funkcję COOP. W przypadku usługi Azure AD B2C dostępność coOP zależy od konfiguracji zaplecza i używanych punktów końcowych uwierzytelniania.
Co się zmieniło
Gdy w odpowiedzi usługi uwierzytelniania występują nagłówki COOP (np. Cross-Origin-Opener-Policy: same-origin), tradycyjne przepływy uwierzytelniania z użyciem wyskakującego okna oraz przepływy cichego uwierzytelniania z użyciem elementu iframe kończą się niepowodzeniem, ponieważ okno uwierzytelniania nie może komunikować się z głównym oknem aplikacji. MSAL w wersji 5 rozwiązuje to przez wprowadzenie wzorca pomostu przekierowania.
Wszystkie przepływy uwierzytelniania (acquireTokenSilent(), ssoSilent(), loginPopup()i loginRedirect()) używają teraz mostka przekierowania. Mechanizm przekierowania obsługuje odpowiedź uwierzytelniającą w różny sposób w zależności od przepływu:
- Przepływy z wyskakującym oknem i bez interakcji: mostek przekierowania przekazuje odpowiedź uwierzytelniającą do głównego okna aplikacji za pomocą interfejsu API BroadcastChannel
- Przepływ przekierowania: mechanizm przekierowania przenosi z powrotem na stronę aplikacji, z której zainicjowano przekierowanie, z odpowiedzią uwierzytelnienia w adresie URL
Jak to działa
-
Główna aplikacja: Aplikacja inicjuje uwierzytelnianie przy użyciu metody
loginPopup(),ssoSilent()lubloginRedirect() - Przekierowanie: MSAL otwiera wyskakujące okno/iframe/osobne okno na stronie urzędu certyfikacji
- Przepływ uwierzytelniania: strona urzędu kończy przepływ protokołu OAuth i odbiera odpowiedź uwierzytelniania
-
Obsługa odpowiedzi: strona przekierowania używa nowej
broadcastResponseToMainFrame()funkcji, która:- W przypadku przepływów wyskakujących/dyskretnych: emituje odpowiedź do okna głównego za pośrednictwem interfejsu API BroadcastChannel
- W przypadku przepływów przekierowań: przechodzi do strony, z której zainicjowano
acquireTokenRedirect, wraz z odpowiedzią uwierzytelnienia
- Pozyskiwanie tokenu: główna aplikacja odbiera odpowiedź i kończy pozyskiwanie tokenu
Kroki migracji
1. Skonfiguruj stronę pośredniczącą przekierowania
Utwórz stronę, która wywołuje broadcastResponseToMainFrame() z poziomu @azure/msal-browser/redirect-bridge. Ta strona nie może być serwowana z nagłówkami COOP.
Konfiguracja różni się w zależności od systemu kompilacji — zobacz przewodnik Redirect Bridge — konfiguracja dla konkretnego frameworka:
| Framework | Approach |
|---|---|
| Angular | Składnik trasy i opcjonalne angular.json zasoby |
| Vite | Wiele stron rollupOptions.input |
| Webpack | Oddzielny wpis + HtmlWebpackPlugin |
| Next.js | Składnik strony wykluczony z MsalProvider |
| CRA (Tworzenie aplikacji React) | Strona statyczna public/redirect.html |
| Express.js | Wykluczenie nagłówka COOP po stronie serwera |
Zobacz również:Uwagi dotyczące identyfikatora URI przekierowania | Błędy interaction_in_progress w oknie podręcznym | MDN: COOP
2. Aktualizowanie konfiguracji biblioteki MSAL
Skieruj redirectUri na nową stronę pomostową przekierowania:
const msalConfig = {
auth: {
clientId: "{your-client-id}",
authority: "https://login.microsoftonline.com/common",
redirectUri: "https://{your-app-home-page}/redirect",
},
};
Ważna
MUSISZ również zaktualizować adres URI przekierowania w rejestracji aplikacji w Entra ID.
Identyfikator URI musi być dokładnie zgodny — łącznie ze ścieżką, protokołem i portem.
Niezastosowanie się do tego powoduje błędy redirect_uri_mismatch.
Zmiany powodujące niezgodność zachowania
Typy zdarzeń i zmiany InteractionStatus
Skonsolidowaliśmy typy zdarzeń i parametr InteractionStatus, aby odzwierciedlić, co się stało, a nie co się stało z interfejsem API.
-
SSO_SILENTiACQUIRE_TOKEN_BY_CODEzdarzenia zostały zastąpione zdarzeniamiACQUIRE_TOKEN(START/SUCCESS/FAILUREwarianty) -
ACCOUNT_ADDEDiACCOUNT_REMOVEDzostały zastąpione odpowiednio elementamiLOGIN_SUCCESSi .LOGOUT_SUCCESS -
LOGIN_STARTiLOGIN_FAILUREzostały zastąpione odpowiednio elementamiACQUIRE_TOKEN_STARTi .ACQUIRE_TOKEN_FAILURE - Ładunek dla
LOGIN_SUCCESSjest teraz obiektemAccountInfo. - Każde pomyślne logowanie emituje teraz zarówno zdarzenie
LOGIN_SUCCESS, jak iACQUIRE_TOKEN_SUCCESS.
LOGIN_SUCCESS migracja typu ładunku
Jeśli funkcja wywołania zwrotnego zdarzenia obecnie rzutuje ładunki LOGIN_SUCCESS na AuthenticationResult, zaktualizuj ją tak, aby używać AccountInfo dla LOGIN_SUCCESS, a AuthenticationResult zastrzeż dla ACQUIRE_TOKEN_SUCCESS.
// BEFORE (v4-style assumption)
import {
EventType,
AuthenticationResult,
} from "@azure/msal-browser";
pca.addEventCallback((event) => {
if (event.eventType === EventType.LOGIN_SUCCESS) {
const result = event.payload as AuthenticationResult;
setAccount(result.account); // Will silently fail in v5 where payload is AccountInfo, not AuthenticationResult
}
});
// AFTER (v5-safe handling)
import {
EventType,
AuthenticationResult,
AccountInfo,
} from "@azure/msal-browser";
pca.addEventCallback((event) => {
if (event.eventType === EventType.LOGIN_SUCCESS) {
const account = event.payload as AccountInfo;
setAccount(account);
}
if (event.eventType === EventType.ACQUIRE_TOKEN_SUCCESS) {
const result = event.payload as AuthenticationResult;
setAccessToken(result.accessToken);
}
});
Zmiany formatu komunikatu o błędzie
Aby zmniejszyć rozmiar pakietu, komunikaty o błędach zostały przeniesione z pakietu. Po wystąpieniu message błędu właściwość zwraca teraz ogólny link do dokumentacji błędu zamiast opisowego komunikatu o błędzie:
// BEFORE (v4)
error.message = "Token request cannot be made without authorization code or refresh token.";
// AFTER (v5)
error.message = "See https://aka.ms/msal.js.errors#request_cannot_be_made for details";
Właściwość errorCode pozostaje niezmieniona i nadal może służyć do identyfikowania określonego błędu. Szczegółowe opisy błędów można znaleźć w dokumentacji błędów.
Ważna
Jeśli aplikacja opiera się na parsowaniu lub wyświetlaniu właściwości error.message, może być konieczne zaktualizowanie kodu obsługi błędów, aby zamiast niej używać errorCode lub kierować użytkowników do odnośnika do dokumentacji.
Aktualizowanie kodu obsługi błędów
Jeśli wyświetlasz błędy dla użytkowników, zamapuj errorCode na przyjazne dla użytkownika komunikaty zamiast pokazywać error.message bezpośrednio:
// BEFORE (v4)
showError(error.message);
// AFTER (v5) — use errorCode for user-facing messages
const userMessages = {
request_cannot_be_made: "Please sign in again to continue.",
interaction_required: "Additional verification is needed.",
consent_required: "Administrator approval is required for this action.",
login_required: "Your session has expired. Please sign in again.",
// Add mappings for error codes your application encounters
};
showError(userMessages[error.errorCode] || "An authentication error occurred.");
Jeśli parsujesz błędy pod kątem logiki warunkowej, przejdź z dopasowywania ciągów znaków w message na porównywanie errorCode (było to już zalecane podejście w v4):
// BEFORE (v4) — fragile, relied on message text
if (error.message.includes("interaction_required")) {
await msalInstance.acquireTokenPopup(request);
}
// AFTER (v5) — use errorCode (stable across versions)
if (error.errorCode === "interaction_required") {
await msalInstance.acquireTokenPopup(request);
}
Jeśli rejestrujesz błędy do celów diagnostycznych, uwzględnij zarówno errorCode, jak i message (komunikat zawiera teraz bezpośrednie łącze do odpowiedniej dokumentacji):
// AFTER (v5) — log errorCode for programmatic use, message for the docs link
logger.error(`MSAL Error [${error.errorCode}]: ${error.message}`);
// Output: MSAL Error [request_cannot_be_made]: See https://aka.ms/msal.js.errors#request_cannot_be_made for details
Wskazówka
Wartości errorCode są takie same między wersjami 4 i v5 — tylko message format został zmieniony. Jeśli w istniejącym kodzie są już instrukcje warunkowe zależne od errorCode, nie trzeba wprowadzać żadnych zmian.
Zmiany w rejestrowaniu w konsoli
Aby zmniejszyć rozmiar pakietu, komunikaty konsoli są teraz haszowane. Zamiast wyświetlać pełne komunikaty dziennika w konsoli przeglądarki, zobaczysz wartość skrótu:
// BEFORE (v4)
[Wed, 15 Jan 2025 10:30:45 GMT] : abc-123 : @azure/msal-browser@4.27.0 : Info - Returning token from cache
// AFTER (v5)
[Wed, 15 Jan 2025 10:30:45 GMT] : abc-123 : @azure/msal-browser@5.0.0 : Info - 7f3a9b2c
Debugowanie w konsoli przeglądarki wymaga dodatkowego kroku w celu dekodowania dzienników. Aby przekształcić haszowane logi z powrotem w czytelne komunikaty, użyj skryptu decode. Aby uzyskać więcej informacji na temat używania skryptu dekodowania, zobacz dokumentację skryptu.