Ganchos no MSAL React

Hooks no MSAL React são funções que permitem utilizar as funcionalidades do MSAL e os métodos do React relacionados com o estado e o ciclo de vida dentro de componentes funcionais. Os principais ganchos são useAccount, useIsAuthenticated, useMsal, e useMsalAuthentication. Este artigo vai guiá-lo sobre como usar cada um destes ganchos.

useAccount gancho

O useAccount hook aceita o parâmetro accountIdentifier e devolve o objeto AccountInfo dessa conta se tiver sessão iniciada ou null se não tiver sessão iniciada. Se não for fornecido o identificador da conta, a conta ativa atual será devolvida. Pode ler mais sobre o objeto AccountInfo devolvido na documentação @azure/msal-browser, em APIs de início de sessão 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);

useIsAuthenticated gancho

O useIsAuthenticated hook devolve um valor booleano que indica se uma conta tem ou não sessão iniciada. Aceita opcionalmente um objeto accountIdentifier que pode facultar se precisar de saber se uma conta específica está autenticada ou não.

Determinar se alguma conta tem sessão iniciada neste momento

O excerto seguinte utiliza o hook useIsAuthenticated do pacote @azure/msal-react. O componente apresenta depois, de forma condicional, uma mensagem consoante o utilizador tenha ou não sessão iniciada.

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 utilizador específico tem sessão iniciada

O excerto de código seguinte utiliza o hook useIsAuthenticated do pacote @azure/msal-react para determinar se um utilizador específico tem sessão iniciada.

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 gancho

O useMsal hook devolve o contexto. Isto pode ser usado se precisar de acesso à instância PublicClientApplication, à lista de contas com sessão iniciada atualmente ou se precisar de saber se há um início de sessão ou outra interação em curso.

Nota: O valor accounts devolvido por useMsal só será atualizado quando as contas forem adicionadas ou removidas, e não será atualizado quando as declarações forem atualizadas. Se precisar de aceder a claims atualizadas do utilizador atual, utilize o hook useAccount ou chame 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
}

useMsalAuthentication gancho

O useMsalAuthentication hook iniciará um login se o utilizador ainda não estiver iniciado sessão, caso contrário tentará adquirir um token.

Parâmetros de entrada

Existem vários parâmetros de entrada que pode fornecer ao hook useMsalAuthentication:

• interactionType - (Nenhum, Popup, Redirecionamento ou Silencioso) especifica como gostaria de adquirir tokens ou iniciar sessão quando for necessária interação (note que a opção Silenciosa tem algumas considerações adicionais explicadas abaixo).
• Objeto de Pedido - (Opcional) especifica parâmetros adicionais a serem usados pelo login ou chamada de aquisição de token
• accountIdentifiers - o objeto é usado para indicar ao hook para qual utilizador deve iniciar sessão ou adquirir tokens

Propriedades de retorno

• resultado - O resultado do último login bem-sucedido ou aquisição de token. Note que este gancho só tenta iniciar sessão ou adquirir tokens automaticamente uma vez. É da responsabilidade da aplicação chamar a função login ou acquireToken quando necessário, para atualizar este valor.
• Erro - Se ocorrer um erro durante o login ou aquisição do token, esta propriedade conterá informação sobre o erro. Pode utilizar as funções login ou acquireToken devolvidas por este hook para tentar novamente. A propriedade error será limpa no próximo início de sessão bem-sucedido ou na próxima aquisição de token.
• login - função que pode ser usada para tentar novamente um login falhado. As result propriedades e error 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 error serão atualizadas.

Ao passar o tipo de interação "Silencioso", chama ssoSilent que tenta abrir um iframe oculto e reutilizar uma sessão existente com o Microsoft Entra ID. Isto não funciona em navegadores que bloqueiam cookies de terceiros, como o Safari. Além disso, o objeto de pedido é obrigatório ao usar o tipo "Silencioso". Se já tiver as informações de início de sessão do utilizador, pode passar os parâmetros opcionais loginHint ou sid para iniciar sessão numa conta específica. Nota: existem considerações adicionais – ao usar ssoSilent sem fornecer qualquer informação sobre a sessão do utilizador.

ssoSilent exemplo

Se utilizares o modo silencioso, deves detetar quaisquer erros e tentar um início de sessão 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 específico de utilizador

Se quiser garantir que um utilizador específico está logado, 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

Pode encontrar documentação para as APIs PublicClientApplication expostas no MSAL Browser:

• Login APIs
• Logout API
• AcquireToken APIs
• APIs de contas
• APIs de eventos