Eseguire la migrazione da MSAL Browser v4 a v5

Se non si ha familiarità con MSAL, è consigliabile iniziare da qui.

Se si usa già MSAL v2, è consigliabile consultare prima di tutto questa guida per eseguire la migrazione a MSAL v3. Se provieni da MSAL v3, consulta prima questa guida per effettuare la migrazione a MSAL v4 e quindi segui i passaggi successivi.

Se si proviene da MSAL v4, è possibile seguire questa guida per aggiornare il codice per l'uso di MSAL v5.

Modifiche che causano un'interruzione dell'API

Il tipo restituito di SignedHttpRequest.removeKeys è stato modificato

La removeKeys funzione nella SignedHttpRequest classe restituisce Promise<void> ora anziché Promise<boolean>. La corretta risoluzione della promise equivale ora a quello che in precedenza era un valore restituito di true. Se si verifica un errore, viene ora generato come errore anziché restituire 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 e loadExternalTokens

L'API JS MSAL per loadExternalTokens viene modificata. Le modifiche includono:

  • TokenCache oggetto e getTokenCache() sono stati rimossi
  • L'API loadExternalTokens() è ora un'esportazione separata e richiede Configuration come parametro
// BEFORE

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

//AFTER

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

handleRedirectPromise La firma dell'API è stata modificata

In precedenza, PublicClientApplication.handleRedirectPromise accettava un parametro hash facoltativo. È stato introdotto un nuovo tipo di opzioni denominato HandleRedirectPromiseOptions . A partire da MSAL Browser v5, un oggetto facoltativo con tipo HandleRedirectPromiseOptions è l'unico parametro handleRedirectPromise() accettato.

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

Rimozione di alcune funzioni in PublicClientApplication

Sono state rimosse le funzioni seguenti in PublicClientApplication :

  1. enableAccountStorageEvents() e disableAccountStorageEvents(): gli eventi di archiviazione dell'account sono ora sempre abilitati. Queste chiamate di funzione non sono più necessarie.

  2. getAccountByHomeId(), getAccountByLocalId()e getAccountByUsername(): usare getAccount() invece .

    // 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(): usare logoutRedirect() o logoutPopup() .

Rimozione di startPerformanceMeasurement()

startPerformanceMeasurement() è stato rimosso. Per favore, usa startMeasurement() invece.

Rimozione di PublicClientNext

La PublicClientNext classe e il relativo metodo createPublicClientApplication() statico sono stati rimossi in MSAL v5. È consigliabile usare una delle alternative seguenti a seconda dei requisiti dell'applicazione:

  • PublicClientApplication: usare questa opzione per scenari standard per app singole. Si tratta dell'utilizzo predefinito e più comune.
  • createNestablePublicClientApplication: usare questa opzione se è necessario supportare le app annidate (NAA). Questa funzione ripiega automaticamente su un'istanza standard di PublicClientApplication se il bridge dell'applicazione annidata non è disponibile o se Hub non è configurato per supportare l'autenticazione dell'applicazione annidata. Per altri dettagli, vedere Nested App Configuration (Configurazione app annidata ).
  • createStandardPublicClientApplication: Usare questa opzione per creare e inizializzare un'istanza standard (non NAA) di PublicClientApplication.

Esempio di migrazione

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

Per la maggior parte delle applicazioni, la sostituzione PublicClientNext.createPublicClientApplication(config) con new PublicClientApplication(config) è sufficiente. Se in precedenza è stata usata l'opzione supportsNestedAppAuth di configurazione, eseguire invece la migrazione a createNestablePublicClientApplication(config) .

Rimozione della funzione statica PublicClientApplication.createPublicClientApplication

La createPublicClientApplication funzione statica in PublicClientApplication è stata rimossa e sostituita con un oggetto esportato createStandardPublicClientApplicationseparatamente.

Esempio di migrazione

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

Modifiche di configurazione

