Hooks no MSAL React

Hooks no MSAL React são funções que permitem usar os recursos do MSAL e os métodos de estado e de ciclo de vida do React dentro de componentes funcionais. Os ganchos principais são useAccount, useIsAuthenticated, useMsal e useMsalAuthentication. Este artigo orientará você sobre como usar cada um desses ganchos.

Gancho useAccount

O useAccount hook aceita um parâmetro accountIdentifier e retorna o objeto AccountInfo para essa conta, se ela estiver conectada, ou null, se não estiver. Se nenhum identificador de conta for fornecido, a conta ativa atual será retornada. Você pode ler mais sobre o objeto AccountInfo retornado na documentação @azure/msal-browser, em APIs de Login no 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);

Gancho useIsAuthenticated

O useIsAuthenticated hook retorna um booleano indicando se uma conta está conectada ou não. Opcionalmente, ele aceita um accountIdentifier objeto que você pode fornecer se precisar saber se uma conta específica está ou não conectado.

Verificar se alguma conta está atualmente conectada

O trecho de código a seguir usa o hook useIsAuthenticated do pacote @azure/msal-react. Em seguida, o componente renderiza condicionalmente uma mensagem com base em se um usuário está conectado ou não.

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 se um usuário específico está conectado

O snippet a seguir usa o useIsAuthenticated gancho do @azure/msal-react pacote para determinar se um usuário específico está conectado.

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

Gancho useMsal

O hook useMsal retorna o contexto. Isso pode ser usado se você precisar de acesso à instância PublicClientApplication, à lista de contas atualmente conectadas ou se precisar saber se um login ou outra interação está em andamento.

Observação: o valor accounts retornado por useMsal só será atualizado quando contas forem adicionadas ou removidas e não será atualizado quando as declarações forem atualizadas. Se você precisar de acesso a declarações atualizadas para o usuário atual, use o hook useAccount ou a chamada acquireTokenSilent em vez disso.

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
}

Gancho useMsalAuthentication

O useMsalAuthentication gancho iniciará um logon se um usuário ainda não estiver conectado, caso contrário, ele tentará adquirir um token.

Parâmetros de Entrada

Há alguns parâmetros de entrada diferentes que você pode fornecer ao useMsalAuthentication gancho:

• interactionType - (None, Popup, Redirect ou Silent) especifica como você deseja adquirir tokens ou logon quando a interação é necessária (observe que a opção Silent tem algumas considerações adicionais explicadas abaixo).
• objeto de solicitação - (opcional) especifica parâmetros adicionais a serem usados na chamada de logon ou de aquisição de token
• accountIdentifiers – objeto usado para informar ao hook de qual usuário ele deve fazer login ou adquirir tokens

Propriedades de retorno

• resultado - O resultado do último login bem-sucedido ou da última aquisição de token. Observe que esse gancho só tenta fazer logon ou adquirir tokens automaticamente uma vez. É responsabilidade da aplicação chamar a função login ou acquireToken, quando necessário, para atualizar esse valor.
• erro – se ocorrer um erro durante a aquisição de logon ou token, essa propriedade conterá informações sobre o erro. Você pode usar a função login ou acquireToken retornada por este hook para tentar novamente. A propriedade error será limpa no próximo login bem-sucedido ou aquisição bem-sucedida de token.
• login – função que pode ser usada para tentar novamente um logon com falha. As result propriedades e as error propriedades serão atualizadas.
• acquireToken – função que pode ser usada para obter um novo token de acesso antes de chamar uma API protegida. As result propriedades e as error propriedades serão atualizadas.

Passar o tipo de interação "Silenciosa" chamará ssoSilent, o qual tentará abrir um iframe oculto e reutilizar uma sessão existente com o Microsoft Entra ID. Isso não funcionará em navegadores que bloqueiam cookies de terceiros, como o Safari. Além disso, o objeto de solicitação é necessário ao usar o tipo "Silencioso". Se você já tiver as informações de login do usuário, poderá passar qualquer um dos parâmetros opcionais loginHint ou sid para fazer login em uma conta específica. Observação: há considerações adicionais – ao usar ssoSilent sem fornecer nenhuma informação sobre a sessão do usuário.

ssoSilent exemplo

Se você usar o modo silencioso, deverá detectar quaisquer erros e tentar um login interativo 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;

Exemplo de usuário específico

Se você quiser garantir que um usuário específico esteja conectado, forneça um 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 também

Você pode encontrar a documentação para as APIs PublicClientApplication expostas no Navegador MSAL:

• APIs de logon
• API de logout
• AcquireToken APIs
• APIs de contas
• APIs de evento