Hooks in MSAL React

Hooks in MSAL React sind Funktionen, mit denen Sie MSAL-Features und React-Status- und Lebenszyklusmethoden innerhalb funktionaler Komponenten verwenden können. Die wichtigsten Hooks sind useAccount, useIsAuthenticated, useMsal und useMsalAuthentication. In diesem Artikel erfahren Sie, wie Sie jeden dieser Hooks verwenden.

useAccount Haken

Der useAccount-Hook akzeptiert den Parameter accountIdentifier und gibt das Objekt AccountInfo für dieses Konto zurück, wenn es angemeldet ist, oder null, wenn dies nicht der Fall ist. Wenn kein Kontobezeichner angegeben wird, wird das aktuelle aktive Konto zurückgegeben. Weitere Informationen zu dem von AccountInfo zurückgegebenen Objekt finden Sie in der @azure/msal-browser-Dokumentation unter Login APIs in MSAL.

const accountIdentifier = {
    localAccountId: "example-local-account-identifier",
    homeAccountId: "example-home-account-identifier"
    username: "example-username" // We do not recommend relying only on username
}

const accountInfo = useAccount(accountIdentifier);

useIsAuthenticated Haken

Der useIsAuthenticated Hook gibt einen booleschen Wert zurück, der angibt, ob ein Konto angemeldet ist. Sie akzeptiert optional ein accountIdentifier Objekt, das Sie angeben können, wenn Sie wissen müssen, ob ein bestimmtes Konto angemeldet ist.

Ermitteln, ob ein Konto zurzeit angemeldet ist

Der folgende Codeausschnitt verwendet den useIsAuthenticated Hook aus dem @azure/msal-react Paket. Die Komponente rendert dann bedingt eine Nachricht basierend darauf, ob ein Benutzer angemeldet ist oder nicht.

import React from 'react';
import { useIsAuthenticated } from "@azure/msal-react";

export function App() {
    const isAuthenticated = useIsAuthenticated();

    return (
        <React.Fragment>
            <p>Anyone can see this paragraph.</p>
            {isAuthenticated && (
                <p>At least one account is signed in!</p>
            )}
            {!isAuthenticated && (
                <p>No users are signed in!</p>
            )}
        </React.Fragment>
    );
}

Ermitteln, ob ein bestimmter Benutzer angemeldet ist

Der folgende Codeausschnitt verwendet den useIsAuthenticated Hook aus dem @azure/msal-react Paket, um zu ermitteln, ob ein bestimmter Benutzer angemeldet ist.

import React from 'react';
import { useIsAuthenticated } from "@azure/msal-react";

export function App() {
    const accountIdentifiers = {
        localAccountId: "example-local-account-identifier",
        homeAccountId: "example-home-account-identifier",
        username: "example-username"
    }

    const isAuthenticated = useIsAuthenticated(accountIdentifiers);

    return (
        <React.Fragment>
            <p>Anyone can see this paragraph.</p>
            {isAuthenticated && (
                <p>User with specified localAccountId is signed in!</p>
            )}
            {!isAuthenticated && (
                <p>User with specified localAccountId is not signed in!</p>
            )}
        </React.Fragment>
    );
}

useMsal Haken

Der useMsal Hook gibt den Kontext zurück. Dies kann verwendet werden, wenn Sie Zugriff auf die PublicClientApplication Instanz benötigen, die Liste der aktuell angemeldeten Konten oder wenn Sie wissen müssen, ob eine Anmeldung oder eine andere Interaktion gerade ausgeführt wird.

Hinweis: Der von useMsal zurückgegebene accounts-Wert wird nur aktualisiert, wenn Konten hinzugefügt oder entfernt werden, nicht jedoch, wenn Anspruchsinformationen aktualisiert werden. Wenn Sie Zugriff auf aktualisierte Claims für den aktuellen Benutzer benötigen, verwenden Sie den useAccount-Hook oder rufen Sie stattdessen acquireTokenSilent auf.

import { useState, useEffect } from "react";
import { useMsal } from "@azure/msal-react";
import { InteractionStatus } from "@azure/msal-browser";

const { instance, accounts, inProgress } = useMsal();
const [loading, setLoading] = useState(false);
const [apiData, setApiData] = useState(null);

useEffect(() => {
    if (!loading && inProgress === InteractionStatus.None && accounts.length > 0) {
        if (apiData) {
            // Skip data refresh if already set - adjust logic for your specific use case
            return;
        }

        const tokenRequest = {
            account: accounts[0], // This is an example - Select account based on your app's requirements
            scopes: ["User.Read"]
        }

        // Acquire an access token
        instance.acquireTokenSilent(tokenRequest).then((response) => {
            // Call your API with the access token and return the data you need to save in state
            callApi(response.accessToken).then((data) => {
                setApiData(data);
                setLoading(false);
            });
        }).catch(async (e) => {
            // Catch interaction_required errors and call interactive method to resolve
            if (e instanceof InteractionRequiredAuthError) {
                await instance.acquireTokenRedirect(tokenRequest);
            }

            throw e;
        });
    }
}, [inProgress, accounts, instance, loading, apiData]);

if (loading || inProgress === InteractionStatus.Login) {
    // Render loading component
} else if (apiData) {
    // Render content that depends on data from your API
}

useMsalAuthentication Haken

