Guida alla migrazione da MSAL v1 a @azure/msal-react e @azure/msal-browser

Questo articolo offre una panoramica sulla migrazione da MSAL v1 a @azure/msal-react e @azure/msal-browser. È consigliabile eseguire la migrazione per migliorare le prestazioni e migliorare la sicurezza con il flusso del codice di autorizzazione con PKCE e l'accesso condizionale. Inoltre, è disponibile un supporto migliore per le applicazioni a pagina singola.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare un account gratuitamente
• Un'applicazione esistente registrata nel tenant Microsoft Entra.

Aggiornamento della registrazione dell'app

La libreria @azure/msal-react è un wrapper di @azure/msal-browser che implementa il flusso del codice di autorizzazione con PKCE. Si tratta di un aggiornamento significativo dalla libreria MSAL v1 che implementa il flusso implicito.

Dovrai creare una nuova registrazione dell'app o aggiornare una esistente per usare il nuovo redirectUri tipo "SPA". Per altre informazioni, vedere Applicazione a pagina singola: registrazione dell'app.

Installazione di @azure/msal-react e @azure/msal-browser

Sia @azure/msal-react che la sua dipendenza peer @azure/msal-browser possono essere installate tramite npm. È importante disinstallare il vecchio pacchetto MSAL. Aprire un terminale ed eseguire i comandi seguenti.

npm uninstall msal
npm install @azure/msal-react @azure/msal-browser

Aggiornare da react-aad-msal

Se l'app usa attualmente React Microsoft Entra MSAL per l'autenticazione e si sta cercando di eseguire la migrazione a @azure/msal-react questa sezione, verranno descritte le differenze tra le due librerie e alcune delle modifiche da apportare. React Microsoft Entra MSAL è una libreria di terze parti e MSAL React è stato creato da zero potrebbero esserci alcuni casi limite non coperti o non supportati da MSAL React.

Di seguito sono riportate le funzionalità supportate in react-aad-msal cui non sono supportate in @azure/msal-react:

• Verifica della scadenza di IdToken prima del rendering dei componenti protetti e aggiornamento automatico degli IdToken scaduti
• Supporto integrato per il Redux store (alternativa di seguito)

Per altri casi possibili con react-aad-msal ma non più possibili con @azure/msal-react, apri una segnalazione nel repository GitHub microsoft-authentication-library-for-js.

Inizializzazione

In react-aad-msal, inizializzi l'istanza di MSAL creando un oggetto MsalAuthProvider, che viene successivamente passato al componente AzureAD.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);

In @azure/msal-react inizializzi la tua istanza MSAL utilizzando PublicClientApplication, esportato da @azure/msal-browser, che viene quindi passata al componente MsalProvider, esportato da @azure/msal-react. Le opzioni di configurazione sono in gran parte simili tra msal e @azure/msal-browser, tuttavia è possibile fare riferimento al tipo di configurazione per le opzioni di configurazione più aggiornate.

I authenticationParameters parametri e options usati in react-aad-msal non vengono usati in @azure/msal-react, anche se è possibile ottenere funzionalità simili su singoli componenti. Questo argomento verrà illustrato più avanti in questo documento.

@azure/msal-react usa l'API Context di React per rendere PublicClientApplication e lo stato di autenticazione disponibili in tutto l'albero dei componenti.

import { PublicClientApplication } from "@azure/msal-browser";
import { MsalProvider } from "@azure/msal-react";

const pca = new PublicClientApplication(config);

function App() {
    return (
        <MsalProvider instance={pca}>
            <YourAppComponents />
        </MsalProvider>
    );
}

Note generali sul componente MsalProvider:

• Tutti i componenti che devono avere accesso allo stato di autenticazione o agli hook o componenti esposti da @azure/msal-react devono avere un MsalProvider posizionato più in alto nell'albero dei componenti; pertanto, è consigliabile eseguire il rendering di MsalProvider il più vicino possibile all'elemento radice.
• L'app non deve eseguire il rendering di più di 1 MsalProvider componente in una determinata pagina.
• Non consigliamo di inizializzare PublicClientApplication all'interno di un componente a causa della possibilità di nuovi rendering

Protezione dei componenti

In react-aad-msal, i componenti sono protetti utilizzando il componente AzureAD o l’HOC withAuthentication, che incapsula il componente con AzureAD internamente. Il componente AzureAD visualizzerà i componenti figlio solo se un utente è autenticato e, facoltativamente, avvierà l’accesso se nessun utente è autenticato. Le opzioni usate per l'accesso (ad esempio ambiti, se usare popup o reindirizzamento e così via) vengono specificate in precedenza durante la creazione della authProvider proprietà.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);

