Migrace z prohlížeče MSAL v4 na v5

Pokud s MSAL začínáte, měli byste začít tady.

Pokud pocházíte z MSAL verze 2, měli byste nejprve zkontrolovat tuto příručku a migrovat na MSAL v3. Pokud pocházíte z MSAL v3, měli byste nejprve zkontrolovat tuto příručku , abyste migrovali na MSAL v4 a pak postupujte podle dalších kroků.

Pokud pocházíte z MSAL v4, můžete podle tohoto průvodce aktualizovat kód tak, aby používal MSAL v5.

Zásadní změny rozhraní API

Byl změněn návratový typ SignedHttpRequest.removeKeys.

Funkce removeKeys třídy SignedHttpRequest nyní vrátí Promise<void> místo Promise<boolean>. Úspěšné splnění promisu nyní odpovídá tomu, co dříve představovalo návratovou hodnotu true. Pokud dojde k selhání, je nyní vyvolán jako chyba místo vrácení 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 a loadExternalTokens

Rozhraní API MSAL JS pro loadExternalTokens bylo upraveno. Změny zahrnují:

  • TokenCache objekt a getTokenCache() objekt byly odstraněny.
  • API loadExternalTokens() je nyní samostatným exportem a vyžaduje parametr Configuration
// BEFORE

const pca = new PublicClientApplication(config);
await pca
    .getTokenCache()
    .loadExternalTokens(silentRequest, serverResponse, loadTokenOptions);

//AFTER

await loadExternalTokens(
    config,
    silentRequest,
    serverResponse,
    loadTokenOptions
);

handleRedirectPromise Podpis rozhraní API se změnil.

PublicClientApplication.handleRedirectPromise Dříve se použil volitelný parametr hash. Byl zaveden nový typ HandleRedirectPromiseOptions možností. Od verze MSAL Browser v5 je volitelný objekt s typem HandleRedirectPromiseOptions jediným parametrem handleRedirectPromise() , který přijímá.

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

Odebrání některých funkcí v PublicClientApplication

Byly odebrány následující funkce PublicClientApplication :

  1. enableAccountStorageEvents() a disableAccountStorageEvents(): Události úložiště účtu jsou nyní vždy povolené. Tato volání funkcí už nejsou nutná.

  2. getAccountByHomeId(), getAccountByLocalId()a getAccountByUsername(): použijte getAccount() místo toho.

    // 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(): použijte logoutRedirect() nebo logoutPopup() místo toho.

Odstranění startPerformanceMeasurement()

startPerformanceMeasurement() bylo odstraněno. Místo toho použijte startMeasurement() .

Odstranění PublicClientNext

Třída PublicClientNext a její statická metoda createPublicClientApplication() byly odebrány v MSAL v5. V závislosti na požadavcích vaší aplikace byste měli použít jednu z následujících alternativ:

  • PublicClientApplication: Tuto možnost použijte pro standardní scénáře s jednou aplikací. Toto je výchozí a nejběžnější použití.
  • createNestablePublicClientApplication: Tuto možnost použijte, pokud potřebujete podporovat vnořené aplikace (NAA). Tato funkce se automaticky vrátí do standardní aplikace PublicClientApplication, pokud není vnořený most aplikací dostupný nebo není centrum nakonfigurované tak, aby podporovalo ověřování vnořených aplikací. Další podrobnosti najdete v části Vnořená konfigurace aplikace .
  • createStandardPublicClientApplication: Slouží k vytvoření a inicializaci standardní instance PublicClientApplication (jiné než NAA).

Příklad migrace

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

U většiny aplikací stačí nahradit PublicClientNext.createPublicClientApplication(config)new PublicClientApplication(config) . Pokud jste dříve použili supportsNestedAppAuth možnost konfigurace, proveďte migraci na createNestablePublicClientApplication(config) místo toho.

Odebrání statické funkce PublicClientApplication.createPublicClientApplication

Statická funkce createPublicClientApplication v PublicClientApplication byla odstraněna a nahrazena samostatně exportovanou createStandardPublicClientApplication.

Příklad migrace

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

Změny konfigurace

