Migrera från MSAL Browser v4 till v5

Om du inte har använt MSAL tidigare bör du börja här.

Om du kommer från MSAL v2 bör du först kontrollera den här guiden för att migrera till MSAL v3. Om du kommer från MSAL v3 bör du först kontrollera den här guiden för att migrera till MSAL v4 och sedan följa nästa steg.

Om du kommer från MSAL v4 kan du följa den här guiden för att uppdatera koden så att den använder MSAL v5.

Icke-bakåtkompatibla API-ändringar

Returtypen SignedHttpRequest.removeKeys har ändrats

Funktionen removeKeys i SignedHttpRequest klassen returnerar Promise<void> nu i stället för Promise<boolean>. Att löftet nu uppfylls är likvärdigt med det som tidigare var ett returvärde för true. Om ett fel uppstår kastas det nu som ett fel i stället för att returnera 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 och loadExternalTokens

MSAL JS API för loadExternalTokens ändras. Ändringarna omfattar:

  • TokenCache objektet och getTokenCache() har tagits bort
  • API:et loadExternalTokens() är nu en separat export och kräver Configuration som en parameter
// BEFORE

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

//AFTER

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

handleRedirectPromise API-signaturen har ändrats

PublicClientApplication.handleRedirectPromise Tog tidigare in en valfri hash-parameter. En ny alternativtyp med namnet HandleRedirectPromiseOptions har introducerats. Från och med MSAL Browser v5 är ett valfritt objekt med typen HandleRedirectPromiseOptions den enda parametern handleRedirectPromise() som accepterar.

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

Borttagning av vissa funktioner i PublicClientApplication

Följande funktioner i PublicClientApplication har tagits bort:

  1. enableAccountStorageEvents() och disableAccountStorageEvents(): kontolagringshändelser är nu alltid aktiverade. Dessa funktionsanrop är inte längre nödvändiga.

  2. getAccountByHomeId(), getAccountByLocalId(), och getAccountByUsername(): använd getAccount() i stället.

    // 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(): använd logoutRedirect() eller logoutPopup() i stället.

Borttagning av startPerformanceMeasurement()

startPerformanceMeasurement() har tagits bort. Använd startMeasurement() i stället.

Borttagning av PublicClientNext

Klassen PublicClientNext och dess statiska metod createPublicClientApplication() har tagits bort i MSAL v5. Du bör använda något av följande alternativ beroende på programmets krav:

  • PublicClientApplication: Använd detta för standardscenarier med en app. Det här är standardanvändningen och den vanligaste användningen.
  • createNestablePublicClientApplication: Använd detta om du behöver stöd för kapslade appar (NAA). Den här funktionen återgår automatiskt till en Standard PublicClientApplication om den kapslade appbryggan inte är tillgänglig eller om hubben inte har konfigurerats för att stödja kapslad appautentisering. Se Nästlad appkonfiguration för mer information.
  • createStandardPublicClientApplication: Använd detta för att instansiera och initiera en standardinstans (icke-NAA) PublicClientApplication.

Migreringsexempel

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

För de flesta program räcker det PublicClientNext.createPublicClientApplication(config) att ersätta med new PublicClientApplication(config) . Om du tidigare använde konfigurationsalternativet supportsNestedAppAuth migrerar du till createNestablePublicClientApplication(config) i stället.

Borttagning av den statiska funktionen PublicClientApplication.createPublicClientApplication

Den createPublicClientApplication statiska funktionen på PublicClientApplication har tagits bort och ersatts med en separat exporterad createStandardPublicClientApplication.

Migreringsexempel

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

Konfigurationsändringar

Ändringar i BrowserAuthOptions

  1. Parametern skipAuthorityMetadataCache har tagits bort från BrowserAuthOptions i Konfiguration.

  2. Parametern protocolMode har flyttats till SystemOptions i stället för BrowserAuthOptions i Configuration.

  3. Parametern supportsNestedAppAuth har tagits bort. Använd API:et createNestablePublicClientApplication för kapslade appar i stället. Läs mer om kapslade appar här.

  4. Parametern navigateTologinRequestUrl har tagits bort från BrowserAuthOptions i Konfiguration och kan nu i stället anges i ett alternativobjekt som en parameter i anropet till handleRedirectPromise:

    pca.handleRedirectPromise({ navigateToLoginRequestUrl: false });

  5. Parametern encodeExtraQueryParams har tagits bort. Alla extra frågeparamer kodas.

  6. Parametern supportsNestedAppAuth har tagits bort. Använd createNestablePublicClientApplication() i stället.

        // 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. Parametern OIDCOptions tar nu in en ResponseMode i stället för en ServerResponseType. Använd ResponseMode.QUERY i stället för ServerResponseType.QUERY och ResponseMode.FRAGMENT i stället för ServerResponseType.FRAGMENT.

CacheOptions-ändringar