function App() {
    return (
        <AzureAD provider={authProvider} forceLogin={true}>
            <span>Only authenticated users can see me.</span>
        </AzureAD>
    );
}

@azure/msal-react, d'altra parte, offre agli sviluppatori un maggiore controllo su ciò che vogliono visualizzare a chi.

• Il componente AuthenticatedTemplate visualizzerà gli elementi figlio se un utente è autenticato
• Il componente UnauthenticatedTemplate eseguirà il rendering dei figli se un utente non è autenticato
• Il componente MsalAuthenticationTemplate avvierà automaticamente la procedura di accesso se l'utente non è autenticato, quindi eseguirà il rendering dei componenti figli una volta autenticato l'utente.

import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import { MsalProvider, AuthenticatedTemplate, UnauthenticatedTemplate, MsalAuthenticationTemplate } from "@azure/msal-react";

const pca = new PublicClientApplication(config);

function App() {
    return (
        <MsalProvider instance={pca}>
            <AuthenticatedTemplate>
                <span>Only authenticated users can see me.</span>
            </AuthenticatedTemplate>
            <UnauthenticatedTemplate>
                <span>Only unauthenticated users can see me.</span>
            </UnauthenticatedTemplate>
            <MsalAuthenticationTemplate interactionType={InteractionType.Popup} authenticationRequest={request}>
                <span>Only authenticated users can see me. Unauthenticated users will get a popup asking them to login first.</span>
            </MsalAuthenticationTemplate>
        </MsalProvider>
    );
}

Inoltre, se preferisci adottare un approccio basato sugli hook, @azure/msal-react offre diversi hook che puoi usare per ottenere risultati simili. Questi sono solo alcuni esempi di base ed è possibile fare riferimento agli hook React MSAL per altre informazioni.

import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import { MsalProvider, useIsAuthenticated, useMsalAuthentication } from "@azure/msal-react";

const pca = new PublicClientApplication(config);

function App() {
    return (
        <MsalProvider instance={pca}>
            <ExampleComponent />
        </MsalProvider>
    );
}

function ExampleComponent() {
    const isAuthenticated = useIsAuthenticated();
    const { error } = useMsalAuthentication(InteractionType.Popup, request); // Will initiate a popup login if user is unauthenticated

    if (isAuthenticated) {
        return <span>Only authenticated users can see me.</span>
    } else if (error) {
        return <span>An error occurred during login!</span>
    } else {
        return <span>Only unauthenticated users can see me.</span>
    }
}

Acquisizione di un token di accesso

react-aad-msal espone un getAccessToken metodo che è possibile usare per ottenere un token di accesso prima di chiamare un'API.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);
const accessToken = authProvider.getAccessToken();

Quando si usano @azure/msal-react e @azure/msal-browser, si richiama acquireTokenSilent sull'istanza PublicClientApplication.

Se è necessario ottenere un token di accesso all'interno di un componente o un hook che si trova sotto MsalProvider è possibile usare l'hook useMsal per ottenere gli oggetti necessari.

import { useState } from "react";
import { useMsal } from "@azure/msal-react";
import { InteractionRequiredAuthError } from "@azure/msal-browser";

function useAccessToken() {
    const { instance, accounts } = useMsal();
    const [accessToken, setAccessToken] = useState(null);

    if (accounts.length > 0) {
        const request = {
            scopes: ["User.Read"],
            account: accounts[0]
        };
        instance.acquireTokenSilent(request).then(response => {
            setAccessToken(response.accessToken);
        }).catch(error => {
            // acquireTokenSilent can fail for a number of reasons, fallback to interaction
            if (error instanceof InteractionRequiredAuthError) {
                instance.acquireTokenPopup(request).then(response => {
                    setAccessToken(response.accessToken);
                });
            }
        });
    }

    return accessToken;
}

Se è necessario ottenere un token di accesso all'esterno del contesto di MsalProvider è possibile usare direttamente l'istanza PublicClientApplication e chiamare getAllAccounts() per ottenere l'oggetto account.

L'esempio seguente mostra l'inizializzazione di PublicClientApplication per scopi dimostrativi. PublicClientApplication deve essere inizializzato una sola volta per ogni caricamento di pagina ed è necessario usare la stessa istanza qui specificata per MsalProvider.

import { PublicClientApplication } from "@azure/msal-browser";

const pca = new PublicClientApplication(config);
const accounts = pca.getAllAccounts();