Modifiche di BrowserAuthOptions

  1. Il skipAuthorityMetadataCache parametro è stato rimosso da BrowserAuthOptions in Configuration.

  2. Il protocolMode parametro è stato spostato in SystemOptions invece di BrowserAuthOptions in Configuration.

  3. Il parametro supportsNestedAppAuth è stato rimosso. Usare invece l'API createNestablePublicClientApplication per le app annidate. Altre informazioni sulle app annidate sono disponibili qui.

  4. Il navigateTologinRequestUrl parametro è stato rimosso da BrowserAuthOptions in Configuration e ora può essere fornito all'interno di un oggetto options come parametro nella chiamata a handleRedirectPromise:

    pca.handleRedirectPromise({ navigateToLoginRequestUrl: false });

  5. Il parametro encodeExtraQueryParams è stato rimosso. Tutti i parametri di query aggiuntivi vengono codificati.

  6. Il parametro supportsNestedAppAuth è stato rimosso. Utilizzare invece 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. Il OIDCOptions parametro accetta ora un ResponseMode anziché un oggetto ServerResponseType. ResponseMode.QUERY Usare al posto di ServerResponseType.QUERY e ResponseMode.FRAGMENT invece di ServerResponseType.FRAGMENT.

Modifiche di CacheOptions

I parametri seguenti sono stati deprecati in MSAL Browser v4 e sono stati rimossi da CacheOptions in v5:

  1. temporaryCacheLocation
  2. claimsBasedCachingEnabled - I token di accesso non vengono più archiviati in base alle attestazioni richieste.
  3. storeAuthStateInCookie
  4. secureCookies - Tutti i cookie vengono ora inviati in modo sicuro solo tramite HTTPS.
  5. cacheMigrationEnabled

SystemOptions

  1. Il parametro protocolMode è stato spostato in SystemOptions da BrowserAuthOptions in Configurazione. Non sono state apportate modifiche alle relative opzioni o funzionalità.
  2. Il parametro navigateFrameWait è stato rimosso. Questa operazione era necessaria in precedenza dai browser meno recenti che non sono più supportati da MSAL.js.
  3. I iframeHashTimeout parametri e windowHashTimeout sono stati sostituiti rispettivamente con iframeBridgeTimeout e popupBridgeTimeout . Questi timeout ora controllano per quanto tempo attendere una risposta dal bridge di reindirizzamento tramite l'API BroadcastChannel.

asyncPopups

Il parametro asyncPopups è stato rinominato in navigatePopups in SystemOptions e le opzioni sono state invertite. In questo modo viene impostato un valore che indica se i popup vengono aperti e spostati in un secondo momento. Se impostato su true, si aprono popup vuoti che vengono reindirizzati al dominio di accesso. Se impostato su false, i popup vengono aperti direttamente al dominio di accesso. Questa impostazione può essere impostata su false per gli scenari in cui about:blank non è supportato, ad esempio app desktop o app Web progressive.

Importante

Per impostazione predefinita, navigatePopups è ora impostato su true. Se in precedenza si usava asyncPopups , sarà necessario modificarlo navigatePopups in e invertire la configurazione.

Per altri dettagli, vedere la documentazione sulla configurazione .

Modifiche su richiesta

Rimozione del onRedirectNavigate parametro

Il parametro onRedirectNavigate è supportato solo a partire dall'oggetto Configuration e viene rimosso dagli oggetti RedirectRequest e EndSessionRequest. Assicurarsi di impostarlo nella configurazione msal se è necessario usarlo.

Consolidamento di parametri di richiesta aggiuntivi

Sono stati rimossi i parametri di richiesta seguenti:

  • authorizePostBodyParams
  • tokenBodyParameters
  • tokenQueryParameters

Per semplificare i parametri di richiesta aggiuntivi, i parametri aggiuntivi generici devono essere inseriti nella nuova extraParameters opzione di richiesta. Quando extraParameters vengono impostati in una richiesta, vengono inviati in tutte le chiamate al servizio dei token, nella stringa di query dell'URL o nel corpo della richiesta, a seconda del valore di httpMethod configurato nella richiesta (il valore predefinito è GET). Per inviare parametri aggiuntivi che DEVONO essere inseriti nella stringa di query URL, extraQueryParameters è ancora disponibile.

