Migrieren von MSAL Browser v4 zu v5

Wenn Sie noch nicht mit MSAL arbeiten, sollten Sie hier beginnen.

Wenn Sie von MSAL v2 kommen, sollten Sie dieses Handbuch zuerst überprüfen, um zu MSAL v3 zu migrieren. Wenn Sie von MSAL v3 stammen, sollten Sie dieses Handbuch zuerst überprüfen, um zu MSAL v4 zu migrieren und dann die nächsten Schritte auszuführen.

Wenn Sie von MSAL v4 stammen, können Sie diesem Leitfaden folgen, um Ihren Code für die Verwendung von MSAL v5 zu aktualisieren.

Api-Unterbrechungsänderungen

Der Rückgabetyp "SignedHttpRequest.removeKeys" wurde geändert.

Die removeKeys Funktion für die SignedHttpRequest Klasse gibt Promise<void> jetzt anstelle von Promise<boolean>. Eine erfolgreiche Auflösung der Zusage entspricht nun dem, was zuvor ein Rückgabewert war true. Wenn ein Fehler auftritt, wird es nun als Fehler ausgelöst, anstatt zurückzugeben 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 und loadExternalTokens

MSAL JS-API für loadExternalTokens wird geändert. Zu den Änderungen zählt Folgendes:

• TokenCache objekt und getTokenCache() wurden entfernt
• Die loadExternalTokens() API ist jetzt ein separater Export und erfordert Configuration als Parameter

// BEFORE

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

//AFTER

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

handleRedirectPromise API-Signatur hat sich geändert

PublicClientApplication.handleRedirectPromise Zuvor wurde ein optionaler Hashparameter verwendet. Es wurde ein neuer Optionstyp eingeführt HandleRedirectPromiseOptions . Seit MSAL Browser v5 ist ein optionales Objekt vom Typ HandleRedirectPromiseOptions der einzige Parameter, den handleRedirectPromise() akzeptiert.

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

Entfernen einiger Funktionen in PublicClientApplication

Die folgenden Funktionen PublicClientApplication wurden entfernt:

1. enableAccountStorageEvents() und disableAccountStorageEvents(): Kontospeicherereignisse sind jetzt immer aktiviert. Diese Funktionsaufrufe sind nicht mehr erforderlich.

2. getAccountByHomeId(), getAccountByLocalId()und getAccountByUsername(): verwenden Sie getAccount() stattdessen.

   // 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(): verwenden logoutRedirect() oder logoutPopup() stattdessen.

Entfernung von startPerformanceMeasurement()

startPerformanceMeasurement() wurde entfernt. Verwenden Sie stattdessen startMeasurement().

Entfernen von PublicClientNext

Die PublicClientNext Klasse und die statische Methode createPublicClientApplication() wurden in MSAL v5 entfernt. Je nach den Anforderungen Ihrer Anwendung sollten Sie eine der folgenden Alternativen verwenden:

• PublicClientApplication: Verwenden Sie dies für Standardszenarien mit einer einzelnen App. Dies ist die Standard- und am häufigsten verwendete Verwendung.
• createNestablePublicClientApplication: Verwenden Sie dies, wenn Sie geschachtelte Apps (NAA) unterstützen müssen. Diese Funktion greift automatisch auf eine öffentliche Standardanwendung zurück, wenn die geschachtelte App-Brücke nicht verfügbar ist oder der Hub nicht für die Unterstützung der geschachtelten App-Authentifizierung konfiguriert ist. Weitere Informationen finden Sie unter "Geschachtelte App-Konfiguration ".
• createStandardPublicClientApplication: Verwenden Sie dies, um eine standardmäßige PublicClientApplication-Instanz (nicht NAA) zu instanziieren und zu initialisieren.

Migrationsbeispiel

// 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 die meisten Anwendungen reicht das Ersetzen PublicClientNext.createPublicClientApplication(config) durch new PublicClientApplication(config) . Wenn Sie zuvor die supportsNestedAppAuth Konfigurationsoption verwendet haben, migrieren Sie stattdessen zu createNestablePublicClientApplication(config) .