Der useMsalAuthentication Hook initiiert eine Anmeldung, wenn ein Benutzer noch nicht angemeldet ist, andernfalls versucht er, ein Token zu erwerben.

Eingabeparameter

Es gibt ein paar verschiedene Eingabeparameter, die Sie für den useMsalAuthentication Hook bereitstellen können:

  • interactionType – (None, Popup, Redirect oder Silent) gibt an, wie Sie Token abrufen oder sich anmelden möchten, wenn eine Interaktion erforderlich ist (beachten Sie, dass die Option "Silent" einige zusätzliche Überlegungen erläutert hat).
  • request object - (optional) gibt zusätzliche Parameter an, die vom Anmelde- oder Tokenakquisitionsaufruf verwendet werden sollen.
  • accountIdentifiers – Objekt wird verwendet, um den Hook mitzuteilen, für welchen Benutzer es sich anmelden oder Token erwerben soll

Rückgabeeigenschaften

  • ergebnis – Das Ergebnis des letzten erfolgreichen Anmelde- oder Tokenerwerbs. Beachten Sie, dass dieser Hook nur ein einziges Mal versucht, sich automatisch anzumelden oder Token zu erwerben. Die Anwendung ist dafür verantwortlich, bei Bedarf die Funktion login oder acquireToken aufzurufen, um diesen Wert zu aktualisieren.
  • error – Wenn während des Anmelde- oder Tokenerwerbs ein Fehler auftritt, enthält diese Eigenschaft Informationen zum Fehler. Sie können die loginacquireToken von diesem Hook zurückgegebenen Funktionen verwenden, um den Vorgang zu wiederholen. Die error Eigenschaft wird beim nächsten erfolgreichen Anmelde- oder Tokenerwerb gelöscht.
  • login - Funktion, die zum Wiederholen einer fehlgeschlagenen Anmeldung verwendet werden kann. Die Eigenschaften result und error werden aktualisiert.
  • acquireToken - Funktion, die verwendet werden kann, um ein neues Zugriffstoken abzurufen, bevor eine geschützte API aufgerufen wird. Die Eigenschaften result und error werden aktualisiert.

Durch Übergabe des Interaktionstyps „Silent“ wird ssoSilent aufgerufen, wodurch versucht wird, ein verstecktes IFrame zu öffnen und eine vorhandene Sitzung mit Microsoft Entra ID wiederzuverwenden. Dies funktioniert nicht in Browsern, die Drittanbietercookies wie Safari blockieren. Darüber hinaus ist das Anforderungsobjekt erforderlich, wenn der Typ "Silent" verwendet wird. Wenn Sie bereits über die Anmeldeinformationen des Benutzers verfügen, können Sie entweder die optionalen Parameter loginHint oder sid übergeben, um ein bestimmtes Konto anzumelden. Hinweis: Bei Verwendung ohne Angabe von Informationen zur Sitzung des Benutzers gibt es ssoSilent.

ssoSilent Beispiel

Wenn Sie den stillen Modus verwenden, sollten Sie alle Fehler abfangen und ersatzweise eine interaktive Anmeldung versuchen.

import React, { useEffect } from 'react';

import { AuthenticatedTemplate, UnauthenticatedTemplate, useMsal, useMsalAuthentication } from "@azure/msal-react";
import { InteractionType, InteractionRequiredAuthError } from '@azure/msal-browser';

function App() {
    const request = {
        loginHint: "name@example.com",
        scopes: ["User.Read"]
    }
    const { login, result, error } = useMsalAuthentication(InteractionType.Silent, request);

    useEffect(() => {
        if (error instanceof InteractionRequiredAuthError) {
            login(InteractionType.Popup, request);
        }
    }, [error]);

    const { accounts } = useMsal();

    return (
        <React.Fragment>
            <p>Anyone can see this paragraph.</p>
            <AuthenticatedTemplate>
                <p>Signed in as: {accounts[0]?.username}</p>
            </AuthenticatedTemplate>
            <UnauthenticatedTemplate>
                <p>No users are signed in!</p>
            </UnauthenticatedTemplate>
        </React.Fragment>
    );
}

export default App;

Beispiel für einen bestimmten Benutzer

Wenn Sie sicherstellen möchten, dass ein bestimmter Benutzer angemeldet ist, geben Sie ein Objekt an accountIdentifiers .

import React from 'react';
import { useMsalAuthentication } from "@azure/msal-react";
import { InteractionType } from '@azure/msal-browser';

export function App() {
    const accountIdentifiers = {
        username: "example-username"
    }
    const request = {
        loginHint: "example-username",
        scopes: ["User.Read"]
    }
    const { login, result, error } = useMsalAuthentication(InteractionType.Popup, request, accountIdentifiers);

    return (
        <React.Fragment>
            <p>Anyone can see this paragraph.</p>
            <AuthenticatedTemplate username="example-username">
                <p>Example user is signed in!</p>
            </AuthenticatedTemplate>
            <UnauthenticatedTemplate username="example-username">
                <p>Example user is not signed in!</p>
            </UnauthenticatedTemplate>
        </React.Fragment>
    );
}

Siehe auch

Die Dokumentation zu den APIs, die PublicClientApplication im MSAL-Browser verfügbar macht, finden Sie hier:

  • Last updated on