Guia de Migração do MSAL v1 para @azure/msal-react e @azure/msal-browser

Este artigo fornece uma visão geral sobre a migração do MSAL v1 para @azure/msal-react e @azure/msal-browser. Recomendamos a migração para melhorar o desempenho e garantir melhor segurança com o fluxo de código de autorização com PKCE e Acesso Condicional. Além disso, há melhor suporte para aplicações de página única.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente
• Uma aplicação existente registada no seu tenant do Microsoft Entra.

Atualizar o registo da sua aplicação

A biblioteca @azure/msal-react é um wrapper em torno de @azure/msal-browser, que implementa o Fluxo de Código de Autorização com PKCE. Esta é uma atualização significativa em relação à biblioteca MSAL v1, que implementa o Fluxo Implícito.

Terá de criar um novo registo de aplicação ou atualizar uma existente para usar o novo redirectUri tipo "SPA". Consulte a Aplicação de página única: Registo da aplicação para mais informações.

A instalação de @azure/msal-react e @azure/msal-browser

Ambos @azure/msal-react e a sua dependência do mesmo nível @azure/msal-browser podem ser instalados a partir do npm. É importante desinstalar o teu antigo pacote MSAL. Abra um terminal e execute os seguintes comandos.

npm uninstall msal
npm install @azure/msal-react @azure/msal-browser

Atualização de react-aad-msal

Se a sua aplicação utiliza atualmente o React Microsoft Entra MSAL para autenticação e pretende migrar para @azure/msal-react esta secção, irá detalhar as diferenças entre as duas bibliotecas e algumas das alterações que precisa de fazer. React Microsoft Entra MSAL é uma biblioteca de terceiros, e o MSAL React foi desenvolvido de raiz; poderá haver alguns casos extremos que não estejam cobertos ou não sejam suportados pelo MSAL React.

As seguintes são funcionalidades suportadas react-aad-msal que não são suportadas em @azure/msal-react:

• Verificação da expiração do IdToken antes de renderizar componentes protegidos e atualização automática dos IdTokens expirados
• Suporte imediato para a store do Redux (alternativa abaixo)

Para outros casos possíveis com react-aad-msal, mas que já não são possíveis com @azure/msal-react, abra uma issue no repositório GitHub microsoft-authentication-library-for-js.

Inicialização

Em react-aad-msal, inicializa a sua instância do MSAL criando um objeto MsalAuthProvider, que é posteriormente passado ao componente AzureAD.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);

Em @azure/msal-react, inicializa a tua instância MSAL usando PublicClientApplication exportado de @azure/msal-browser, que é depois passada ao componente MsalProvider exportado de @azure/msal-react. As opções de configuração são em grande parte semelhantes entre msal e @azure/msal-browser, no entanto, pode consultar o tipo de configuração para as opções de configuração mais atualizadas.

Os parâmetros authenticationParameters e options utilizados em react-aad-msal não são utilizados em @azure/msal-react, embora seja possível obter funcionalidade semelhante em componentes individuais. Isto será explicado mais adiante neste documento.

@azure/msal-react utiliza a API de Contexto do React para disponibilizar PublicClientApplication e o estado de autenticação em toda a árvore de componentes.

import { PublicClientApplication } from "@azure/msal-browser";
import { MsalProvider } from "@azure/msal-react";

const pca = new PublicClientApplication(config);

function App() {
    return (
        <MsalProvider instance={pca}>
            <YourAppComponents />
        </MsalProvider>
    );
}

Notas gerais sobre o MsalProvider componente:

• Todos os componentes que necessitam de acesso ao estado de autenticação ou ganchos/componentes expostos por @azure/msal-react devem ter uma MsalProvider posição superior na árvore de componentes, pelo que recomenda-se que MsalProvider sejam renderizados o mais próximo possível da raiz.
• A tua aplicação não deve renderizar mais do que 1 MsalProvider componente em cada página.
• Não recomendamos inicializar PublicClientApplication dentro de um componente devido à possibilidade de re-renderizações

Proteger os seus componentes

Em react-aad-msal, os componentes são protegidos utilizando o componente AzureAD ou o HOC withAuthentication, que envolve o seu componente com AzureAD nos bastidores. O AzureAD componente só renderizará os componentes filhos se um utilizador estiver autenticado e, opcionalmente, iniciará um login se nenhum utilizador estiver autenticado. As opções usadas para iniciar sessão (por exemplo, Scopes, se deve usar popup ou redirecionar, etc.) são especificadas anteriormente, ao criar a authProvider prop.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);

