Migrálási útmutató az MSAL v1-ről a @azure/msal-react és @azure/msal-browser verziókra

Ez a cikk áttekintést nyújt az MSAL v1-ről a @azure/msal-react és @azure/msal-browser verzióra való migrálásról. A jobb teljesítmény és a nagyobb biztonság érdekében javasoljuk a migrálást a PKCE-vel és a feltételes hozzáféréssel rendelkező engedélyezési kódfolyamattal. Emellett jobb egyoldalas alkalmazástámogatás is elérhető.

Prerequisites

Az alkalmazásregisztráció frissítése

A @azure/msal-react kódtár egy, a @azure/msal-browser köré épülő burkolókönyvtár, amely a PKCE-vel működő engedélyezési kódfolyamatot valósítja meg. Ez egy jelentős frissítés az MSAL v1 kódtárból, amely implementálja az implicit folyamatot.

Létre kell hoznia egy új alkalmazásregisztrációt, vagy frissítenie kell egy meglévőt az új redirectUri "SPA" típus használatához. További információért tekintse meg az egyoldalas alkalmazást: Alkalmazásregisztráció .

A @azure/msal-react és @azure/msal-browser telepítése

Mind a @azure/msal-react, mind a társfüggősége, a @azure/msal-browser is telepíthető az npm-ből. Fontos, hogy távolítsa el a régi MSAL-csomagot. Nyisson meg egy terminált, és futtassa a következő parancsokat.

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

Frissítés erről: react-aad-msal

Ha az alkalmazás jelenleg a React Microsoft Entra MSAL-t használja a hitelesítéshez, és erre a szakaszra szeretne migrálni@azure/msal-react, felvázolja a két kódtár és a szükséges módosítások közötti különbségeket. A React Microsoft Entra MSAL egy harmadik féltől származó kódtár, és az MSAL React az alapoktól épült, lehetnek olyan peremes esetek, amelyeket az MSAL React nem fed le vagy nem támogat.

Az alábbi funkciók támogatottak a(z) react-aad-msal esetében, de a(z) @azure/msal-react esetében nem:

  • IdToken-lejárat ellenőrzése a védett összetevők megjelenítése előtt & a lejárt IdTokens automatikus frissítése
  • A Redux Store dobozon kívüli támogatása (az alábbi alternatíva)

Az egyéb olyan esetekben, amelyek a react-aad-msal használatával lehetségesek, de a @azure/msal-react használatával már nem, nyisson egy hibajegyet a microsoft-authentication-library-for-js GitHub-tárhelyen.

Inicializálás

A(z) react-aad-msal elemben az MSAL-példányt egy MsalAuthProvider objektum létrehozásával inicializálod, amelyet később átadsz a(z) AzureAD összetevőnek.

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

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

A(z) @azure/msal-react fájlban a(z) @azure/msal-browser által exportált PublicClientApplication használatával inicializálja az MSAL-példányt, amelyet ezután a(z) @azure/msal-react által exportált MsalProvider komponensnek ad át. A konfigurációs beállítások nagyrészt hasonlóak a(z) msal és @azure/msal-browser között, azonban a legfrissebb konfigurációs beállításokat a Konfiguráció típusa című résznél találja meg.

A(z) react-aad-msal-ben használt authenticationParameters és options paraméterek nincsenek használatban a(z) @azure/msal-react-ban, bár hasonló funkció az egyes összetevőknél elérhető. Ezt a dokumentum későbbi részében ismertetjük.

@azure/msal-react a React Context API használatával teszi elérhetővé a PublicClientApplication-t és a hitelesítési állapotot a teljes komponensfában.

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

Általános megjegyzések az MsalProvider összetevőről:

  • Minden olyan összetevő esetében, amelynek hozzá kell férnie a hitelesítési állapothoz vagy a @azure/msal-react által elérhetővé tett hookokhoz/komponensekhez, szükséges, hogy a komponensfában felette legyen egy MsalProvider, ezért javasolt, hogy a MsalProvider a lehető legközelebb legyen renderelve a gyökérhez.
  • Az alkalmazás egyetlen oldalon sem jeleníthet meg 1-nél MsalProvider több összetevőt.
  • Nem javasoljuk a(z) PublicClientApplication inicializálását egy komponensen belül az újrarenderelések lehetősége miatt.

Az összetevők védelme

A react-aad-msal esetében az összetevők a AzureAD összetevő vagy a withAuthentication HOC használatával védhetők, amely a háttérben a AzureAD elemmel burkolja az összetevőt. Az AzureAD összetevő csak akkor jeleníti meg a gyermekösszetevőket, ha a felhasználó hitelesítése megtörtént, és ha nincs felhasználó hitelesítése, szükség esetén kezdeményezi a bejelentkezést. A bejelentkezéshez használt beállításokat (például a hatóköröket, hogy előugró ablakot vagy átirányítást használjon-e stb.) már korábban, a authProvider prop létrehozásakor kell megadni.

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-reactugyanakkor a fejlesztők jobban szabályozhatják, hogy kinek mit szeretnének megjeleníteni.

  • Az AuthenticatedTemplate összetevő gyermekeket jelenít meg, ha a felhasználó hitelesítése megtörtént
  • Az UnauthenticatedTemplate összetevő gyermekeket jelenít meg, ha egy felhasználó nincs hitelesítve
  • Az MsalAuthenticationTemplate összetevő automatikusan kezdeményezi a bejelentkezést, ha a felhasználó hitelesítése nem történik meg, majd gyermekeket jelenít meg a felhasználó hitelesítése után.
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>
    );
}