Změny BrowserAuthOptions

  1. Parametr skipAuthorityMetadataCache byl odebrán z BrowserAuthOptions v konfiguraci.

  2. Parametr protocolMode byl přesunut do SystemOptions místo BrowserAuthOptions v konfiguraci.

  3. Parametr supportsNestedAppAuth byl odebrán. createNestablePublicClientApplication Místo toho použijte rozhraní API pro vnořené aplikace. Další informace o vnořených aplikacích najdete tady.

  4. Parametr navigateTologinRequestUrl byl odebrán z BrowserAuthOptions v Configuration a nyní ho lze místo toho předat v objektu options jako parametr při volání handleRedirectPromise:

    pca.handleRedirectPromise({ navigateToLoginRequestUrl: false });

  5. Parametr encodeExtraQueryParams byl odebrán. Všechny parametry dotazu navíc jsou kódované.

  6. Parametr supportsNestedAppAuth byl odebrán. Místo toho použijte createNestablePublicClientApplication().

        // 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. Parametr OIDCOptions nyní přijímá ResponseMode místo ServerResponseType. Použijte ResponseMode.QUERY místo ServerResponseType.QUERY a ResponseMode.FRAGMENT místo ServerResponseType.FRAGMENT.

Změny v CacheOptions

Následující parametry byly v prohlížeči MSAL v4 zastaralé a byly odebrány z CacheOptions verze 5:

  1. temporaryCacheLocation
  2. claimsBasedCachingEnabled – Přístupové tokeny se už neukládají na základě vyžádaných claimů.
  3. storeAuthStateInCookie
  4. secureCookies - Všechny soubory cookie se teď posílají jenom bezpečně přes PROTOKOL HTTPS.
  5. cacheMigrationEnabled

SystemOptions

  1. Parametr protocolMode byl v Konfiguraci přesunut do SystemOptions z BrowserAuthOptions. V možnostech ani funkcích nejsou žádné změny.
  2. Parametr navigateFrameWait byl odebrán. To bylo dříve potřeba staršími prohlížeči, které už MSAL.jsnepodporují .
  3. Parametry iframeHashTimeout a windowHashTimeout byly nahrazeny parametry iframeBridgeTimeout a popupBridgeTimeout v uvedeném pořadí. Tyto časové limity teď určují, jak dlouho se má čekat na odpověď z mostu přesměrování přes rozhraní API BroadcastChannel.

asyncPopups

Parametr asyncPopups byl v SystemOptions přejmenován na navigatePopups a pořadí možností bylo obráceno. Určuje, zda se vyskakovací okna otevřou a zda se na ně později přejde. Je-li nastavena hodnota true, otevře se prázdné vyskakovací okno a přejde na přihlašovací doménu. Je-li nastavena hodnota false, vyskakovací okna se otevírají přímo na přihlašovací doméně. To se dá nastavit na false pro scénáře, ve about:blank kterých se nepodporuje, například desktopové aplikace nebo progresivní webové aplikace.

Important

Ve výchozím nastavení je nyní navigatePopups nastaveno na true. Pokud jste dříve používali asyncPopups, nyní jej budete muset změnit na navigatePopups a obrátit svou konfiguraci.

Další podrobnosti najdete v dokumentaci ke konfiguraci .

Změny na vyžádání

Odebrání parametru onRedirectNavigate

Parametr onRedirectNavigate je podporován pouze od objektu Configuration dále a byl odebrán z objektů RedirectRequest a EndSessionRequest. Pokud ji potřebujete použít, nezapomeňte ji nastavit v nástroji msal config.

Konsolidace dodatečných parametrů požadavku

Byly odebrány následující parametry požadavku:

  • authorizePostBodyParams
  • tokenBodyParameters
  • tokenQueryParameters

Aby se zjednodušily další parametry požadavků, měly by obecné další parametry přejít do nové extraParameters možnosti požadavku. Pokud jsou v požadavku nastaveny extraParameters, odesílají se při všech voláních tokenové služby buď v řetězci dotazu URL, nebo v těle požadavku, v závislosti na hodnotě httpMethod nakonfigurované v požadavku (výchozí je GET). Pokud chcete odeslat další parametry, které musí jít do řetězce dotazu adresy URL, extraQueryParameters je stále k dispozici.

