Migratiehandleiding van MSAL v1 naar @azure/msal-react en @azure/msal-browser

Dit artikel bevat een overzicht van het migreren van MSAL v1 naar @azure/msal-react en @azure/msal-browser. We raden migratie aan voor verbeterde prestaties en betere beveiliging met de autorisatiecodestroom met PKCE en voorwaardelijke toegang. Daarnaast is er betere ondersteuning voor toepassingen met één pagina.

Prerequisites

• Een Azure-account met een actief abonnement. Gratis een account maken
• Een bestaande toepassing die is geregistreerd in uw Microsoft Entra-tenant.

Uw app-registratie bijwerken

De @azure/msal-react-bibliotheek is een wrapper rond @azure/msal-browser, die de autorisatiecodeflow met PKCE implementeert. Dit is een belangrijke update van de MSAL v1-bibliotheek waarmee de impliciete stroom wordt geïmplementeerd.

U moet een nieuwe app-registratie maken of een bestaande bijwerken om het nieuwe redirectUri type "SPA" te gebruiken. Raadpleeg de toepassing met één pagina: App-registratie voor meer informatie.

@azure/msal-react en @azure/msal-browser installeren

Zowel @azure/msal-react als de bijbehorende peerafhankelijkheid @azure/msal-browser kunnen worden geïnstalleerd vanuit npm. Het is belangrijk om uw oude MSAL-pakket te verwijderen. Open een terminal en voer de volgende opdrachten uit.

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

Upgraden vanaf react-aad-msal

Als uw app momenteel React Microsoft Entra MSAL gebruikt voor verificatie en u wilt migreren naar @azure/msal-react deze sectie, worden de verschillen tussen de twee bibliotheken en enkele van de wijzigingen beschreven die u moet aanbrengen. React Microsoft Entra MSAL is een externe bibliotheek en omdat MSAL React helemaal vanaf nul is opgebouwd, kunnen er enkele randgevallen zijn die niet door MSAL React worden afgedekt of ondersteund.

Hieronder vindt u functies die worden ondersteund in react-aad-msal, maar niet in @azure/msal-react:

• Controleren of een IdToken is verlopen voordat beveiligde componenten worden weergegeven en verlopen IdTokens automatisch vernieuwen
• Out-of-the-box-ondersteuning voor redux store (alternatief hieronder)

Voor andere gevallen die mogelijk zijn met react-aad-msal, maar niet langer mogelijk zijn met @azure/msal-react, maak een issue aan in de microsoft-authentication-library-for-js-GitHub-repo.

Initialisatie

In react-aad-msal initialiseert u uw MSAL-instantie door een MsalAuthProvider-object te maken dat later wordt doorgegeven aan de AzureAD-component.

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

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

In @azure/msal-react initialiseert u uw MSAL-instantie met PublicClientApplication, geëxporteerd uit @azure/msal-browser, die vervolgens wordt doorgegeven aan het MsalProvider-component dat is geëxporteerd uit @azure/msal-react. De configuratieopties zijn grotendeels vergelijkbaar tussen msal en @azure/msal-browser, maar u kunt het configuratietype raadplegen voor de meest recente configuratieopties.

De parameters authenticationParameters en options die in react-aad-msal worden gebruikt, worden niet gebruikt in @azure/msal-react, al kan vergelijkbare functionaliteit wel op afzonderlijke componenten worden bereikt. Dit wordt verderop in dit document uitgelegd.

@azure/msal-react maakt gebruik van de React Context API om PublicClientApplication en de authenticatiestatus beschikbaar te maken in je volledige componentstructuur.

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

Algemene opmerkingen over het MsalProvider onderdeel:

• Alle componenten die toegang nodig hebben tot de authenticatiestatus of hooks/componenten die door @azure/msal-react beschikbaar worden gesteld, moeten hogerop in de componentstructuur een MsalProvider hebben. Daarom wordt aanbevolen MsalProvider zo dicht mogelijk bij de root te renderen.
• Uw app mag niet meer dan 1 MsalProvider onderdeel weergeven op een bepaalde pagina.
• We raden niet aan om PublicClientApplication binnen een component te initialiseren vanwege de kans op opnieuw renderen.

Uw onderdelen beveiligen

In react-aad-msal worden componenten beveiligd met de AzureAD-component of de withAuthentication HOC, die je component achter de schermen met AzureAD omhult. De AzureAD component rendert alleen onderliggende componenten als een gebruiker is aangemeld en kan optioneel een aanmeldproces starten als er geen gebruiker is aangemeld. De opties die voor aanmelden worden gebruikt (bijvoorbeeld scopes, of u een pop-up of omleiding wilt gebruiken, enzovoort) worden eerder gespecificeerd, bij het maken van de authProvider prop.

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, daarentegen, geeft ontwikkelaars meer controle over wat ze willen weergeven aan wie.

