Migrationshandbuch von MSAL v1 zu @azure/msal-react und @azure/msal-browser

Dieser Artikel enthält eine Übersicht über die Migration von MSAL v1 zu @azure/msal-react und @azure/msal-browser. Wir empfehlen die Migration für verbesserte Leistung und bessere Sicherheit mit dem Autorisierungscodefluss mit PKCE und bedingtem Zugriff. Darüber hinaus gibt es eine bessere Unterstützung für einzelseitige Anwendungen.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement. Kostenlos ein Konto erstellen
• Eine vorhandene Anwendung, die in Ihrem Microsoft Entra Mandanten registriert ist.

Aktualisieren der App-Registrierung

Die @azure/msal-react-Bibliothek ist ein Wrapper für @azure/msal-browser, das den Autorisierungscode-Flow mit PKCE implementiert. Dies ist ein bedeutendes Update aus der MSAL v1-Bibliothek, die den impliziten Fluss implementiert.

Sie müssen eine neue App-Registrierung erstellen oder eine vorhandene app aktualisieren, um den neuen redirectUri Typ "SPA" zu verwenden. Weitere Informationen finden Sie in der Einzelseitenanwendung: App-Registrierung .

Installation von @azure/msal-react und @azure/msal-browser

Sowohl @azure/msal-react als auch die Peer-Abhängigkeit @azure/msal-browser können über npm installiert werden. Es ist wichtig, Ihr altes MSAL-Paket zu deinstallieren. Öffnen Sie ein Terminal, und führen Sie die folgenden Befehle aus.

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

Upgrade von react-aad-msal

Wenn Ihre App derzeit React Microsoft Entra MSAL für die Authentifizierung verwendet und Sie zu @azure/msal-react diesem Abschnitt migrieren möchten, werden die Unterschiede zwischen den beiden Bibliotheken und einigen der Änderungen beschrieben, die Sie vornehmen müssen. React Microsoft Entra MSAL ist eine Bibliothek eines Drittanbieters, und MSAL React wurde von Grund auf neu entwickelt. Daher kann es einige Randfälle geben, die von MSAL React nicht abgedeckt oder nicht unterstützt werden.

Die folgenden Funktionen werden in react-aad-msal unterstützt, in @azure/msal-react jedoch nicht:

• Überprüfen des Ablaufs von IdToken vor dem Rendern geschützter Komponenten und der automatischen Aktualisierung abgelaufener IdTokens
• Direkte Unterstützung für den Redux-Store (Alternative weiter unten)

Öffnen Sie in anderen Fällen, die mit react-aad-msal möglich waren, mit @azure/msal-react jedoch nicht mehr, ein Issue im microsoft-authentication-library-for-js-GitHub-Repository.

Initialisierung

In react-aad-msal initialisieren Sie Ihre MSAL-Instanz, indem Sie ein MsalAuthProvider-Objekt erstellen, das später an die AzureAD-Komponente übergeben wird.

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

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

In @azure/msal-react initialisieren Sie Ihre MSAL-Instanz unter Verwendung von PublicClientApplication, das aus @azure/msal-browser exportiert wird und dann an die MsalProvider-Komponente übergeben wird, die aus @azure/msal-react exportiert wird. Die Konfigurationsoptionen sind weitgehend ähnlich zwischen msal und @azure/msal-browser, sie können jedoch auf den Konfigurationstyp für die aktuellsten Konfigurationsoptionen verweisen.

Die in react-aad-msal verwendeten Parameter authenticationParameters und options werden in @azure/msal-react nicht verwendet, obwohl eine ähnliche Funktionalität bei einzelnen Komponenten erzielt werden kann. Dies wird weiter unten in diesem Dokument erläutert.

@azure/msal-react verwendet die React-Kontext-API, um PublicClientApplication und den Authentifizierungsstatus in Ihrem gesamten Komponentenbaum verfügbar zu machen.

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

Allgemeine Hinweise zur MsalProvider Komponente:

• Alle Komponenten, die Zugriff auf den Authentifizierungsstatus oder auf von @azure/msal-react bereitgestellte Hooks/Komponenten benötigen, müssen weiter oben im Komponentenbaum ein MsalProvider haben. Daher wird empfohlen, MsalProvider so nah wie möglich an der Wurzel zu rendern.
• Ihre App sollte nicht mehr als 1 MsalProvider Komponente auf einer bestimmten Seite rendern.
• Wir empfehlen nicht, PublicClientApplication innerhalb einer Komponente zu initialisieren, da es zu Neurenderings kommen kann.

Schützen Ihrer Komponenten

In react-aad-msal werden Komponenten durch die AzureAD Komponente oder das withAuthentication HOC geschützt, das Ihre Komponente intern mit AzureAD umgibt. Die AzureAD Komponente rendert nur untergeordnete Komponenten, wenn ein Benutzer authentifiziert ist, und initiiert optional eine Anmeldung, wenn kein Benutzer authentifiziert ist. Die für die Anmeldung verwendeten Optionen (z. B. Berechtigungsbereiche, ob ein Popup oder eine Umleitung verwendet werden soll usw.) werden zuvor beim Erstellen des authProvider-Prop angegeben.

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-reactauf der anderen Seite bietet Entwicklern mehr Kontrolle darüber, was sie für wen anzeigen möchten.