async function getAccessToken() {
    if (accounts.length > 0) {
        const request = {
            scopes: ["User.Read"],
            account: accounts[0]
        }
        const accessToken = await pca.acquireTokenSilent(request).then((response) => {
            return response.accessToken;
        }).catch(error => {
            // Do not fallback to interaction when running outside the context of MsalProvider. Interaction should always be done inside context.
            console.log(error);
            return null;
        });

        return accessToken;
    }

    return null;
}

Acquisizione di un token ID

react-aad-msal ha esposto una getIdToken funzione per ottenere o rinnovare un idToken.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);
const token = await authProvider.getIdToken();
const idToken = token.idToken.rawIdToken;

Potresti anche avere familiarità con lo schema che prevede la richiesta del tuo clientId come unico scope per ottenere un idToken. Questo modello non è più supportato in @azure/msal-browser.

In @azure/msal-react e @azure/msal-browser tutte le chiamate di token restituiranno sia un token di accesso che un token ID e tutti i rinnovi del token di accesso rinnovieranno anche il token ID.

Se è necessario ottenere un token ID all'interno di un componente o un hook che si trova sotto MsalProvider è possibile usare l'hook useMsal per ottenere gli oggetti necessari.

import { useState } from "react";
import { useMsal } from "@azure/msal-react";

function useIdToken() {
    const { instance, accounts } = useMsal();
    const [idToken, setIdToken] = useState(null);

    if (accounts.length > 0) {
        const request = {
            scopes: ["openid"],
            account: accounts[0]
        };
        instance.acquireTokenSilent(request).then(response => {
            setIdToken(response.idToken);
        }).catch(error => {
            // acquireTokenSilent can fail for a number of reasons, fallback to interaction
            if (error instanceof InteractionRequiredAuthError) {
                instance.acquireTokenPopup(request).then(response => {
                    setIdToken(response.idToken);
                });
            }
        });
    }

    return idToken;
}

Se è necessario ottenere un token ID all'esterno del contesto di MsalProvider è possibile usare direttamente l'istanza PublicClientApplication e chiamare getAllAccounts() per ottenere l'oggetto account.

L'esempio seguente mostra l'inizializzazione di PublicClientApplication per scopi dimostrativi. PublicClientApplication deve essere inizializzato una sola volta per ogni caricamento di pagina ed è necessario usare la stessa istanza qui specificata per MsalProvider.

import { PublicClientApplication } from "@azure/msal-browser";

const pca = new PublicClientApplication(config);
const accounts = pca.getAllAccounts();

async function getIdToken() {
    if (accounts.length > 0) {
        const request = {
            scopes: ["openid"],
            account: accounts[0]
        }
        const idToken = await pca.acquireTokenSilent(request).then((response) => {
            return response.idToken;
        }).catch (error => {
            // Do not fallback to interaction when running outside the context of MsalProvider. Interaction should always be done inside context.
            console.log(error);
            return null;
        });

        return idToken
    }

    return null;
}

Aggiornamento dell'integrazione dell'archivio redux/reazione agli eventi

react-aad-msal offriva un'integrazione pronta all'uso con uno store Redux, inviando azioni quando si verificavano eventi come l'accesso o la disconnessione. @azure/msal-react non fornisce questa funzionalità, tuttavia, è possibile ottenere funzionalità simili usando l'API evento esposta da @azure/msal-browser.

È possibile registrare un callback di eventi che verrà chiamato ogni volta che viene trasmesso un evento (ad esempio LOGIN_SUCCESS). La funzione di callback può esaminare l'evento ed eseguire operazioni con il payload. Se desideri continuare a utilizzare il tuo store Redux esistente, puoi registrare una callback per gli eventi che invia azioni al tuo store.

import { PublicClientApplication, EventType } from "@azure/msal-browser";
import { store } from "your-redux-store-implementation";

const msalInstance = new PublicClientApplication(config);

const callbackId = msalInstance.addEventCallback((message: EventMessage) => {
    if (message.eventType === EventType.LOGIN_SUCCESS) {
        store.dispatchAction({type: "AAD_LOGIN_SUCCESS", payload: message.payload});
    }
});

I payload possono variare tra msal v1 e @azure/msal-browser quindi potrebbe essere necessario apportare alcune modifiche se l'applicazione si basa su campi specifici o sulla forma dell'oggetto. I typedoc contengono l'elenco più aggiornato dei tipi di evento e dei tipi di payload ed è possibile trovare il mapping tra i due nel documento dell'evento.

Vedere anche

• Alias di tipo di MSAL React