Note

Se non si è sicuri che il parametro aggiuntivo vada in extraQueryStringParameters o in extraParameters, molto probabilmente dovrebbe andare in extraParameters.

Esempio di richiesta v4 (precedente):

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

Esempio di richiesta 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

Nei casi in cui MSAL determina extraParameters deve essere codificato nella stringa URL, extraParameters viene unito con extraQueryParams in modo da sovrascrivere i parametri con lo stesso nome. In questi casi, il valore per il parametro in extraParameters ha la precedenza sul valore in extraQueryParams.

Supporto per Cross-Origin-Opener-Policy (COOP)

MSAL Browser v5 introduce il supporto integrato per Cross-Origin-Opener-Policy (COOP), che migliora la sicurezza isolando i contesti di navigazione. Quando il servizio di autenticazione (Microsoft Entra ID o Azure AD B2C) restituisce header COOP, i flussi di autenticazione tradizionali tramite finestre popup e iframe invisibili sono soggetti a limitazioni. MSAL v5 fornisce un meccanismo di bridge di reindirizzamento per gestire l'autenticazione negli ambienti abilitati per COOP.

Note

Microsoft Entra ID (in precedenza Azure AD) ha COOP abilitato per impostazione predefinita. Per Azure AD B2C, la disponibilità di COOP dipende dalla configurazione back-end e dagli endpoint di autenticazione in uso.

Cosa è cambiato

Quando le intestazioni COOP sono presenti nella risposta del servizio di autenticazione (ad esempio, Cross-Origin-Opener-Policy: same-origin), i tradizionali flussi di autenticazione tramite popup e iframe silenzioso non funzionano perché la finestra di autenticazione non può comunicare con la finestra principale dell'applicazione. MSAL v5 risolve questo problema introducendo un modello di bridge di reindirizzamento.

Tutti i flussi di autenticazione (acquireTokenSilent(), ssoSilent(), loginPopup()e loginRedirect()) ora usano il bridge di reindirizzamento. Il bridge di reindirizzamento gestisce la risposta di autenticazione in modo diverso in base al flusso:

  • Flussi popup e silenziosi: il bridge di reindirizzamento invia la risposta di autenticazione alla finestra principale dell'applicazione tramite l'API BroadcastChannel
  • Flusso di reindirizzamento: il bridge di reindirizzamento torna alla pagina dell'applicazione da cui è stato avviato il reindirizzamento con la risposta di autenticazione nell'URL

Funzionamento

  1. Applicazione principale: l'applicazione avvia l'autenticazione con loginPopup(), ssoSilent()o loginRedirect()
  2. Reindirizzamento: MSAL apre un popup, un iframe o una finestra in una pagina dell'autorità
  3. Flusso di autenticazione: la pagina autorità completa il flusso OAuth e riceve la risposta di autenticazione
  4. Gestione delle risposte: la pagina di reindirizzamento usa la nuova broadcastResponseToMainFrame() funzione che:
    • Per i flussi popup/silenti: trasmette la risposta alla finestra principale tramite l'API BroadcastChannel
    • Per i flussi di reindirizzamento: passa alla pagina da cui viene avviato acquireTokenRedirect con la risposta di autenticazione
  5. Acquisizione di token: l'applicazione principale riceve la risposta e completa l'acquisizione del token

Passaggi per la migrazione

1. Configurare la pagina del bridge di reindirizzamento

Creare una pagina che chiama broadcastResponseToMainFrame() da @azure/msal-browser/redirect-bridge. Questa pagina non deve essere fornita con intestazioni COOP.

La configurazione varia in base al sistema di compilazione: consulta la guida Bridge di reindirizzamento — Configurazione specifica del framework:

