Guía de migración de MSAL v1 a @azure/msal-react y @azure/msal-browser

En este artículo se proporciona información general sobre la migración de MSAL v1 a @azure/msal-react y @azure/msal-browser. Se recomienda la migración para mejorar el rendimiento y mejorar la seguridad con el flujo de código de autorización con PKCE y el acceso condicional. Además, hay mejor compatibilidad con aplicaciones de página única.

Prerequisites

• Una cuenta de Azure con una suscripción activa. Cree su cuenta de forma gratuita.
• Una aplicación existente registrada en su inquilino de Microsoft Entra.

Actualización del registro de la aplicación

La biblioteca @azure/msal-react, es un envoltorio de @azure/msal-browser que implementa el flujo de código de autorización con PKCE. Se trata de una actualización significativa de la biblioteca MSAL v1 que implementa el flujo implícito.

Deberá crear un nuevo registro de aplicación o actualizar uno existente para usar el nuevo redirectUri tipo "SPA". Consulte Aplicación de página única: Registro de aplicaciones para obtener más información.

Instalando @azure/msal-react y @azure/msal-browser

Tanto @azure/msal-react como su dependencia par @azure/msal-browser se pueden instalar desde npm. Es importante desinstalar el paquete MSAL antiguo. Abra un terminal y ejecute los siguientes comandos.

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

Actualización desde react-aad-msal

Si la aplicación usa actualmente React Microsoft Entra MSAL para la autenticación y quiere migrar a @azure/msal-react esta sección describirá las diferencias entre las dos bibliotecas y algunos de los cambios que debe realizar. React Microsoft Entra MSAL es una biblioteca de terceros y MSAL React se creó desde cero, puede haber algunos casos perimetrales que no están cubiertos o no compatibles con MSAL React.

A continuación se muestran las características admitidas en react-aad-msal las que no se admiten en @azure/msal-react:

• Comprobación de la expiración de IdToken antes de representar componentes protegidos y actualización automática de IdTokens expirados
• Compatibilidad nativa con Redux Store (alternativa más abajo)

Para otros casos que son posibles con react-aad-msal pero que ya no lo son con @azure/msal-react, abra una incidencia en el repositorio de GitHub microsoft-authentication-library-for-js.

Inicialización

En react-aad-msal inicializas tu instancia de MSAL creando un objeto MsalAuthProvider, que más adelante se pasa al componente AzureAD.

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

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

En @azure/msal-react, inicializas la instancia de MSAL usando PublicClientApplication, exportado desde @azure/msal-browser, que luego se pasa al componente MsalProvider, exportado desde @azure/msal-react. Las opciones de configuración son muy similares entre msal y @azure/msal-browser, pero puede hacer referencia al tipo de configuración para obtener las opciones de configuración más actualizadas.

Los authenticationParameters parámetros y options utilizados en react-aad-msal no se usan en @azure/msal-react, aunque se puede lograr una funcionalidad similar en componentes individuales. Esto se explicará más adelante en este documento.

@azure/msal-react usa la API de contexto de React para poner PublicClientApplication y el estado de autenticación a disposición de todo el árbol 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 generales sobre el MsalProvider componente:

• Todos los componentes que necesitan acceso al estado de autenticación o a los enlaces o componentes expuestos por @azure/msal-react deben tener un MsalProvider nivel superior en el árbol de componentes, por lo que se recomienda MsalProvider que se represente lo más cerca posible de la raíz.
• La aplicación no debe representar más de 1 MsalProvider componente en ninguna página determinada.
• No recomendamos inicializar PublicClientApplication dentro de un componente por la posibilidad de que se produzcan nuevos renderizados

Protección de los componentes

En react-aad-msal, los componentes se protegen mediante el componente AzureAD o el HOC withAuthentication, que envuelve el componente con AzureAD internamente. El AzureAD componente solo representará los componentes secundarios si un usuario se autentica y, opcionalmente, iniciará un inicio de sesión si no se autentica ningún usuario. Las opciones utilizadas para el inicio de sesión (p. ej., Scopes, si se debe usar popup o redirect, etc.) se especifican antes, al crear la propiedad authProvider.

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-reactPor otro lado, proporciona a los desarrolladores más control sobre lo que quieren mostrar a quién.