Note

Pokud si nejste jistí, jestli má dodatečný parametr jít do extraQueryStringParameters nebo do extraParameters, měl by s největší pravděpodobností jít do extraParameters.

Příklad požadavku v4 (předchozí):

// 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
    }
}

Příklad požadavku 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

V případech, kdy MSAL určí, že je nutné extraParameters zakódovat do řetězce URL, se extraParameters sloučí s extraQueryParams způsobem, který způsobí přepsání parametrů se stejným názvem. V těchto případech má hodnota parametru extraParameters přednost před hodnotou v extraQueryParams.

Podpora Cross-Origin-Opener-Policy (COOP)

MSAL Browser v5 přináší integrovanou podporu pro Cross-Origin-Opener-Policy (COOP), která zvyšuje zabezpečení izolací kontextů prohlížení. Když služba ověřování (Microsoft Entra ID nebo Azure AD B2C) vrací hlavičky COOP, jsou tradiční ověřovací toky pomocí automaticky otevíraných oken a tichého ověřování pomocí prvku iframe omezeny. MSAL v5 poskytuje mechanismus mostu přesměrování pro zpracování ověřování v prostředích s podporou COOP.

Note

Microsoft Entra ID (dříve Azure AD) má ve výchozím nastavení povolenou funkci COOP. U Azure AD B2C závisí dostupnost COOP na konfiguraci back-endu a používaných koncových bodech ověřování.

Co se změnilo

Pokud jsou v odpovědi autentizační služby přítomny hlavičky COOP (např. Cross-Origin-Opener-Policy: same-origin), tradiční ověřovací toky s automaticky otevíraným oknem a tiché ověřovací toky pomocí iframe selžou, protože autentizační okno nemůže komunikovat s hlavním oknem aplikace. MSAL v5 to řeší zavedením vzoru mostu přesměrování.

Všechny toky ověřování (acquireTokenSilent(), ssoSilent(), loginPopup()a loginRedirect()) teď používají most pro přesměrování. Přesměrový most zpracovává odpověď ověřování odlišně v závislosti na toku:

  • Automaticky otevírané a tiché toky: Most pro přesměrování vysílá odpověď ověřování do hlavního okna aplikace pomocí rozhraní API BroadcastChannel.
  • Proces přesměrování: Přemosťovací mechanismus přesměrování vás přesměruje zpět na stránku vaší aplikace, která přesměrování iniciovala, s odpovědí ověření v adrese URL.

Jak to funguje

  1. Hlavní aplikace: Aplikace inicializuje ověřování pomocí loginPopup(), ssoSilent()nebo loginRedirect()
  2. Přesměrování: MSAL otevře místní okno, iframe nebo okno se stránkou autority.
  3. Tok ověřování: Stránka autority dokončí tok OAuth a obdrží odpověď na ověření.
  4. Zpracování odpovědí: Stránka přesměrování používá novou broadcastResponseToMainFrame() funkci, která:
    • Pro automaticky otevírané/tiché toky: Vysílá odpověď do hlavního okna prostřednictvím rozhraní API BroadcastChannel.
    • Pro toky přesměrování: Přejde na stránku, ze které se inicializuje acquireTokenRedirect, s ověřovací odpovědí
  5. Získání tokenu: Hlavní aplikace obdrží odpověď a dokončí získání tokenu.

Postup migrace

1. Nastavte stránku přemosťujícího přesměrování

Vytvořte stránku, která volá broadcastResponseToMainFrame() z @azure/msal-browser/redirect-bridge. Tato stránka nesmí být obsluhována se záhlavími COOP.

Nastavení se liší podle systému sestavení — viz průvodce Redirect Bridge — Nastavení specifické pro framework:

.NET Framework Approach
Angular Komponenta trasy + volitelné angular.json prostředky
Vite Vícestráková stránka rollupOptions.input
Webpack Samostatná položka + HtmlWebpackPlugin
Next.js Součást stránky vyloučená z MsalProvider
CRA (vytvoření aplikace React) Statická public/redirect.html stránka
Express.js Vyloučení hlavičky COOP na straně serveru