Emellett, ha inkább hookokra épülő megközelítést választ, a @azure/msal-react több olyan hookot is biztosít, amelyekkel hasonló eredményeket érhet el. Ezek csak néhány alapvető példa, további információkért pedig lásd az MSAL React hookjai oldalt.

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

Hozzáférési jogkivonat beszerzése

react-aad-msal az API meghívása getAccessToken előtt egy hozzáférési jogkivonat beszerzésére használható metódust tesz elérhetővé.

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

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

A @azure/msal-react és a @azure/msal-browser használatakor a(z) PublicClientApplication példányon a acquireTokenSilent függvényt fogja meghívni.

Ha be kell szereznie egy hozzáférési jogkivonatot egy olyan összetevőben vagy horogban, amely alatt MsalProvider él, a useMsal horoggal lekérheti a szükséges objektumokat.

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

Ha a környezeten MsalProvider kívüli hozzáférési jogkivonatot kell beszereznie, használhatja közvetlenül a PublicClientApplication példányt, és meghívhatja getAllAccounts() a fiókobjektum lekéréséhez.

Important

Csak a(z) MsalProvider kontextusán kívül kísérelje meg a tokenek csendes beszerzését. Nem hívhat meg interaktív metódust (átirányítás vagy előugró ablak) a környezeten MsalProviderkívül.

Az alábbi példa a PublicClientApplication bemutatási célból történő inicializálását mutatja be. PublicClientApplication elemet oldalbetöltésenként csak egyszer szabad inicializálni, és itt ugyanazt a példányt kell használnia, amelyet a MsalProvider elemnek ad át.

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

Azonosító jogkivonat beszerzése

react-aad-msal egy függvényt getIdToken adott meg egy idToken lekéréséhez vagy megújításához.

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

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

Ismerős lehet az a minta is, amikor az Ön clientId értékét egyetlen hatókörként kéri le egy idToken lekéréséhez. Ez már nem támogatott minta a @azure/msal-browser.

A @azure/msal-react és @azure/msal-browser esetében minden tokenhívás egy hozzáférési tokent és egy azonosító tokent is visszaad, és a hozzáférési token minden megújítása az azonosító tokent is megújítja.

Ha be kell szereznie egy azonosító jogkivonatot egy olyan összetevőben vagy horogban, amely alatt MsalProvider él, a useMsal horoggal lekérheti a szükséges objektumokat.

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

Ha a(z) MsalProvider kontextusán kívül kell beszereznie egy azonosító tokent, közvetlenül használhatja a(z) PublicClientApplication példányt, és a fiókobjektum lekéréséhez meghívhatja a(z) getAllAccounts() metódust.

Important

Csak a(z) MsalProvider kontextusán kívül kísérelje meg a tokenek csendes beszerzését. Nem hívhat meg interaktív metódust (átirányítás vagy előugró ablak) a környezeten MsalProviderkívül.

Az alábbi példa a PublicClientApplication inicializálását mutatja be demonstrációs célból. A PublicClientApplication komponenst oldalbetöltéskor csak egyszer szabad inicializálni, és itt ugyanazt a példányt kell használnia, amelyet a MsalProvider számára biztosít.

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-integráció frissítése/ eseményekre való reagálás

react-aad-msal beépített integrációt biztosított egy Redux store-ral azáltal, hogy akciókat küldött, amikor például bejelentkezési vagy kijelentkezési események történtek. @azure/msal-react nem biztosítja ezt a funkciót, azonban hasonló funkcionalitás érhető el a @azure/msal-browser által elérhetővé tett esemény-API használatával.

Regisztrálhat egy eseményvisszahívást, amelyet minden esemény közvetítésekor meghívunk (például LOGIN_SUCCESS). A callback függvény megvizsgálhatja az eseményt, és valamilyen műveletet végezhet a payloaddal. Ha folytatni szeretné a meglévő redux áruház használatát, regisztrálhat egy eseményvisszahívást, amely műveleteket küld az áruházba.

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

Az adattartalmak eltérhetnek a msal v1 és a @azure/msal-browser között, ezért előfordulhat, hogy bizonyos módosításokat kell végrehajtania, ha az alkalmazása adott mezőkre vagy az objektum szerkezetére támaszkodik. A típusdokumok tartalmazzák az eseménytípusok és hasznos adattípusok legfrissebb listáját, és a kettő közötti megfeleltetést az eseménydokumentumban találja.

Lásd még

  • Last updated on