Megjegyzés
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhat bejelentkezni vagy módosítani a címtárat.
Az oldalhoz való hozzáféréshez engedély szükséges. Megpróbálhatja módosítani a címtárat.
Ha még nem ismerkedik az MSAL-zal, kezdje itt.
Ha az MSAL v2-ről érkezik, először ellenőrizze ezt az útmutatót , hogy migráljon az MSAL v3-ra. Ha az MSAL v3-ról érkezik, először ellenőrizze ezt az útmutatót , hogy migráljon az MSAL v4-re, majd kövesse a következő lépéseket.
Ha az MSAL v4-ről érkezik, az alábbi útmutatót követve frissítheti a kódot az MSAL v5 használatára.
API-kompatibilitástörő változások
A SignedHttpRequest.removeKeys visszatérési típusa megváltozott
A SignedHttpRequest osztály removeKeys függvénye mostantól Promise<void> értéket ad vissza Promise<boolean> helyett. A Promise sikeres teljesülése most már egyenértékű azzal, ami korábban a true visszatérési értéke volt. Ha hiba történik, a rendszer most hibát dob ahelyett, hogy false értéket adna vissza.
// 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 és loadExternalTokens
A loadExternalTokens MSAL JS API-ja módosult. A változások közé tartoznak például az alábbiak:
- A(z)
TokenCacheobjektum és a(z)getTokenCache()el lett távolítva - Az
loadExternalTokens()API most már egy külön exportálás, és paraméterként szükségesConfiguration
// BEFORE
const pca = new PublicClientApplication(config);
await pca
.getTokenCache()
.loadExternalTokens(silentRequest, serverResponse, loadTokenOptions);
//AFTER
await loadExternalTokens(
config,
silentRequest,
serverResponse,
loadTokenOptions
);
handleRedirectPromise Módosult az API-aláírás
PublicClientApplication.handleRedirectPromise Korábban egy választható kivonatparamétert vett fel. Új, úgynevezett HandleRedirectPromiseOptions beállítástípus lett bevezetve. Az MSAL Browser v5-től kezdve a handleRedirectPromise() által elfogadott egyetlen paraméter egy opcionális, HandleRedirectPromiseOptions típusú objektum.
// 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
});
Egyes függvények eltávolítása a következőben: PublicClientApplication
A következő függvények PublicClientApplication el lettek távolítva:
enableAccountStorageEvents()ésdisableAccountStorageEvents(): a fiók tárolási eseményei mostantól mindig engedélyezve vannak. Ezekre a függvényhívásokra már nincs szükség.getAccountByHomeId(),getAccountByLocalId()ésgetAccountByUsername(): használjagetAccount()helyette.// 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(): használjalogoutRedirect()vagylogoutPopup()helyette.
startPerformanceMeasurement() eltávolítása
startPerformanceMeasurement() el lett távolítva. Használja inkább a startMeasurement().
A(z) PublicClientNext eltávolítása
Az PublicClientNext osztály és a statikus metódusa createPublicClientApplication() el lett távolítva az MSAL v5-ben. Az alkalmazás követelményeitől függően az alábbi alternatívák egyikét kell használnia:
-
PublicClientApplication: Használja ezt a standard egyalkalmazásos forgatókönyvekhez. Ez az alapértelmezett és leggyakoribb használat. -
createNestablePublicClientApplication: Ezt akkor használja, ha támogatnia kell a beágyazott alkalmazásokat (NAA). Ez a függvény automatikusan visszaesik egy szabványos PublicClientApplication szolgáltatásba, ha a beágyazott alkalmazáshíd nem érhető el, vagy ha a központ nincs konfigurálva a beágyazott alkalmazáshitelesítés támogatására. További részletekért lásd a beágyazott alkalmazáskonfigurációt . -
createStandardPublicClientApplication: Ezzel példányosíthat és inicializálhat egy standard (nem NAA) PublicClientApplication-példányt.
Példa áttelepítésre
// 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);
A legtöbb alkalmazásnál elegendő a PublicClientNext.createPublicClientApplication(config) lecserélése new PublicClientApplication(config)-re. Ha korábban a supportsNestedAppAuth konfigurációs lehetőséget használta, migráljon createNestablePublicClientApplication(config) helyette.
A PublicClientApplication.createPublicClientApplication statikus függvény eltávolítása
A createPublicClientApplication statikus függvényt PublicClientApplication eltávolítottuk, és külön exportáltra cseréltük createStandardPublicClientApplication.
Példa áttelepítésre
// 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);
Konfigurációs módosítások
A BrowserAuthOptions módosításai
A
skipAuthorityMetadataCacheparaméter el lett távolítva a BrowserAuthOptions konfigurációból.A
protocolModeparaméter a BrowserAuthOptions helyett a SystemOptionsba lett áthelyezve a konfigurációban.A
supportsNestedAppAuthparaméter el lett távolítva. Használja inkább acreateNestablePublicClientApplicationBeágyazott alkalmazások API-t. A beágyazott alkalmazásokról itt olvashat bővebben.A
navigateTologinRequestUrlparaméter el lett távolítva a BrowserAuthOptions konfigurációból, és mostantól egy beállításobjektumon belül is megadható paraméterként a következő híváshozhandleRedirectPromise:pca.handleRedirectPromise({ navigateToLoginRequestUrl: false });A
encodeExtraQueryParamsparaméter el lett távolítva. Minden további lekérdezési paraméter kódolva van.A
supportsNestedAppAuthparaméter el lett távolítva. AcreateNestablePublicClientApplication()használható helyette.// 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" } });A
OIDCOptionsparaméter mostantólResponseModehelyettServerResponseTypeértéket fogad el. Kérjük, használja a(z)ResponseMode.QUERYelemetServerResponseType.QUERYhelyett, és a(z)ResponseMode.FRAGMENTelemetServerResponseType.FRAGMENThelyett.
A CacheOptions módosításai
A következő paraméterek elavultak az MSAL Browser 4-ben, és el lettek távolítva a v5-ös verzióból CacheOptions :
temporaryCacheLocation-
claimsBasedCachingEnabled– A hozzáférési jogkivonatok már nem a kért jogcímek alapján vannak tárolva. storeAuthStateInCookie-
secureCookies- Mostantól minden cookie-t csak HTTPS-en keresztül küldünk biztonságosan. cacheMigrationEnabled
SystemOptions
- A
protocolModeparaméter a Konfigurációban át lett helyezve ide:SystemOptions, innen:BrowserAuthOptions. A beállítások és a funkciók nem változnak. - A
navigateFrameWaitparaméter el lett távolítva. Erre korábban olyan régebbi böngészők is szükség volt, amelyeket MSAL.jsmár nem támogatnak. - A(z)
iframeHashTimeoutéswindowHashTimeoutparamétereket rendre a(z)iframeBridgeTimeoutéspopupBridgeTimeoutparaméterek váltották fel. Ezek az időtúllépések mostantól szabályozzák, hogy mennyi ideig kell várni az átirányítási híd válaszára a BroadcastChannel API-n keresztül.
asyncPopups
A asyncPopups paraméter neve navigatePopups-re változott a(z) SystemOptions elemben, és a beállítások sorrendje felcserélődött. Ez határozza meg, hogy megnyitják-e az előugró ablakokat, és csak később navigálnak-e rájuk. Ha true értékre van állítva, üres felugró ablakok nyílnak meg, amelyek a bejelentkezési tartományra navigálnak. Ha hamis értékre van állítva, a rendszer közvetlenül a bejelentkezési tartományba nyitja meg az előugró ablakokat. Ez hamis értékre állítható be olyan helyzetekben, amelyek about:blank nem támogatottak, például asztali vagy progresszív webalkalmazások esetén.
Important
Alapértelmezés szerint a(z) navigatePopups mostantól true értékre van állítva. Ha korábban asyncPopups-t használt, most arra kell módosítania, hogy navigatePopups, és meg kell fordítania a konfigurációját.
További részletekért tekintse meg a konfigurációs dokumentumot .
Változások kérésre
A onRedirectNavigate paraméter eltávolítása
A onRedirectNavigate paraméter csak támogatott a Configuration objektumtól kezdve, és el lett távolítva a RedirectRequest és EndSessionRequest objektumokból. Ha használni szeretné, győződjön meg arról, hogy msal konfigurációban van beállítva.
További kérelemparaméterek konszolidálása
A következő kérelemparaméterek lettek eltávolítva:
authorizePostBodyParamstokenBodyParameterstokenQueryParameters
Az extra kérelemparaméterek egyszerűsítése érdekében az általános extra paramétereknek az új extraParameters kérési beállításban kell lennie. Amikor a(z) extraParameters elemeket beállítják egy kérésben, azokat a jogkivonat-szolgáltatás minden hívásával elküldik, vagy az URL lekérdezési karakterláncában, vagy a kérés törzsében, a kérésben konfigurált httpMethod beállítástól függően (az alapértelmezett érték: GET).
Az URL lekérdezési karakterláncában kötelezően szereplő további paraméterek elküldéséhez a extraQueryParameters továbbra is elérhető.
Note
Ha nem biztos benne, hogy az extra paraméternek a extraQueryStringParameters vagy a extraParameters elembe kell-e kerülnie, akkor nagy valószínűséggel a extraParameters elembe kell kerülnie.
v4 (előző) kérelem példa:
// 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
}
}
v5-ös kérelem – példa
// 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
Azokban az esetekben, amikor az MSAL megállapítja, hogy a(z) extraParameters elemet bele kell kódolni az URL-karakterláncba, a(z) extraParameters összevonásra kerül a(z) extraQueryParams elemmel oly módon, hogy az azonos nevű paraméterek felülíródnak. Ezekben az esetekben a paraméter extraParameters értéke elsőbbséget élvez a következőben megadott extraQueryParamsértékkel szemben:
Cross-Origin-Opener-Policy (COOP) támogatása
Az MSAL Browser v5 beépített támogatást nyújt a Cross-Origin-Opener-Policy (COOP) számára, amely a böngészési környezetek elkülönítésével javítja a biztonságot. Ha a hitelesítési szolgáltatás (Microsoft Entra ID vagy Azure AD B2C) COOP-fejléceket ad vissza, a hagyományos előugró és csendes iframe hitelesítési folyamatok korlátozottak lesznek. Az MSAL v5 egy átirányítási híd mechanizmust biztosít a HITELESÍTÉS KEZELÉSÉHEZ a COOP-kompatibilis környezetekben.
Note
Microsoft Entra ID (korábban Azure AD) alapértelmezés szerint engedélyezve van a COOP. Az AD B2C Azure esetében a COOP elérhetősége a háttérkonfigurációtól és a használt hitelesítési végpontoktól függ.
Mi változott?
Ha a COOP-fejlécek szerepelnek a hitelesítési szolgáltatás válaszában (például), a hagyományos előugró és csendes iframe hitelesítési folyamatok meghiúsulnak, Cross-Origin-Opener-Policy: same-originmert a hitelesítési ablak nem tud vissza kommunikálni a fő alkalmazásablakba. Az MSAL v5 ezt egy átirányítási hídminta bevezetésével oldja meg.
Az összes hitelesítési folyamat (acquireTokenSilent(), , ssoSilent()és loginPopup()loginRedirect()) most az átirányítási hidat használja. Az átirányítási híd a folyamattól függően eltérően kezeli a hitelesítési választ:
- Előugró és csendes folyamatok: Az átirányítási híd a BroadcastChannel API használatával közvetíti a hitelesítési választ a fő alkalmazásablakba
- Átirányítási folyamat: Az átirányítási híd visszakerül az alkalmazás lapjára, amely az átirányítást az URL-cím hitelesítési válaszával kezdeményezte
Hogyan működik?
-
Fő alkalmazás: Az alkalmazás a hitelesítést
loginPopup(),ssoSilent()vagyloginRedirect()használatával kezdeményezi. - Átirányítás: Az MSAL megnyit egy előugró ablakot/iframe-et/ablakot egy szolgáltatói lapra
- Hitelesítési folyamat: A szolgáltatói oldal befejezi az OAuth-folyamatot, és megkapja a hitelesítési választ
-
Válaszkezelés: Az átirányítási oldal az új
broadcastResponseToMainFrame()függvényt használja, amely:- Előugró/csendes folyamatok esetén: A válasz közvetítése a főablakba a BroadcastChannel API-n keresztül
-
Átirányítási folyamatok esetén: Arra a lapra navigál, ahonnan a
acquireTokenRedirectrendszer elindítja a hitelesítési választ
- Jogkivonat-beszerzés: A fő alkalmazás megkapja a választ, és befejezi a jogkivonat beszerzését
A migrálás lépései
1. Az átirányítási híd oldalának beállítása
Hozzon létre egy oldalt, amely meghívja a(z) broadcastResponseToMainFrame() elemet a(z) @azure/msal-browser/redirect-bridge elemből. Ezt a lapot NEM szabad COOP fejlécekkel kiszolgálni.
A beállítás az összeállítási rendszertől függően változik – lásd az Átirányítási híd – Framework-Specific telepítési útmutatót:
| Keretrendszer | Approach |
|---|---|
| Angular | Útvonalösszetevő + választható angular.json eszközök |
| Vite | Többoldalas rollupOptions.input |
| Webpack | Különálló bejegyzés + HtmlWebpackPlugin |
| Next.js | Kizárt oldalkomponens: MsalProvider |
| CRA (React-alkalmazás létrehozása) | Statikus public/redirect.html oldal |
| Express.js | Kiszolgálóoldali COOP-fejléc kizárása |
Lásd még:Az átirányítási URI-val kapcsolatos szempontok | Felugró ablakos interaction_in_progress hibák | MDN: COOP
2. Az MSAL-konfiguráció frissítése
Irányítsa a(z) redirectUri elemet egy új átirányítási köztes oldalra:
const msalConfig = {
auth: {
clientId: "{your-client-id}",
authority: "https://login.microsoftonline.com/common",
redirectUri: "https://{your-app-home-page}/redirect",
},
};
Important
Az átirányítási URI-t is frissítenie kell a Entra ID alkalmazásregisztrációban.
Az URI-nak pontosan meg kell egyeznie – beleértve az elérési utat, a protokollt és a portot is.
Ennek elmulasztása hibákhoz redirect_uri_mismatch vezet.
A viselkedést érintő kompatibilitástörő változások
Eseménytípusok és InteractionStatus-módosítások
Összevontuk az eseménytípusokat és az InteractionStatust, hogy tükrözzük, mi történt ahelyett, hogy az API-ban történt volna.
-
SSO_SILENTésACQUIRE_TOKEN_BY_CODEaz eseményeket eseményekreACQUIRE_TOKENcserélték (START/SUCCESS/FAILUREváltozatok) -
ACCOUNT_ADDEDhelyére, illetveACCOUNT_REMOVEDhelyébeLOGIN_SUCCESSLOGOUT_SUCCESSa következőt léptetik: - A(z)
LOGIN_STARTésLOGIN_FAILUREhelyére rendre a(z)ACQUIRE_TOKEN_STARTésACQUIRE_TOKEN_FAILUREkerült. - A
LOGIN_SUCCESShasznos adata mostantól egyAccountInfoobjektum. - Minden sikeres bejelentkezés mostantól egy
LOGIN_SUCCESSeseményt és egyACQUIRE_TOKEN_SUCCESSeseményt is kivált.
LOGIN_SUCCESS hasznos teher típusának migrálása
Ha az esemény-visszahívása jelenleg a(z) LOGIN_SUCCESS hasznos adatokat AuthenticationResult típusként kezeli, frissítse úgy, hogy LOGIN_SUCCESS esetén AccountInfo típust használjon, és a(z) AuthenticationResult típust tartsa fenn a(z) ACQUIRE_TOKEN_SUCCESS számára.
// 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);
}
});
Hibaüzenet formátumának változásai
A csomag méretének csökkentése érdekében a hibaüzenetek ki lettek helyezve a csomagból. Hiba esetén a message tulajdonság mostantól általános hivatkozást ad vissza a hibadokumentációra leíró hibaüzenet helyett:
// 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";
A errorCode tulajdonság változatlan marad, és továbbra is használható az adott hiba azonosítására. A hibák részletes leírását a hibák dokumentációjában találja.
Important
Ha az alkalmazása a error.message tulajdonság elemzésére vagy megjelenítésére támaszkodik, előfordulhat, hogy frissítenie kell a hibakezelő kódját, hogy helyette a errorCode használja, vagy a felhasználókat a dokumentáció hivatkozására irányítsa.
Hibakezelési kód frissítése
Ha hibákat jelenít meg a felhasználóknak, rendelje a(z) errorCode elemet felhasználóbarát üzenetekhez a(z) error.message közvetlen megjelenítése helyett:
// 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.");
Ha elemzi a feltételes logika hibáit, váltson a sztringegyeztetésről message az errorCode összehasonlításra (a v4-ben már ez volt az ajánlott módszer):
// 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);
}
Ha naplózza a diagnosztikával kapcsolatos hibákat, adja meg mindkettőt errorCode és message (az üzenet most már tartalmaz egy közvetlen hivatkozást a vonatkozó dokumentációra):
// 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
Tip
Az errorCode értékek megegyeznek a v4 és a v5 között – csak a message formátum változott. Ha a meglévő kód már a(z) errorCode alapján ágazik el, nincs szükség semmilyen módosításra.
konzolnaplózás változásai
A csomagméret csökkentése érdekében a konzolnapló-üzenetek kivonatolva lesznek. Ahelyett, hogy teljes naplóüzeneteket lát a böngészőkonzolban, egy kivonatérték jelenik meg:
// 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
A böngészőkonzol hibakereséséhez további lépés szükséges a naplók dekódolásához. A kivonatolt naplók olvasható üzenetekre való visszafejtéséhez használja a dekódoló szkriptet. A dekódoló szkript használatával kapcsolatos további információkért tekintse meg a szkript dokumentációját.