Hooks en MSAL React

Los enlaces en MSAL React son funciones que permiten usar características de MSAL y métodos de estado y ciclo de vida de React dentro de los componentes funcionales. Los principales puntos de enganche son useAccount, useIsAuthenticated, useMsal y useMsalAuthentication. Este artículo le guiará en el uso de cada uno de estos hooks.

useAccount enlace

El useAccount hook acepta el parámetro accountIdentifier y devuelve el objeto AccountInfo de esa cuenta si ha iniciado sesión o null si no ha iniciado sesión. Si no se proporciona ningún identificador de cuenta, se devolverá la cuenta activa actual. Puedes obtener más información sobre el objeto AccountInfo devuelto en la documentación de @azure/msal-browser en API de inicio de sesión en 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 enlace

El useIsAuthenticated enlace devuelve un valor booleano que indica si una cuenta ha iniciado sesión o no. Opcionalmente, acepta un accountIdentifier objeto que puede proporcionar si necesita saber si una cuenta específica ha iniciado sesión o no.

Determinar si hay alguna cuenta conectada actualmente

El siguiente fragmento de código usa el hook useIsAuthenticated del paquete @azure/msal-react. A continuación, el componente representa condicionalmente un mensaje en función de si un usuario ha iniciado sesión o 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>
    );
}

Determinar si un usuario específico ha iniciado sesión

El fragmento de código siguiente usa el useIsAuthenticated enlace del @azure/msal-react paquete para determinar si un usuario específico ha iniciado sesión.

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 enlace

El useMsal gancho devuelve el contexto. Esto puede usarse si necesita acceder a la instancia PublicClientApplication, a la lista de cuentas que han iniciado sesión actualmente o saber si hay un inicio de sesión u otra interacción en curso.

Nota: El valor accounts devuelto por useMsal solo se actualizará cuando se añadan o eliminen cuentas, y no se actualizará cuando se actualicen las reclamaciones. Si necesitas acceder a las reclamaciones actualizadas del usuario actual, utiliza el hook useAccount o llama a acquireTokenSilent en su lugar.

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 enlace

El useMsalAuthentication enlace iniciará un inicio de sesión si un usuario aún no ha iniciado sesión; de lo contrario, intentará adquirir un token.

Parámetros de entrada

Hay varios parámetros de entrada diferentes que puede pasar al hook useMsalAuthentication:

• interactionType : (None, Popup, Redirect o Silent) especifica cómo desea adquirir tokens o iniciar sesión cuando se requiera interacción (tenga en cuenta que la opción Silenciosa tiene algunas consideraciones adicionales que se explican a continuación).
• objeto de solicitud - (opcional) especifica parámetros adicionales que se utilizarán en la llamada de inicio de sesión o de obtención de tokens.
• accountIdentifiers : el objeto se usa para indicar al enlace qué usuario debe iniciar sesión o adquirir tokens para

Propiedades de retorno

• result - El resultado del último inicio de sesión realizado correctamente o de la última obtención de un token. Tenga en cuenta que este enlace solo intenta iniciar sesión o adquirir tokens automáticamente una vez. Es responsabilidad de la aplicación llamar a la login función o acquireToken , cuando sea necesario, para actualizar este valor.
• error : si se produce un error durante el inicio de sesión o la adquisición de tokens, esta propiedad contendrá información sobre el error. Puede usar las funciones login o acquireToken devueltas por este hook para reintentar. La propiedad error se borrará tras el siguiente inicio de sesión o adquisición de token que se realice con éxito.
• login : función que se puede usar para reintentar un inicio de sesión con errores. Las result propiedades y error se actualizarán.
• acquireToken : función que se puede usar para obtener un nuevo token de acceso antes de llamar a una API protegida. Las result propiedades y error se actualizarán.

Al pasar el tipo de interacción "Silent", se llamará a ssoSilent, que intenta abrir un iframe oculto y reutilizar una sesión existente con Microsoft Entra ID. Esto no funcionará en exploradores que bloqueen cookies de terceros como Safari. Además, el objeto de solicitud es necesario cuando se usa el tipo "Silencioso". Si ya tiene la información de inicio de sesión del usuario, puede pasar los parámetros opcionales loginHint o sid para iniciar sesión en una cuenta específica. Nota: hay consideraciones adicionales : al usar ssoSilent sin proporcionar información sobre la sesión del usuario.

ssoSilent ejemplo

Si usa el modo silencioso, debe detectar cualquier error e intentar un inicio de sesión interactivo como alternativa.

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;

Ejemplo de usuario específico

Si desea asegurarse de que un usuario específico ha iniciado sesión, proporcione un accountIdentifiers objeto .

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

Consulte también

Puede encontrar documentación sobre las API PublicClientApplication expuestas en MSAL Browser:

• API de inicio de sesión
• API de cierre de sesión
• API de AcquireToken
• API de cuenta
• API de eventos