function App() {
    return (
        <AzureAD provider={authProvider} forceLogin={true}>
            <span>Only authenticated users can see me.</span>
        </AzureAD>
    );
}

@azure/msal-react, por outro lado, dá aos programadores mais controlo sobre o que querem mostrar a quem.

• O AuthenticatedTemplate componente irá renderizar as crianças se um utilizador for autenticado
• O UnauthenticatedTemplate componente irá renderizar as crianças se o utilizador não estiver autenticado
• O MsalAuthenticationTemplate componente iniciará automaticamente um login se um utilizador não estiver autenticado e depois renderizará filhos assim que o utilizador estiver autenticado.

import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import { MsalProvider, AuthenticatedTemplate, UnauthenticatedTemplate, MsalAuthenticationTemplate } from "@azure/msal-react";

const pca = new PublicClientApplication(config);

function App() {
    return (
        <MsalProvider instance={pca}>
            <AuthenticatedTemplate>
                <span>Only authenticated users can see me.</span>
            </AuthenticatedTemplate>
            <UnauthenticatedTemplate>
                <span>Only unauthenticated users can see me.</span>
            </UnauthenticatedTemplate>
            <MsalAuthenticationTemplate interactionType={InteractionType.Popup} authenticationRequest={request}>
                <span>Only authenticated users can see me. Unauthenticated users will get a popup asking them to login first.</span>
            </MsalAuthenticationTemplate>
        </MsalProvider>
    );
}

Além disso, se preferir uma abordagem baseada em hooks, @azure/msal-react disponibiliza vários hooks que pode utilizar para obter resultados semelhantes. Estes são apenas alguns exemplos básicos, e pode consultar hooks do MSAL React para obter mais informações.

import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import { MsalProvider, useIsAuthenticated, useMsalAuthentication } from "@azure/msal-react";

const pca = new PublicClientApplication(config);

function App() {
    return (
        <MsalProvider instance={pca}>
            <ExampleComponent />
        </MsalProvider>
    );
}

function ExampleComponent() {
    const isAuthenticated = useIsAuthenticated();
    const { error } = useMsalAuthentication(InteractionType.Popup, request); // Will initiate a popup login if user is unauthenticated

    if (isAuthenticated) {
        return <span>Only authenticated users can see me.</span>
    } else if (error) {
        return <span>An error occurred during login!</span>
    } else {
        return <span>Only unauthenticated users can see me.</span>
    }
}

Aquisição de um token de acesso

react-aad-msal expõe um getAccessToken método que pode usar para obter um token de acesso antes de chamar uma API.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);
const accessToken = authProvider.getAccessToken();

Ao usar @azure/msal-react e @azure/msal-browser, irá chamar acquireTokenSilent na instância PublicClientApplication.

Se precisares de obter um token de acesso dentro de um componente ou hook que viva por baixo MsalProvider , podes usar o useMsal hook para obter os objetos de que precisas.

import { useState } from "react";
import { useMsal } from "@azure/msal-react";
import { InteractionRequiredAuthError } from "@azure/msal-browser";

function useAccessToken() {
    const { instance, accounts } = useMsal();
    const [accessToken, setAccessToken] = useState(null);

    if (accounts.length > 0) {
        const request = {
            scopes: ["User.Read"],
            account: accounts[0]
        };
        instance.acquireTokenSilent(request).then(response => {
            setAccessToken(response.accessToken);
        }).catch(error => {
            // acquireTokenSilent can fail for a number of reasons, fallback to interaction
            if (error instanceof InteractionRequiredAuthError) {
                instance.acquireTokenPopup(request).then(response => {
                    setAccessToken(response.accessToken);
                });
            }
        });
    }

    return accessToken;
}

Se precisares de obter um token de acesso fora do contexto de MsalProvider podes usar a PublicClientApplication instância diretamente e chamar getAllAccounts() para obter o objeto da conta.

O exemplo abaixo mostra a inicialização de PublicClientApplication para fins de demonstração. PublicClientApplication deve ser inicializado apenas uma vez por carregamento de página e deve usar a mesma instância aqui que fornece para MsalProvider.

import { PublicClientApplication } from "@azure/msal-browser";

const pca = new PublicClientApplication(config);
const accounts = pca.getAllAccounts();