Entfernen der statischen Funktion PublicClientApplication.createPublicClientApplication

Die statische Funktion createPublicClientApplication in PublicClientApplication wurde entfernt und durch eine separat exportierte Funktion createStandardPublicClientApplication ersetzt.

Migrationsbeispiel

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

BrowserAuthOptions-Änderungen

1. Der skipAuthorityMetadataCache Parameter wurde aus BrowserAuthOptions in Configuration entfernt.

2. Der protocolMode Parameter wurde in "SystemOptions" anstelle von "BrowserAuthOptions" in "Configuration" verschoben.

3. Der Parameter supportsNestedAppAuth wurde entfernt. Verwenden Sie stattdessen die createNestablePublicClientApplication API für geschachtelte Apps. Weitere Informationen zu geschachtelten Apps finden Sie hier.

4. Der navigateTologinRequestUrl-Parameter wurde aus BrowserAuthOptions in Configuration entfernt und kann jetzt stattdessen innerhalb eines Optionsobjekts als Parameter im Aufruf von handleRedirectPromise übergeben werden:

   pca.handleRedirectPromise({ navigateToLoginRequestUrl: false });
   

5. Der Parameter encodeExtraQueryParams wurde entfernt. Alle zusätzlichen Abfrageparameter werden codiert.

6. Der Parameter supportsNestedAppAuth wurde entfernt. Verwenden Sie stattdessen 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. Der OIDCOptions-Parameter akzeptiert jetzt ein ResponseMode anstelle eines ServerResponseType. Bitte verwenden Sie ResponseMode.QUERY anstelle von ServerResponseType.QUERY und ResponseMode.FRAGMENT anstelle von ServerResponseType.FRAGMENT.

CacheOptions-Änderungen

Die folgenden Parameter wurden in MSAL Browser v4 als veraltet eingestuft und in v5 aus CacheOptions entfernt:

1. temporaryCacheLocation
2. claimsBasedCachingEnabled – Zugriffstoken werden nicht mehr basierend auf angeforderten Ansprüchen gespeichert.
3. storeAuthStateInCookie
4. secureCookies - Alle Cookies werden jetzt nur noch sicher über HTTPS gesendet.
5. cacheMigrationEnabled

Systemoptionen

1. Der protocolMode-Parameter wurde in der Konfiguration von BrowserAuthOptions nach SystemOptions verschoben. Es gibt keine Änderungen an den Optionen oder Funktionen.
2. Der Parameter navigateFrameWait wurde entfernt. Dies wurde zuvor von älteren Browsern benötigt, die von MSAL.jsnicht mehr unterstützt werden.
3. Die Parameter iframeHashTimeout und windowHashTimeout wurden durch iframeBridgeTimeout bzw. popupBridgeTimeout ersetzt. Diese Timeouts legen jetzt fest, wie lange auf eine Antwort von der Redirect-Bridge über die BroadcastChannel-API gewartet werden soll.

asyncPopups

Der asyncPopups-Parameter wurde in SystemOptions in navigatePopups umbenannt und die Optionen wurden vertauscht. Hiermit wird festgelegt, ob Pop-ups geöffnet und später aufgerufen werden. Bei Festlegung auf "true" werden leere Popups geöffnet und zur Anmeldedomäne navigiert. Wenn dieser Wert auf "false" festgelegt ist, werden Popups direkt in der Anmeldedomäne geöffnet. Dies kann für Szenarien, in denen about:blank nicht unterstützt wird, auf "false" festgelegt werden, z. B. Desktop-Apps oder progressive Web-Apps.

Weitere Informationen finden Sie im Konfigurationsdokument .

Änderungen auf Anfrage

Entfernen des onRedirectNavigate Parameters