• De AuthenticatedTemplate component rendert onderliggende elementen als een gebruiker is geauthenticeerd
• De UnauthenticatedTemplate component rendert child-elementen als een gebruiker niet is geauthenticeerd
• De MsalAuthenticationTemplate-component start automatisch een aanmeldproces als een gebruiker niet is aangemeld en geeft vervolgens onderliggende elementen weer zodra de gebruiker is aangemeld.

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

Daarnaast geldt: als u liever kiest voor een op hooks gebaseerde aanpak, biedt @azure/msal-react verschillende hooks die u kunt gebruiken om vergelijkbare resultaten te bereiken. Dit zijn slechts enkele basisvoorbeelden en u kunt naar MSAL React-hooks verwijzen voor meer informatie.

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

Een toegangstoken verkrijgen

react-aad-msal maakt een getAccessToken methode beschikbaar die u kunt gebruiken om een toegangstoken te verkrijgen voordat u een API aanroept.

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

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

Wanneer u @azure/msal-react en @azure/msal-browser gebruikt, roept u acquireTokenSilent aan op de instantie PublicClientApplication.

Als u een toegangstoken in een onderdeel of haak wilt verkrijgen die zich onder MsalProvider bevindt, kunt u de useMsal haak gebruiken om de objecten op te halen die u nodig hebt.

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

Als u buiten de context van MsalProvider een toegangstoken moet ophalen, kunt u de instantie PublicClientApplication rechtstreeks gebruiken en getAllAccounts() aanroepen om het accountobject op te halen.

In het onderstaande voorbeeld wordt de initialisatie van PublicClientApplication ter demonstratie getoond. PublicClientApplication mag slechts één keer worden geïnitialiseerd bij het laden van de pagina en u moet hier dezelfde instantie gebruiken die u aan MsalProvider doorgeeft.

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

Een id-token verkrijgen

react-aad-msal een getIdToken functie beschikbaar gemaakt om een idToken op te halen of te vernieuwen.

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

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

U bent wellicht ook bekend met het patroon waarbij u uw clientId als enige scope aanvraagt om een idToken te verkrijgen. Dit is geen ondersteund patroon meer in @azure/msal-browser.

In @azure/msal-react en @azure/msal-browser retourneren alle tokenaanroepen zowel een toegangstoken als een id-token, en bij alle vernieuwingen van het toegangstoken wordt ook het id-token vernieuwd.

Als u een id-token in een onderdeel of haak wilt verkrijgen die zich onder MsalProvider bevindt, kunt u de useMsal haak gebruiken om de objecten op te halen die u nodig hebt.

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

Als u een id-token wilt ophalen buiten de context van MsalProvider, kunt u de instantie PublicClientApplication rechtstreeks gebruiken en getAllAccounts() aanroepen om het accountobject op te halen.

In het onderstaande voorbeeld wordt de initialisatie van PublicClientApplication getoond voor demonstratiedoeleinden. PublicClientApplication mag slechts één keer per paginaweergave worden geïnitialiseerd en u moet hier dezelfde instantie gebruiken die u aan MsalProvider doorgeeft.

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

Redux Store-integratie bijwerken/ reageren op gebeurtenissen

react-aad-msal bood standaard integratie met een Redux-store door acties te dispatchen wanneer gebeurtenissen zoals aanmelden of afmelden plaatsvonden. @azure/msal-react biedt deze functie niet, maar vergelijkbare functionaliteit kan worden bereikt met behulp van de gebeurtenis-API die wordt weergegeven door @azure/msal-browser.

U kunt een gebeurtenis-callback registreren die telkens wordt aangeroepen wanneer een gebeurtenis wordt uitgezonden (bijvoorbeeld LOGIN_SUCCESS). Uw callbackfunctie kan de gebeurtenis bekijken en iets doen met de payload. Als u uw bestaande Redux Store wilt blijven gebruiken, kunt u een callback voor gebeurtenissen registreren waarmee acties naar uw winkel worden verzonden.

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

De payloads kunnen verschillen tussen msal v1 en @azure/msal-browser, dus moet u mogelijk enige aanpassingen aanbrengen als uw toepassing afhankelijk is van specifieke velden of de structuur van het object. Onze typedocs bevatten de meest actuele lijst met gebeurtenistypen en payloadtypen, en u vindt de toewijzing tussen de twee in het eventdocument.

Zie ook

• MSAL React Type-aliassen