Följande parametrar är inaktuella i MSAL Browser v4 och har tagits bort från CacheOptions i v5:

  1. temporaryCacheLocation
  2. claimsBasedCachingEnabled – Åtkomsttoken lagras inte längre baserat på begärda anspråk.
  3. storeAuthStateInCookie
  4. secureCookies - Alla cookies skickas nu bara säkert via HTTPS.
  5. cacheMigrationEnabled

SystemOptions

  1. Parametern protocolMode har flyttats till SystemOptions från BrowserAuthOptions i Konfiguration. Det finns inga ändringar i dess alternativ eller funktioner.
  2. Parametern navigateFrameWait har tagits bort. Detta behövdes tidigare av äldre webbläsare som inte längre stöds av MSAL.js.
  3. Parametrarna iframeHashTimeout och windowHashTimeout har ersatts med iframeBridgeTimeout respektive popupBridgeTimeout . Dessa timeouter styr nu hur länge du ska vänta på ett svar från omdirigeringsbryggan via BroadcastChannel-API:et.

asyncPopups

Parametern asyncPopups har bytt namn till navigatePopups i SystemOptions och alternativen har ändrats. Detta anger om popup-fönster öppnas och navigeras till senare. När värdet är true öppnas tomma popup-fönster och navigerar till inloggningsdomänen. När värdet är falskt öppnas popup-fönster direkt till inloggningsdomänen. Detta kan ställas in på false för scenarier där about:blank inte stöds, t.ex. skrivbordsappar eller progressiva webbappar.

Important

Som standard navigatePopups är nu inställt på true. Om du använde asyncPopups tidigare måste du nu ändra till navigatePopups och ändra konfigurationen.

Mer information finns i konfigurationsdokumentet .

Ändringar vid begäran

Borttagning av onRedirectNavigate parameter

Parametern onRedirectNavigatestöds endast från Configuration objektet framöver och tas bort från RedirectRequest och EndSessionRequest objekt. Se till att ange den i msal-konfigurationen om du behöver använda den.

Sammanställning av ytterligare begärandeparametrar

Följande parametrar för begäran har tagits bort:

  • authorizePostBodyParams
  • tokenBodyParameters
  • tokenQueryParameters

För att förenkla extra begärandeparametrar bör allmänna extra parametrar gå till det nya extraParameters begärandealternativet. När extraParameters anges i en begäran skickas de på alla tokentjänstanrop i antingen URL-frågesträngen eller begärandetexten, beroende på det httpMethod konfigurerade (standardvärdet är GET) i begäran. Om du vill skicka in extra parametrar som MÅSTE gå i URL-frågesträngen extraQueryParameters är det fortfarande tillgängligt.

Note

Om du är osäker på om den extra parametern ska gå in extraQueryStringParameters eller extraParametersbör den troligen gå i extraParameters.

v4 (föregående) exempel på förfrågan:

// 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 Exempel på begäran

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

I de fall där MSAL bestämmer extraParameters måste kodas till URL-strängen sammanfogas extraParameters med extraQueryParams på ett sätt som gör att samma namngivna parametrar skrivs över. I dessa fall har värdet för parametern i extraParameters företräde framför värdet i extraQueryParams.

Stöd för Cross-Origin-Opener-Policy (COOP)

MSAL Browser v5 introducerar inbyggt stöd för Cross-Origin-Opener-Policy (COOP), vilket förbättrar säkerheten genom att isolera webbläsarkontexter. När autentiseringstjänsten (Microsoft Entra ID eller Azure AD B2C) returnerar COOP-huvuden begränsas traditionella popup- och tyst iframe-autentiseringsflöden. MSAL v5 tillhandahåller en mekanism för omdirigeringsbrygga för att hantera autentisering i COOP-aktiverade miljöer.

Note

Microsoft Entra ID (tidigare Azure AD) har COOP aktiverat som standard. För Azure AD B2C beror COOP-tillgängligheten på din serverdelskonfiguration och de autentiseringsslutpunkter som används.

Vad har ändrats

När COOP-huvuden finns på autentiseringstjänstens svar (t.ex. Cross-Origin-Opener-Policy: same-origin), misslyckas traditionella popup- och tyst iframe-autentiseringsflöden eftersom autentiseringsfönstret inte kan kommunicera tillbaka till huvudprogrammets fönster. MSAL v5 löser detta genom att införa ett omdirigeringsbryggamönster.

Alla autentiseringsflöden (acquireTokenSilent(), ssoSilent(), loginPopup()och loginRedirect()) använder nu omdirigeringsbryggan. Omdirigeringsbryggningen hanterar autentiseringssvaret på olika sätt baserat på flödet:

  • Popup-fönster och tysta flöden: Omdirigeringsbryggan sänder autentiseringssvaret till huvudprogramfönstret med broadcastchannel-API:et
  • Omdirigeringsflöde: Omdirigeringsbrygga navigerar tillbaka till programmets sida som initierade omdirigeringen med autentiseringssvaret i URL:en