Der onRedirectNavigate-Parameter wird künftig nur noch vom Configuration-Objekt unterstützt und aus den RedirectRequest- und EndSessionRequest-Objekten entfernt. Stellen Sie sicher, dass Sie sie in der msal-Konfiguration festlegen, wenn Sie sie verwenden müssen.

Konsolidierung zusätzlicher Anforderungsparameter

Die folgenden Anforderungsparameter wurden entfernt:

• authorizePostBodyParams
• tokenBodyParameters
• tokenQueryParameters

Um zusätzliche Anforderungsparameter zu vereinfachen, sollten generische zusätzliche Parameter in der neuen extraParameters Anforderungsoption verwendet werden. Wenn extraParameters in einer Anfrage festgelegt sind, werden sie bei allen Aufrufen an den Tokendienst entweder in der URL-Abfragezeichenfolge oder im Anforderungstext gesendet, abhängig von dem in der Anfrage konfigurierten httpMethod (Standard ist GET). Um zusätzliche Parameter zu senden, die in die URL-Abfragezeichenfolge gehen müssen, extraQueryParameters ist weiterhin verfügbar.

v4 (vorheriges) Anforderungsbeispiel:

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

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

Unterstützung für die Cross-Origin-Opener-Policy (COOP)

MSAL Browser v5 führt integrierte Unterstützung für Cross-Origin-Opener-Policy (COOP) ein, die die Sicherheit durch Isolieren von Browserkontexten verbessert. Wenn der Authentifizierungsdienst (Microsoft Entra ID oder Azure AD B2C) COOP-Header sendet, werden herkömmliche Popup- und stille Iframe-Authentifizierungsflüsse eingeschränkt. MSAL v5 bietet einen Umleitungsbrückenmechanismus zur Behandlung der Authentifizierung in COOP-fähigen Umgebungen.

Was hat sich geändert?

Wenn die Antwort des Authentifizierungsdienstes COOP-Header enthält (z. B. Cross-Origin-Opener-Policy: same-origin), schlagen herkömmliche Popup- und stille Iframe-Authentifizierungsabläufe fehl, da das Authentifizierungsfenster nicht mit dem Hauptanwendungsfenster kommunizieren kann. MSAL v5 löst dies durch Die Einführung eines Umleitungsbrückenmusters.

Alle Authentifizierungsflüsse (acquireTokenSilent(), ssoSilent(), loginPopup()und loginRedirect()) verwenden jetzt die Umleitungsbrücke. Die Umleitungsbrücke behandelt die Authentifizierungsantwort je nach Ablauf unterschiedlich:

• Popup- und stille Abläufe: Die Umleitungsbrücke überträgt die Authentifizierungsantwort mithilfe der BroadcastChannel-API an das Hauptfenster der Anwendung.
• Umleitungsfluss: Die Umleitungsbrücke navigiert zurück zur Seite Ihrer Anwendung, die die Umleitung mit der Authentifizierungsantwort in der URL initiiert hat.

Funktionsweise

1. Hauptanwendung: Ihre Anwendung initiiert die Authentifizierung mit loginPopup(), oder ssoSilent()loginRedirect()
2. Umleitung: MSAL öffnet ein Popup/iframe/Fenster auf eine Autoritätsseite.
3. Authentifizierungsfluss: Die Autoritätsseite schließt den OAuth-Fluss ab und empfängt die Authentifizierungsantwort.
4. Antwortbehandlung: Die Umleitungsseite verwendet die neue broadcastResponseToMainFrame() Funktion, die:
   • Für Popup-/Silent-Abläufe: Überträgt die Antwort über die BroadcastChannel-API an das Hauptfenster
   • Für Umleitungsabläufe: Navigiert zu der Seite zurück, auf der acquireTokenRedirect mit der Authentifizierungsantwort initiiert wird.
5. Tokenerwerb: Die Hauptanwendung empfängt die Antwort und schließt den Tokenerwerb ab.

Schritte bei der Migration

1. Einrichten der Seite "Umleitungsbrücke"