Viz také:Aspekty identifikátoru URI přesměrování | Chyby interaction_in_progress v popup okně | MDN: COOP

2. Aktualizace konfigurace MSAL

Nasměrujte redirectUri na novou stránku mostu přesměrování:

const msalConfig = {
    auth: {
        clientId: "{your-client-id}",
        authority: "https://login.microsoftonline.com/common",
        redirectUri: "https://{your-app-home-page}/redirect",
    },
};

Important

Musíte také aktualizovat identifikátor URI pro přesměrování v registraci vaší aplikace Entra ID. Identifikátor URI se musí přesně shodovat – včetně cesty, protokolu a portu. Pokud to neuděláte, dojde k redirect_uri_mismatch chybám.

Změny v chování narušující kompatibilitu

Typy událostí a změny InteractionStatus

Konsolidovali jsme typy událostí a InteractionStatus tak, aby odrážely, co se stalo, místo toho, jaké rozhraní API se stalo.

  1. SSO_SILENTa ACQUIRE_TOKEN_BY_CODE události byly nahrazeny událostmi ACQUIRE_TOKEN (START/SUCCESS/FAILURE varianty)
  2. ACCOUNT_ADDED a ACCOUNT_REMOVED byly nahrazeny LOGIN_SUCCESS a LOGOUT_SUCCESSv uvedeném pořadí.
  3. LOGIN_START a LOGIN_FAILURE byly nahrazeny ACQUIRE_TOKEN_START a ACQUIRE_TOKEN_FAILUREv uvedeném pořadí.
  4. Datová část pro LOGIN_SUCCESS je nyní objekt AccountInfo.
  5. Každé úspěšné přihlášení teď vyvolá jak událost LOGIN_SUCCESS, tak událost ACQUIRE_TOKEN_SUCCESS.

LOGIN_SUCCESS migrace typu payloadu

Pokud vaše zpětné volání události aktuálně přetypovává datové struktury LOGIN_SUCCESS na AuthenticationResult, aktualizujte je tak, aby používalo AccountInfo pro LOGIN_SUCCESS, a AuthenticationResult vyhraďte pro 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);
    }
});

Změny formátu chybové zprávy

Kvůli zmenšení velikosti sady byly chybové zprávy přesunuty mimo sadu. Když dojde k chybě, vlastnost message nyní vrací obecný odkaz na dokumentaci chyby namísto popisné chybové zprávy:

// 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";

Vlastnost errorCode zůstává beze změny a lze ji použít k identifikaci konkrétní chyby. Podrobné popisy chyb najdete v dokumentaci k chybám.

Important

Pokud vaše aplikace spoléhá na parsování nebo zobrazování vlastnosti error.message, možná budete muset aktualizovat kód pro zpracování chyb tak, aby místo ní používal errorCode, nebo odkázat uživatele na odkaz na dokumentaci.

Aktualizace kódu pro zpracování chyb

Pokud uživatelům zobrazujete chyby, namapujte errorCode na uživatelsky přívětivé zprávy namísto přímého zobrazení error.message:

// 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.");

Pokud v podmíněné logice parsujete chyby, přejděte od porovnávání řetězců u message k porovnávání errorCode (to už byl doporučený přístup ve 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);
}

Pokud zaznamenáte chyby diagnostiky, uveďte obojí errorCode a message (zpráva teď obsahuje přímý odkaz na příslušnou dokumentaci):

// 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

Hodnoty errorCode jsou stejné mezi v4 a v5 – změnil se pouze message formát. Pokud váš stávající kód již rozlišuje podle errorCode, nejsou nutné žádné změny.

Změny v protokolování konzole

Aby se zmenšila velikost balíčku, zprávy protokolu konzole jsou nyní hashovány. Místo zobrazení úplných zpráv protokolu v konzole prohlížeče se zobrazí hodnota hash:

// 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

Ladění v konzoli prohlížeče vyžaduje další krok pro dekódování záznamů protokolu. Pokud chcete dekódovat hashované protokoly zpět ke čitelným zprávám, použijte dekódovací skript. Další informace o použití dekódovacího skriptu najdete v dokumentaci ke skriptu.

  • Last updated on