Så här fungerar det

  1. Huvudprogram: Ditt program initierar autentisering med hjälp av loginPopup(), ssoSilent()eller loginRedirect()
  2. Omdirigering: MSAL öppnar ett popupfönster, en iframe eller ett fönster till en auktoritetssida
  3. Autentiseringsflöde: Utfärdarsidan slutför OAuth-flödet och tar emot autentiseringssvaret
  4. Svarshantering: Omdirigeringssidan använder den nya broadcastResponseToMainFrame() funktionen som:
    • För popup-/tysta flöden: Sänder svaret till huvudfönstret via BroadcastChannel-API:et
    • För omdirigeringsflöden: Navigerar till sidan där acquireTokenRedirect initieras från med autentiseringssvaret
  5. Tokenförvärv: Huvudprogrammet tar emot svaret och slutför tokenförvärvet

Migreringsanvisningar

1. Konfigurera omdirigeringsbryggsidan

Skapa en sida som anropar broadcastResponseToMainFrame() från @azure/msal-browser/redirect-bridge. Den här sidan får INTE hanteras med COOP-huvuden.

Konfigurationen varierar beroende på byggsystem – se installationsguiden för omdirigeringsbrygga – Framework-Specific :

Framework Tillvägagångssätt
Angular Vägkomponent + valfria angular.json tillgångar
Vite Flera sidor rollupOptions.input
Webpack Separat inlägg + HtmlWebpackPlugin
Next.js Sidkomponenten undantas från MsalProvider
CRA (Skapa en React-app) Statisk sida public/redirect.html
Express.js Undantag för COOP-header på serversidan

Se även:Omdirigering av URI-överväganden | Popup-interaction_in_progress fel | MDN: COOP

2. Uppdatera MSAL-konfigurationen

Peka om redirectUri till en ny sida för omdirigeringsbrygga:

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

Important

Du MÅSTE också uppdatera omdirigerings-URI:n i din Entra ID appregistrering. URI:n måste matcha exakt – inklusive sökväg, protokoll och port. Om detta inte görs leder det till redirect_uri_mismatch fel.

Beteendebrytande ändringar

Händelsetyper och InteractionStatus-ändringar

Vi har konsoliderat händelsetyper och InteractionStatus för att återspegla vad som hände i stället för vilket API det hände i.

  1. SSO_SILENToch ACQUIRE_TOKEN_BY_CODE händelser har ersatts med ACQUIRE_TOKEN händelser (START/SUCCESS/FAILUREvarianter)
  2. ACCOUNT_ADDED och ACCOUNT_REMOVED har ersatts med LOGIN_SUCCESS respektive LOGOUT_SUCCESS.
  3. LOGIN_START och LOGIN_FAILURE har ersatts med ACQUIRE_TOKEN_START respektive ACQUIRE_TOKEN_FAILURE.
  4. Nyttolasten för LOGIN_SUCCESS är nu ett AccountInfo objekt.
  5. Varje lyckad inloggning genererar nu både en LOGIN_SUCCESS- och en ACQUIRE_TOKEN_SUCCESS-händelse.

LOGIN_SUCCESS migrering av nyttolasttyp

Om händelseåteranropet för närvarande genererar LOGIN_SUCCESS nyttolaster till AuthenticationResultuppdaterar du det så att det används AccountInfo för LOGIN_SUCCESS och reserverar AuthenticationResult för 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);
    }
});

Ändringar i formatet för felmeddelanden

Felmeddelanden har flyttats ut ur paketet för att minska paketstorleken. När ett fel utlöses message returnerar egenskapen nu en allmän länk till feldokumentationen i stället för ett beskrivande felmeddelande:

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

Egenskapen errorCode förblir oförändrad och kan fortfarande användas för att identifiera det specifika felet. Detaljerade felbeskrivningar finns i dokumentationen om fel.

Important

Om programmet förlitar sig på att parsa eller visa error.message egenskapen kan du behöva uppdatera felhanteringskoden för att använda errorCode i stället eller dirigera användarna till dokumentationslänken.

Uppdatera felhanteringskod

Om du visar fel för användare kan du mappa errorCode till användarvänliga meddelanden i stället för att visa error.message direkt:

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

Om du parsar fel för villkorsstyrd logik växlar du från strängmatchning messageerrorCode till jämförelse (detta var redan den rekommenderade metoden i 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);
}

Om du loggar fel för diagnostik inkluderar du både errorCode och message (meddelandet innehåller nu en direktlänk till relevant dokumentation):

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

Värdena errorCode är desamma mellan v4 och v5 – endast message formatet har ändrats. Om din befintliga kod redan förgrenas på errorCodebehövs inga ändringar.

Ändringar i konsolloggning

För att minska paketstorleken hashas nu konsolloggmeddelanden. I stället för att se fullständiga loggmeddelanden i webbläsarkonsolen visas ett hash-värde:

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

Felsökning i webbläsarkonsolen kräver ytterligare ett steg för att avkoda loggar. Om du vill avkoda hashade loggar tillbaka till läsbara meddelanden använder du avkodningsskriptet. Mer information om hur du använder avkodningsskriptet finns i skriptdokumentationen.

  • Last updated on