Haki w rozwiązaniu MSAL React

Hooks in MSAL React to funkcje, które umożliwiają korzystanie z funkcji biblioteki MSAL oraz metod stanu i cyklu życia react wewnątrz składników funkcjonalnych. Główne hooki to useAccount, useIsAuthenticated, useMsal i useMsalAuthentication. W tym artykule dowiesz się, jak używać każdego z tych haków.

useAccount Hak

Hook useAccount przyjmuje parametr accountIdentifier i zwraca obiekt AccountInfo dla tego konta, jeśli konto jest zalogowane, lub null, jeśli nie jest. Jeśli nie podano identyfikatora konta, zostanie zwrócone bieżące aktywne konto . Możesz przeczytać więcej o obiekcie AccountInfo, zwracanym w dokumentacji @azure/msal-browser, w temacie Interfejsy API logowania w bibliotece 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 Hak

Hook useIsAuthenticated zwraca wartość logiczną wskazującą, czy konto jest zalogowane, czy nie. Opcjonalnie akceptuje accountIdentifier obiekt, który można podać, jeśli musisz wiedzieć, czy jest zalogowane określone konto.

Ustal, czy jakiekolwiek konto jest obecnie zalogowane

Poniższy fragment kodu używa hooka useIsAuthenticated z pakietu @azure/msal-react. Składnik następnie warunkowo renderuje komunikat na podstawie tego, czy użytkownik jest zalogowany, czy nie.

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

Określanie, czy określony użytkownik jest zalogowany

Poniższy fragment kodu używa hooka useIsAuthenticated z pakietu @azure/msal-react, aby sprawdzić, czy konkretny użytkownik jest zalogowany.

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 Hak

Hook useMsal zwraca kontekst. Można tego użyć, jeśli potrzebujesz dostępu do instancji PublicClientApplication, listy kont, na które użytkownik jest obecnie zalogowany, lub wiedzieć, czy logowanie albo inna interakcja właśnie trwa.

Uwaga: wartość zwracana przez useMsal w accounts będzie aktualizowana tylko wtedy, gdy konta zostaną dodane lub usunięte, i nie będzie aktualizowana, gdy oświadczenia zostaną zaktualizowane. Jeśli potrzebujesz dostępu do zaktualizowanych claimów dla bieżącego użytkownika, użyj hooka useAccount lub zamiast tego wywołaj acquireTokenSilent.

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 Hak

Hak useMsalAuthentication zainicjuje logowanie, jeśli użytkownik nie jest jeszcze zalogowany, w przeciwnym razie podejmie próbę uzyskania tokenu.

Parametry wejściowe

Istnieje kilka różnych parametrów wejściowych, które można podać do haka useMsalAuthentication :

• interactionType — (Brak, Wyskakujące, Przekierowanie lub Dyskretne) określa, jak chcesz uzyskać tokeny lub zalogować się, gdy jest wymagana interakcja (pamiętaj, że opcja Dyskretna ma kilka dodatkowych zagadnień opisanych poniżej).
• obiekt żądania — (opcjonalnie) określa dodatkowe parametry, które mają być używane przez wywołanie logowania lub pozyskiwania tokenu
• accountIdentifiers — obiekt służący do określenia, dla którego użytkownika hook powinien wykonać logowanie lub pobrać tokeny

Właściwości zwracane

• result — wynik ostatniego pomyślnego logowania lub pozyskiwania tokenu. Należy pamiętać, że ten hak podejmuje automatyczną próbę zalogowania się lub uzyskania tokenów tylko raz. To aplikacja odpowiada za wywołanie funkcji login lub acquireToken w razie potrzeby, aby zaktualizować tę wartość.
• error — jeśli podczas logowania lub pozyskiwania tokenu wystąpi błąd, ta właściwość będzie zawierać informacje o błędzie. Możesz użyć funkcji login lub acquireToken, zwróconych przez ten hook, aby ponowić próbę. Właściwość error zostanie wyczyszczona przy następnym pomyślnym logowaniu lub uzyskaniu tokenu.
• login - funkcja, która może służyć do ponawiania próby nieudanego logowania. Właściwości result i error zostaną zaktualizowane.
• acquireToken — funkcja, która może służyć do uzyskiwania nowego tokenu dostępu przed wywołaniem chronionego interfejsu API. Właściwości result i error zostaną zaktualizowane.

Przekazanie typu interakcji „Cicha” spowoduje wywołanie metody ssoSilent, która próbuje otworzyć ukrytą ramkę iframe i ponownie użyć istniejącej sesji z Microsoft Entra ID. Nie będzie to działać w przeglądarkach, które blokują pliki cookie innych firm, takie jak Safari. Ponadto obiekt żądania jest wymagany w przypadku używania typu "Dyskretny". Jeśli masz już dane logowania użytkownika, możesz przekazać jeden z opcjonalnych parametrów loginHint lub sid, aby zalogować konkretne konto. Uwaga: istnieją dodatkowe kwestie — podczas korzystania z ssoSilent bez podawania jakichkolwiek informacji o sesji użytkownika.

przykład ssoSilent

Jeśli używasz trybu cichego, należy przechwycić wszelkie błędy i w razie niepowodzenia spróbować zalogować się interaktywnie.

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;

Przykład określonego użytkownika

Jeśli chcesz upewnić się, że określony użytkownik jest zalogowany, podaj accountIdentifiers obiekt.

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

Zobacz także

Dokumentację interfejsów API udostępnianych przez PublicClientApplication w bibliotece MSAL Browser można znaleźć tutaj:

• API logowania
• Interfejs API wylogowywania
• Interfejsy API AcquireToken
• Interfejsy API kont
• Interfejsy API zdarzeń