Hooks in MSAL React

Hooks in MSAL React zijn functies waarmee u MSAL-functies en React-status- en levenscyclusmethoden binnen functionele onderdelen kunt gebruiken. De hoofdhaken zijn useAccount, useIsAuthenticated, useMsalen useMsalAuthentication. In dit artikel wordt uitgelegd hoe u elk van deze hooks kunt gebruiken.

useAccount Haak

De useAccount hook accepteert een accountIdentifier parameter en retourneert het AccountInfo object voor dat account als het is aangemeld of null als het niet is. Als er geen account-id is opgegeven, wordt het huidige actieve account geretourneerd. Je kunt meer lezen over het AccountInfo object dat wordt geretourneerd in de @azure/msal-browser-documentatie in Login-API's 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 Haak

De useIsAuthenticated hook retourneert een Booleaanse waarde die aangeeft of er al dan niet een account is aangemeld. Het neemt optioneel een accountIdentifier object aan dat u kunt opgeven als u wilt weten of een specifieke account is aangemeld.

Bepalen of er momenteel een account is aangemeld

In het volgende codefragment wordt de useIsAuthenticated hook van het @azure/msal-react pakket gebruikt. Het onderdeel geeft vervolgens voorwaardelijk een bericht weer op basis van of een gebruiker is aangemeld of niet.

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

Bepalen of een specifieke gebruiker is aangemeld

In het volgende codefragment wordt de useIsAuthenticated hook van het @azure/msal-react pakket gebruikt om te bepalen of een specifieke gebruiker is aangemeld.

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 Haak

De useMsal hook geeft de context terug. Dit kan worden gebruikt als u toegang nodig hebt tot het PublicClientApplication exemplaar, de lijst met accounts die momenteel zijn aangemeld of als u wilt weten of er momenteel een aanmelding of andere interactie wordt uitgevoerd.

Opmerking: de accounts-waarde die door useMsal wordt geretourneerd, wordt alleen bijgewerkt wanneer accounts worden toegevoegd of verwijderd, en wordt niet bijgewerkt wanneer claims worden bijgewerkt. Als u toegang nodig hebt tot bijgewerkte claims voor de huidige gebruiker, gebruikt u in plaats daarvan de hook useAccount of roept u acquireTokenSilent aan.

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 Haak

De useMsalAuthentication hook start een aanmelding als een gebruiker nog niet is aangemeld, anders wordt geprobeerd een token te verkrijgen.

Invoerparameters

Er zijn enkele verschillende invoerparameters die u aan de useMsalAuthentication hook kunt opgeven:

  • interactionType - (None, Popup, Redirect of Silent) geeft aan hoe u tokens wilt verkrijgen of aanmelden wanneer interactie is vereist (let op: de optie Achtergrond bevat enkele extra overwegingen die hieronder worden uitgelegd).
  • aanvraagobject - (optioneel) geeft aanvullende parameters op die moeten worden gebruikt door de aanroep voor aanmelding of tokenverwerving
  • accountIdentifiers - object wordt gebruikt om de hook te vertellen voor welke gebruiker het zich moet aanmelden of tokens moet verkrijgen voor

Eigenschappen retourneren

  • resultaat : het resultaat van de laatste geslaagde aanmelding of tokenverwerving. Deze hook probeert zich slechts één keer aan te melden of tokens te verkrijgen. Het is de verantwoordelijkheid van de toepassing om de login of acquireToken functie, indien nodig, aan te roepen om deze waarde bij te werken.
  • fout : als er een fout optreedt tijdens het aanmelden of verkrijgen van tokens, bevat deze eigenschap informatie over de fout. U kunt de login of acquireToken functies die door deze hook worden geretourneerd, gebruiken om het opnieuw te proberen. De error eigenschap wordt gewist bij de volgende geslaagde aanmelding of tokenovername.
  • login - functie die kan worden gebruikt om een mislukte aanmelding opnieuw uit te voeren. De result en error eigenschappen worden bijgewerkt.
  • acquireToken - functie die kan worden gebruikt om een nieuw toegangstoken op te halen voordat u een beveiligde API aanroept. De result en error eigenschappen worden bijgewerkt.

Als u het interactietype 'Silent' opgeeft, wordt ssoSilent aangeroepen. Deze probeert een verborgen iframe te openen en een bestaande sessie bij Microsoft Entra ID te hergebruiken. Dit werkt niet in browsers die cookies van derden blokkeren, zoals Safari. Daarnaast is het requestobject vereist wanneer u het type "Silent" gebruikt. Als u de aanmeldingsgegevens van de gebruiker al hebt, kunt u de loginHint of sid optionele parameters doorgeven om een specifiek account aan te melden. Opmerking: er zijn aanvullende aandachtspunten - bij gebruik van ssoSilent zonder informatie over de sessie van de gebruiker te verstrekken.

ssoSilent voorbeeld

Als u een stille aanmelding gebruikt, moet u eventuele fouten afhandelen en als alternatief interactief aanmelden proberen.

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;

Voorbeeld van specifieke gebruiker

Als u ervoor wilt zorgen dat een specifieke gebruiker is aangemeld, geeft u een accountIdentifiers object op.

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

Zie ook

U vindt documentatie voor de API's PublicClientApplication die beschikbaar worden gesteld in MSAL Browser:

  • Last updated on