• El componente AuthenticatedTemplate renderizará el contenido hijo si el usuario está autenticado.
• El componente UnauthenticatedTemplate renderizará el contenido hijo si el usuario no está autenticado.
• El componente MsalAuthenticationTemplate iniciará sesión automáticamente si el usuario no está autenticado y, a continuación, renderizará los elementos secundarios una vez que el usuario esté 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>
    );
}

Además, si prefiere tomar un enfoque @azure/msal-react basado en enlaces proporciona varios enlaces que puede usar para lograr resultados similares. Estos son solo algunos ejemplos básicos, y puedes consultar hooks de React de MSAL para obtener más información.

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

Adquisición de un token de acceso

react-aad-msal expone un getAccessToken método que puede usar para obtener un token de acceso antes de llamar a una API.

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

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

Al usar @azure/msal-react y @azure/msal-browser, llamará a acquireTokenSilent en la instancia de PublicClientApplication.

Si necesita obtener un token de acceso dentro de un componente o un enlace que reside en MsalProvider , puede usar el useMsal enlace para obtener los objetos que necesita.

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

Si necesita obtener un token de acceso fuera del contexto de MsalProvider, puede usar directamente la instancia PublicClientApplication y llamar a getAllAccounts() para obtener el objeto de cuenta.

El ejemplo siguiente muestra la inicialización de PublicClientApplication con fines de demostración. PublicClientApplication solo debería inicializarse una vez por carga de la página y aquí debería usar la misma instancia que se pasa a 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;
}

Adquisición de un token de identificador

react-aad-msal expone una getIdToken función para obtener o renovar un idToken.

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

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

Puede que también le resulte familiar el patrón de solicitar su clientId como único ámbito para obtener un idToken. Ya no es un patrón admitido en @azure/msal-browser.

En @azure/msal-react y @azure/msal-browser todas las llamadas de token devolverán un token de acceso y un token de identificador y todas las renovaciones de tokens de acceso también renovarán el token de identificador.

Si necesita obtener un token de identificador dentro de un componente o un enlace que resida bajo MsalProvider usted puede usar el useMsal enlace para obtener los objetos que necesita.

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

Si necesita obtener un token de ID fuera del contexto de MsalProvider, puede usar directamente la instancia PublicClientApplication y llamar a getAllAccounts() para obtener el objeto de cuenta.

En el ejemplo siguiente se muestra la inicialización de PublicClientApplication con fines de demostración. PublicClientApplication solo debe inicializarse una vez por carga de página y debes usar aquí la misma instancia que proporcionas a 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;
}

Actualización de la integración con el store de Redux / respuesta a eventos

react-aad-msal proporcionaba integración lista para usar con un store de Redux al despachar acciones cuando se producían eventos como el inicio o cierre de sesión. @azure/msal-react no proporciona esta característica, sin embargo, se puede lograr una funcionalidad similar mediante la API de eventos expuesta por @azure/msal-browser.

Puede registrar una función de devolución de llamada para eventos que se invocará cada vez que se emita un evento (por ejemplo, LOGIN_SUCCESS). La función de devolución de llamada puede inspeccionar el evento y hacer algo con la carga. Si desea seguir utilizando su almacén de Redux existente, puede registrar una función de devolución de llamada de evento que despache acciones a su almacén.

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

Las cargas pueden diferir entre msal v1 y @azure/msal-browser , por lo tanto, es posible que tenga que realizar algunos ajustes si la aplicación se basa en campos específicos o en la forma del objeto. Nuestros typedocs contienen la lista más reciente de tipos de eventos y tipos de carga útil, y puede consultar la correspondencia entre ambos en la documentación de eventos.

Consulte también

• Alias de tipo react de MSAL