• Die AuthenticatedTemplate Komponente rendert untergeordnete Elemente, wenn ein Benutzer authentifiziert ist
• Die UnauthenticatedTemplate-Komponente rendert Kindelemente, wenn ein Benutzer nicht authentifiziert ist.
• Die MsalAuthenticationTemplate-Komponente startet automatisch einen Anmeldevorgang, falls ein Benutzer nicht authentifiziert ist, und rendert anschließend die Kindelemente, sobald der Benutzer authentifiziert ist.

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

Wenn Sie einen Hooks-basierten Ansatz @azure/msal-react bevorzugen, bieten Sie außerdem mehrere Hooks, die Sie verwenden können, um ähnliche Ergebnisse zu erzielen. Dies sind nur einige grundlegende Beispiele, und Sie können auf MSAL React-Hooks verweisen, um weitere Informationen zu erhalten.

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

Abrufen eines Zugriffstokens

react-aad-msal macht eine getAccessToken Methode verfügbar, mit der Sie ein Zugriffstoken abrufen können, bevor Sie eine API aufrufen.

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

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

Wenn Sie @azure/msal-react und @azure/msal-browser verwenden, rufen Sie acquireTokenSilent für die Instanz PublicClientApplication auf.

Wenn Sie innerhalb einer Komponente oder eines Hooks, der sich unter MsalProvider befindet, ein Zugriffstoken abrufen müssen, können Sie den Hook useMsal verwenden, um die benötigten Objekte zu erhalten.

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

Wenn Sie ein Zugriffstoken außerhalb des Kontexts MsalProvider abrufen müssen, können Sie die PublicClientApplication Instanz direkt verwenden und aufrufen getAllAccounts() , um das Kontoobjekt abzurufen.

Das folgende Beispiel zeigt die Initialisierung von PublicClientApplication zu Demonstrationszwecken. PublicClientApplication sollte nur einmal pro Seitenladung initialisiert werden, und Sie sollten hier dieselbe Instanz verwenden, die Sie an MsalProvider übergeben.

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

Anfordern eines ID-Tokens

react-aad-msal hat eine getIdToken Funktion bereitgestellt, um ein idToken abzurufen oder zu erneuern.

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

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

Möglicherweise sind Sie auch mit dem Muster vertraut, `clientId` als einzigen Bereich anzufordern, um ein idToken abzurufen. Dies ist kein unterstütztes Muster mehr in @azure/msal-browser.

In @azure/msal-react und @azure/msal-browser alle Tokenaufrufe geben sowohl ein Zugriffstoken als auch ein ID-Token zurück, und alle Zugriffstokenverlängerungen erneuern auch das ID-Token.

Wenn Sie innerhalb einer Komponente oder eines Hooks, die sich unter MsalProvider befinden, ein ID-Token abrufen müssen, können Sie den Hook useMsal verwenden, um die Objekte abzurufen, die Sie benötigen.

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

Wenn Sie ein ID-Token außerhalb des Kontexts MsalProvider abrufen müssen, können Sie die PublicClientApplication Instanz direkt verwenden und aufrufen getAllAccounts() , um das Kontoobjekt abzurufen.

Das folgende Beispiel zeigt zu Demonstrationszwecken die Initialisierung von PublicClientApplication. PublicClientApplication sollte nur einmal pro Seitenaufruf initialisiert werden, und Sie sollten hier dieselbe Instanz verwenden, die Sie MsalProvider bereitstellen.

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

Aktualisieren der Redux Store-Integration/Reaktion auf Ereignisse

react-aad-msal stellte eine sofort einsatzbereite Integration mit einem Redux-Store bereit, indem Aktionen ausgelöst wurden, wenn Ereignisse wie An- oder Abmeldung auftraten. @azure/msal-react stellt diese Funktion jedoch nicht bereit; eine ähnliche Funktionalität kann jedoch über die von @azure/msal-browser bereitgestellte Event-API erreicht werden.

Sie können einen Ereignisrückruf registrieren, der jedes Mal aufgerufen wird, wenn ein Ereignis übertragen wird (z. B. LOGIN_SUCCESS). Ihre Callback-Funktion kann das Ereignis untersuchen und etwas mit der Payload tun. Wenn Sie Ihren vorhandenen Redux-Store weiterhin verwenden möchten, können Sie einen Event-Callback registrieren, der Actions an Ihren Store weiterleitet.

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

Die Nutzlasten können sich zwischen msal v1 unterscheiden, @azure/msal-browser sodass Sie möglicherweise einige Anpassungen vornehmen müssen, wenn Ihre Anwendung auf bestimmte Felder oder die Objektform basiert. Unsere Typedocs enthalten die aktuellste Liste der Ereignistypen und Nutzlasttypen , und Sie finden die Zuordnung zwischen den beiden im Ereignisdokument.

Siehe auch

• MSAL React-Typaliasen