async function getAccessToken() {
    if (accounts.length > 0) {
        const request = {
            scopes: ["User.Read"],
            account: accounts[0]
        }
        const accessToken = await pca.acquireTokenSilent(request).then((response) => {
            return response.accessToken;
        }).catch(error => {
            // Do not fallback to interaction when running outside the context of MsalProvider. Interaction should always be done inside context.
            console.log(error);
            return null;
        });

        return accessToken;
    }

    return null;
}

Aquisição de um ID token

react-aad-msal expôs uma getIdToken função para obter ou renovar um idToken.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);
const token = await authProvider.getIdToken();
const idToken = token.idToken.rawIdToken;

Também pode estar familiarizado com o padrão de pedir o seu clientId como único escopo para recuperar um idToken. Este já não é um padrão suportado em @azure/msal-browser.

Em @azure/msal-react e @azure/msal-browser todas as chamadas de token devolverão tanto um token de acesso como um token id, e todas as renovações de token de acesso também renovarão o token id.

Se precisares de obter um id token dentro de um componente ou hook que viva por baixo MsalProvider , podes usar o useMsal hook para obter os objetos de que precisas.

import { useState } from "react";
import { useMsal } from "@azure/msal-react";

function useIdToken() {
    const { instance, accounts } = useMsal();
    const [idToken, setIdToken] = useState(null);

    if (accounts.length > 0) {
        const request = {
            scopes: ["openid"],
            account: accounts[0]
        };
        instance.acquireTokenSilent(request).then(response => {
            setIdToken(response.idToken);
        }).catch(error => {
            // acquireTokenSilent can fail for a number of reasons, fallback to interaction
            if (error instanceof InteractionRequiredAuthError) {
                instance.acquireTokenPopup(request).then(response => {
                    setIdToken(response.idToken);
                });
            }
        });
    }

    return idToken;
}

Se precisares de obter um id token fora do contexto de MsalProvider podes usar a PublicClientApplication instância diretamente e chamar getAllAccounts() para obter o objeto da conta.

O exemplo abaixo mostra a inicialização de PublicClientApplication para fins de demonstração. PublicClientApplication deve ser inicializado apenas uma vez por carregamento de página e deve usar a mesma instância aqui que fornece para MsalProvider.

import { PublicClientApplication } from "@azure/msal-browser";

const pca = new PublicClientApplication(config);
const accounts = pca.getAllAccounts();

async function getIdToken() {
    if (accounts.length > 0) {
        const request = {
            scopes: ["openid"],
            account: accounts[0]
        }
        const idToken = await pca.acquireTokenSilent(request).then((response) => {
            return response.idToken;
        }).catch (error => {
            // Do not fallback to interaction when running outside the context of MsalProvider. Interaction should always be done inside context.
            console.log(error);
            return null;
        });

        return idToken
    }

    return null;
}

Atualização da integração da loja redux / reação a eventos

react-aad-msal fornecia integração imediata com uma store Redux, através do envio de ações quando ocorriam eventos como início de sessão ou fim de sessão. @azure/msal-react não oferece esta funcionalidade, no entanto, funcionalidades semelhantes podem ser alcançadas usando a API de eventos exposta por @azure/msal-browser.

Pode registar um callback de evento que será chamado sempre que um evento for transmitido (por exemplo, LOGIN_SUCCESS). A tua função de callback pode inspecionar o evento e fazer algo com a carga útil. Se quiser continuar a usar a sua loja redux existente, pode registar um callback de evento que despacha ações para a sua loja.

import { PublicClientApplication, EventType } from "@azure/msal-browser";
import { store } from "your-redux-store-implementation";

const msalInstance = new PublicClientApplication(config);

const callbackId = msalInstance.addEventCallback((message: EventMessage) => {
    if (message.eventType === EventType.LOGIN_SUCCESS) {
        store.dispatchAction({type: "AAD_LOGIN_SUCCESS", payload: message.payload});
    }
});

Os payloads podem variar entre a v1 de msal e @azure/msal-browser, pelo que poderá ser necessário fazer alguns ajustes se a sua aplicação depender de campos específicos ou da estrutura do objeto. A nossa documentação de tipos contém a lista mais atual de tipos de eventos e tipos de carga útil, e pode encontrar a correspondência entre os dois na documentação de eventos.

Consulte também

• Tipos Alternativos do MSAL React