Struttura Avvicinarsi
Angular Componente di route + asset facoltativi angular.json
Vite Più pagine rollupOptions.input
Webpack Voce separata + HtmlWebpackPlugin
Next.js Componente della pagina escluso da MsalProvider
CRA (Create React App) Pagina statica public/redirect.html
Express.js Esclusione dell'intestazione COOP sul lato server

Vedi anche:Considerazioni sull'URI di reindirizzamento | Errori interaction_in_progress nei popup | MDN: COOP

2. Aggiornare la configurazione di MSAL

Indirizzare redirectUri a una nuova pagina ponte di reindirizzamento:

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

Importante

Devi anche aggiornare l'URI di reindirizzamento nella registrazione dell'app Entra ID. L'URI deve corrispondere esattamente , inclusi percorso, protocollo e porta. Il mancato rispetto di questa istruzione provoca errori redirect_uri_mismatch.

Modifiche di rilievo del comportamento

Tipi di evento e modifiche interactionStatus

Sono stati consolidati i tipi di evento e InteractionStatus per riflettere ciò che è successo anziché l'API in cui si è verificato.

  1. gli eventi SSO_SILENT e ACQUIRE_TOKEN_BY_CODE sono stati sostituiti dagli eventi ACQUIRE_TOKEN (varianti START/SUCCESS/FAILURE)
  2. ACCOUNT_ADDED e ACCOUNT_REMOVED sono stati sostituiti rispettivamente con LOGIN_SUCCESS e LOGOUT_SUCCESS.
  3. LOGIN_START e LOGIN_FAILURE sono stati sostituiti rispettivamente con ACQUIRE_TOKEN_START e ACQUIRE_TOKEN_FAILURE.
  4. Il payload per LOGIN_SUCCESS è ora un AccountInfo oggetto .
  5. Ogni accesso effettuato con successo genera ora sia un evento LOGIN_SUCCESS sia un evento ACQUIRE_TOKEN_SUCCESS.

LOGIN_SUCCESS migrazione del tipo di payload

Se il callback di evento converte attualmente i payload LOGIN_SUCCESS in AuthenticationResult, aggiornalo in modo da usare AccountInfo per LOGIN_SUCCESS e riservare AuthenticationResult per 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);
    }
});

Modifiche al formato del messaggio di errore

Per ridurre le dimensioni del bundle, i messaggi di errore sono stati spostati all'esterno del bundle. Quando viene generato un errore, la message proprietà restituisce ora un collegamento generico alla documentazione degli errori anziché un messaggio di errore descrittivo:

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

La errorCode proprietà rimane invariata e può comunque essere usata per identificare l'errore specifico. Per le descrizioni dettagliate degli errori, vedere la documentazione relativa agli errori.

Importante

Se l'applicazione si basa sull'analisi o sulla visualizzazione della error.message proprietà, potrebbe essere necessario aggiornare il codice di gestione degli errori per usare invece errorCode o indirizzare gli utenti al collegamento alla documentazione.

Aggiornamento del codice di gestione degli errori

Se mostri gli errori agli utenti, associa errorCode a messaggi comprensibili per l'utente invece di mostrare direttamente 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.");

Se analizzi gli errori per la logica condizionale, passa dalla corrispondenza di stringhe in message al confronto di errorCode (questo era già l'approccio consigliato nella 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);
}

Se registri errori a scopo diagnostico, includi sia errorCode che message (il messaggio contiene ora un collegamento diretto alla documentazione pertinente):

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

I errorCode valori sono gli stessi tra v4 e v5. Solo il message formato è stato modificato. Se il codice esistente contiene già una logica condizionale basata su errorCode, non sono necessarie modifiche.

Modifiche al logging della console

Per ridurre le dimensioni del bundle, i messaggi di log della console vengono ora sottoposti ad hashing. Anziché visualizzare i messaggi di log completi nella console del browser, verrà visualizzato un valore 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

Il debug nella console del browser richiede un passaggio aggiuntivo per decodificare i log. Per decodificare i log con hash in messaggi leggibili, usare lo script di decodifica. Per altre informazioni sull'uso dello script di decodifica, vedere la documentazione dello script.

  • Last updated on