Hooks in MSAL React

Gli hook in MSAL React sono funzioni che consentono di usare le funzionalità MSAL e i metodi di stato e ciclo di vita React all'interno di componenti funzionali. Gli hook principali sono useAccount, useIsAuthenticated, useMsale useMsalAuthentication. Questo articolo illustra come usare ognuno di questi hook.

useAccount hook

L'hook useAccount accetta un accountIdentifier parametro e restituisce l'oggetto AccountInfo per tale account se è connesso o null in caso contrario. Se non viene specificato alcun identificatore di account, verrà restituito l'account attivo corrente. Per altre informazioni sull'oggetto AccountInfo restituito nella @azure/msal-browser documentazione, vedere API di accesso 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 hook

L'hook useIsAuthenticated restituisce un valore booleano che indica se un account è connesso o meno. Facoltativamente accetta un accountIdentifier oggetto che è possibile fornire se è necessario sapere se un account specifico è connesso o meno.

Determinare se un account è attualmente connesso

Il frammento di codice seguente usa l'hook useIsAuthenticated del @azure/msal-react pacchetto. Il componente visualizza quindi un messaggio in modo condizionale, a seconda che un utente abbia effettuato l'accesso oppure no.

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

Determinare se un utente specifico ha eseguito l'accesso

Il frammento di codice seguente usa l'hook useIsAuthenticated del @azure/msal-react pacchetto per determinare se un utente specifico ha eseguito l'accesso.

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 hook

L'hook useMsal restituisce il contesto. Questa opzione può essere usata se è necessario accedere all'istanza PublicClientApplication, all'elenco degli account attualmente connessi oppure sapere se è attualmente in corso un accesso o un'altra interazione.

Nota: il accounts valore restituito da useMsal aggiornerà solo quando gli account vengono aggiunti o rimossi e non verranno aggiornati quando le attestazioni vengono aggiornate. Se hai bisogno di accedere ai claim aggiornati per l'utente corrente, usa l'hook useAccount o chiama invece 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 Gancio

L'hook useMsalAuthentication avvierà l'accesso se l'utente non ha già effettuato l'accesso; in caso contrario, tenterà di ottenere un token.

Parametri di input

Esistono alcuni parametri di input diversi che è possibile fornire all'hook useMsalAuthentication :

  • interactionType : (Nessuno, Popup, Reindirizzamento o Invisibile all'utente) specifica come acquisire i token o l'accesso quando è necessaria l'interazione (si noti che l'opzione Silent include alcune considerazioni aggiuntive illustrate di seguito).
  • oggetto richiesta - (facoltativo) specifica i parametri aggiuntivi da utilizzare per la chiamata di accesso o di acquisizione del token
  • accountIdentifiers - l'oggetto viene usato per indicare all'hook per quale utente deve effettuare l'accesso o ottenere i token

Proprietà di restituzione

  • result - Il risultato dell'ultimo accesso riuscito o dell'ultima acquisizione del token. Si noti che questo hook tenta solo di accedere o acquisire automaticamente i token una volta. È responsabilità dell'applicazione chiamare la funzione login o acquireToken, se necessario, per aggiornare questo valore.
  • error : se si verifica un errore durante l'acquisizione di un account di accesso o di token, questa proprietà conterrà informazioni sull'errore. È possibile usare le login funzioni o acquireToken restituite da questo hook per riprovare. La proprietà error verrà cancellata al successivo accesso riuscito o alla successiva acquisizione riuscita del token.
  • login - funzione che può essere utilizzata per ripetere un accesso non riuscito. Le result proprietà e error verranno aggiornate.
  • acquireToken : funzione che può essere usata per ottenere un nuovo token di accesso prima di chiamare un'API protetta. Le result proprietà e error verranno aggiornate.

Passando il tipo di interazione "Silent", verrà chiamato ssoSilent, che tenta di aprire un iframe nascosto e riutilizzare una sessione esistente con Microsoft Entra ID. Questo non funzionerà nei browser che bloccano cookie di terze parti come Safari. Inoltre, l'oggetto richiesta è necessario quando si usa il tipo "Silent". Se si dispone già delle informazioni di accesso dell'utente, è possibile passare i loginHint parametri facoltativi o sid per accedere a un account specifico. Nota: quando si usa senza fornire informazioni sulla sessione dell'utente, è necessario tenere presenti ssoSilent.

ssoSilent esempio

Se usi la modalità silent, dovresti intercettare eventuali errori e tentare un accesso interattivo come soluzione di ripiego.

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;

Esempio di utente specifico

Se si vuole assicurarsi che un utente specifico sia connesso, specificare un accountIdentifiers oggetto .

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

Vedere anche

È possibile trovare la documentazione per le API PublicClientApplication esposte in MSAL Browser:

  • Last updated on