Erstellen Sie eine Seite, die broadcastResponseToMainFrame() von @azure/msal-browser/redirect-bridge aus aufruft. Diese Seite darf nicht mit COOP-Kopfzeilen bedient werden.

Die Einrichtung variiert je nach Build-System – siehe den Leitfaden Redirect-Bridge – frameworkspezifische Einrichtung:

Siehe auch:Überlegungen zu Umleitungs-URIs | Fehler vom Typ interaction_in_progress in Popupinteraktionen | MDN: COOP

2. Aktualisieren Der MSAL-Konfiguration

Zeigen Sie redirectUri auf eine neue Umleitungsbrückesseite:

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

Verhaltensgebrochene Änderungen

Ereignistypen und InteractionStatus-Änderungen

Wir haben Ereignistypen und InteractionStatus konsolidiert, sodass sie widerspiegeln, was passiert ist, statt in welcher API dies geschehen ist.

1. SSO_SILENTund ACQUIRE_TOKEN_BY_CODE Ereignisse wurden durch ACQUIRE_TOKEN Ereignisse ersetzt (START/SUCCESS/FAILURE Varianten)
2. ACCOUNT_ADDED und ACCOUNT_REMOVED wurden durch LOGIN_SUCCESS bzw LOGOUT_SUCCESS. ersetzt.
3. LOGIN_START und LOGIN_FAILURE wurden durch ACQUIRE_TOKEN_START bzw ACQUIRE_TOKEN_FAILURE. ersetzt.
4. Die Nutzlast für LOGIN_SUCCESS ist jetzt ein AccountInfo Objekt.
5. Jede erfolgreiche Anmeldung löst jetzt sowohl ein LOGIN_SUCCESS- als auch ein ACQUIRE_TOKEN_SUCCESS-Ereignis aus.

LOGIN_SUCCESS Nutzlasttypmigration

Wenn Ihr Ereignis-Callback derzeit LOGIN_SUCCESSNutzlasten in AuthenticationResult umwandelt, aktualisieren Sie ihn so, dass für LOGIN_SUCCESSAccountInfo verwendet wird und AuthenticationResult für ACQUIRE_TOKEN_SUCCESS reserviert bleibt.

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

Änderungen des Fehlermeldungsformats

Um die Größe des Bündels zu verringern, wurden Fehlermeldungen aus dem Bundle verschoben. Wenn ein Fehler ausgelöst wird, gibt die message Eigenschaft jetzt einen generischen Link zur Fehlerdokumentation anstelle einer beschreibenden Fehlermeldung zurück:

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

Die errorCode Eigenschaft bleibt unverändert und kann weiterhin verwendet werden, um den spezifischen Fehler zu identifizieren. Ausführliche Fehlerbeschreibungen finden Sie in der Fehlerdokumentation.

Aktualisieren von Fehlerbehandlungscode

Wenn Sie Benutzern Fehler anzeigen, ordnen Sie errorCode benutzerfreundlichen Meldungen zu, anstatt error.message direkt anzuzeigen:

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

Wenn Sie Fehler für bedingte Logik analysieren, wechseln Sie von Zeichenfolgenabgleich message zum Vergleich errorCode (dies war bereits der empfohlene Ansatz in 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);
}

Wenn Sie Fehler zur Diagnose protokollieren, fügen Sie sowohl errorCode als auch message ein (die Nachricht enthält jetzt einen direkten Link zur zugehörigen 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

Änderungen an der Konsolenprotokollierung

Um die Bündelgröße zu verringern, werden jetzt Konsolenprotokollmeldungen mit Hash versehen. Anstatt vollständige Protokollmeldungen in der Browserkonsole anzuzeigen, wird ein Hashwert angezeigt:

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

Für das Debuggen in der Browserkonsole ist ein zusätzlicher Schritt erforderlich, um Protokolle zu decodieren. Um gehashte Protokolle wieder in lesbare Meldungen zu decodieren, verwenden Sie das decode script. Weitere Informationen zur Verwendung des Decodierungsskripts finden Sie in der Skriptdokumentation.