Migrálás az MSAL Browser 4-ről v5-ös verzióra

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) TokenCache objektum é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éges Configuration
// 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:

  1. enableAccountStorageEvents() és disableAccountStorageEvents(): 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.

  2. getAccountByHomeId(), getAccountByLocalId()és getAccountByUsername(): használja getAccount() 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 });
    
  3. logout(): használja logoutRedirect() vagy logoutPopup() 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

  1. A skipAuthorityMetadataCache paraméter el lett távolítva a BrowserAuthOptions konfigurációból.

  2. A protocolMode paraméter a BrowserAuthOptions helyett a SystemOptionsba lett áthelyezve a konfigurációban.

  3. A supportsNestedAppAuth paraméter el lett távolítva. Használja inkább a createNestablePublicClientApplication Beágyazott alkalmazások API-t. A beágyazott alkalmazásokról itt olvashat bővebben.

  4. A navigateTologinRequestUrl paramé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áshoz handleRedirectPromise:

    pca.handleRedirectPromise({ navigateToLoginRequestUrl: false });
    
  5. A encodeExtraQueryParams paraméter el lett távolítva. Minden további lekérdezési paraméter kódolva van.

  6. A supportsNestedAppAuth paraméter el lett távolítva. A createNestablePublicClientApplication() 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"
            }
        });
    
  7. A OIDCOptions paraméter mostantól ResponseMode helyett ServerResponseType értéket fogad el. Kérjük, használja a(z) ResponseMode.QUERY elemet ServerResponseType.QUERY helyett, és a(z) ResponseMode.FRAGMENT elemet ServerResponseType.FRAGMENT helyett.

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 :

  1. temporaryCacheLocation
  2. claimsBasedCachingEnabled – A hozzáférési jogkivonatok már nem a kért jogcímek alapján vannak tárolva.
  3. storeAuthStateInCookie
  4. secureCookies - Mostantól minden cookie-t csak HTTPS-en keresztül küldünk biztonságosan.
  5. cacheMigrationEnabled

SystemOptions

  1. A protocolMode paraméter a Konfigurációban át lett helyezve ide: SystemOptions, innen: BrowserAuthOptions. A beállítások és a funkciók nem változnak.
  2. A navigateFrameWait paramé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.
  3. A(z) iframeHashTimeout és windowHashTimeout paramétereket rendre a(z) iframeBridgeTimeout és popupBridgeTimeout paramé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:

  • authorizePostBodyParams
  • tokenBodyParameters
  • tokenQueryParameters

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?

  1. Fő alkalmazás: Az alkalmazás a hitelesítést loginPopup(), ssoSilent() vagy loginRedirect() használatával kezdeményezi.
  2. Átirányítás: Az MSAL megnyit egy előugró ablakot/iframe-et/ablakot egy szolgáltatói lapra
  3. Hitelesítési folyamat: A szolgáltatói oldal befejezi az OAuth-folyamatot, és megkapja a hitelesítési választ
  4. 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 acquireTokenRedirect rendszer elindítja a hitelesítési választ
  5. 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.

  1. SSO_SILENTés ACQUIRE_TOKEN_BY_CODE az eseményeket eseményekre ACQUIRE_TOKEN cserélték (START/SUCCESS/FAILURE változatok)
  2. ACCOUNT_ADDED helyére, illetve ACCOUNT_REMOVED helyébe LOGIN_SUCCESSLOGOUT_SUCCESSa következőt léptetik:
  3. A(z) LOGIN_START és LOGIN_FAILURE helyére rendre a(z) ACQUIRE_TOKEN_START és ACQUIRE_TOKEN_FAILURE került.
  4. A LOGIN_SUCCESS hasznos adata mostantól egy AccountInfo objektum.
  5. Minden sikeres bejelentkezés mostantól egy LOGIN_SUCCESS eseményt és egy ACQUIRE_TOKEN_SUCCESS esemé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.