Руководство по миграции из MSAL версии 1 в @azure/msal-react и @azure/msal-browser

В этой статье представлен обзор миграции из MSAL версии 1 в @azure/msal-react и @azure/msal-browser. Рекомендуется выполнить миграцию для повышения производительности и повышения безопасности потока кода авторизации с помощью PKCE и условного доступа. Кроме того, есть улучшена поддержка одностраничных приложений.

Необходимые условия

Обновление регистрации приложения

Библиотека @azure/msal-react — это оболочка, вокруг @azure/msal-browser которой реализуется поток кода авторизации с помощью PKCE. Это значительное обновление из библиотеки MSAL версии 1, которая реализует неявный поток.

Вам потребуется создать новую регистрацию приложения или обновить существующую, чтобы использовать новый тип redirectUri "SPA". Дополнительные сведения см. в приложении с одной страницей: регистрация приложений .

Установка @azure/msal-react и @azure/msal-browser

Как @azure/msal-react, так и его peer dependency @azure/msal-browser можно установить через npm. Важно удалить старый пакет MSAL. Откройте терминал и выполните следующие команды.

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

Обновление с react-aad-msal

Если приложение в настоящее время использует React Microsoft Entra MSAL для проверки подлинности, и вы хотите перейти к @azure/msal-react этому разделу, вы узнаете о различиях между двумя библиотеками и некоторыми изменениями, которые необходимо внести. Поскольку React Microsoft Entra MSAL является сторонней библиотекой, а MSAL React был создан с нуля, возможны некоторые крайние случаи, которые не охвачены или не поддерживаются в MSAL React.

Ниже перечислены функции, поддерживаемые в react-aad-msal, но не поддерживаемые в @azure/msal-react:

  • Проверка истечения срока действия IdToken перед отрисовкой защищенных компонентов и автоматическое обновление просроченных idTokens
  • Поддержка redux store (альтернатива ниже)

В других случаях, которые возможны с react-aad-msal, но больше невозможны с @azure/msal-react, создайте обращение в репозитории GitHub microsoft-authentication-library-for-js.

Инициализация

В react-aad-msal вы инициализируете экземпляр MSAL, создав объект MsalAuthProvider, который затем передается в компонент AzureAD.

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

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

В @azure/msal-react вы инициализируете свой экземпляр MSAL, используя PublicClientApplication, экспортированный из @azure/msal-browser, который затем передаётся в компонент MsalProvider, экспортируемый из @azure/msal-react. Параметры конфигурации в значительной степени похожи между msal и @azure/msal-browser, однако, можно ссылаться на тип конфигурации для наиболее актуальных параметров конфигурации.

Параметры authenticationParameters и options, используемые в react-aad-msal, не используются в @azure/msal-react, хотя аналогичной функциональности можно добиться для отдельных компонентов. Это будет описано далее в этом документе.

@azure/msal-react использует API контекста React, чтобы сделать PublicClientApplication и состояние аутентификации доступными во всём дереве компонентов.

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

Общие заметки о компоненте MsalProvider :

  • Все компоненты, которым нужен доступ к состоянию аутентификации или к хукам/компонентам, предоставляемым через @azure/msal-react, должны иметь MsalProvider выше по дереву компонентов, поэтому рекомендуется размещать MsalProvider как можно ближе к корню.
  • Приложение не должно отображать более 1 MsalProvider компонента на любой странице.
  • Мы не рекомендуем инициализировать PublicClientApplication внутри компонента из-за возможной повторной отрисовки

Защита компонентов

В react-aad-msal компоненты защищаются с помощью компонента AzureAD или HOC withAuthentication, который внутренне оборачивает ваш компонент в AzureAD. Компонент AzureAD будет отображать дочерние компоненты, только если пользователь аутентифицирован, и при необходимости может инициировать вход, если пользователь не аутентифицирован. Параметры, используемые для входа в систему (например, области действия, использование всплывающего окна или перенаправления и т. д.), задаются ранее — при создании свойства 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-reactс другой стороны, дает разработчикам больше контроля над тем, что они хотят отобразить кому.

  • Компонент AuthenticatedTemplate будет отображать дочерние элементы, если пользователь аутентифицирован
  • Компонент UnauthenticatedTemplate будет отображать дочерние элементы, если пользователь не прошел проверку подлинности
  • Компонент MsalAuthenticationTemplate автоматически выполняет вход, если пользователь не аутентифицирован, а затем отображает дочерние элементы после аутентификации пользователя.
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>
    );
}

Кроме того, если вы предпочитаете подход на основе хуков, @azure/msal-react предоставляет несколько хуков, которые можно использовать для получения аналогичных результатов. Это лишь несколько базовых примеров, а дополнительную информацию можно найти в хуках MSAL React.

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

Получение токена доступа

react-aad-msal предоставляет метод getAccessToken, который можно использовать для получения токена доступа перед вызовом API.

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

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

При использовании @azure/msal-react и @azure/msal-browser вы будете вызывать acquireTokenSilent для экземпляра PublicClientApplication.

Если вам нужно получить токен доступа внутри компонента или хука, который находится под MsalProvider, вы можете использовать хук useMsal, чтобы получить нужные вам объекты.

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

Если вам нужно получить токен доступа вне контекста MsalProvider, можно напрямую использовать экземпляр PublicClientApplication и вызвать getAllAccounts(), чтобы получить объект учетной записи.

Important

Выполняйте тихое получение токена только вне контекста MsalProvider. Не следует вызывать интерактивный метод (перенаправление или всплывающее окно) вне контекста MsalProvider.

В приведенном ниже примере показана инициализация PublicClientApplication в целях демонстрации. PublicClientApplication следует инициализировать только один раз при каждой загрузке страницы, и здесь нужно использовать тот же экземпляр, который вы передаёте в 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;
}

Получение токена идентификации

react-aad-msal предоставляет доступ к функции getIdToken для получения или обновления idToken.

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

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

Возможно, вам также знаком шаблон, при котором вы запрашиваете clientId как единственную область действия, чтобы получить idToken. Этот шаблон больше не поддерживается в @azure/msal-browser.

В @azure/msal-react и @azure/msal-browser все вызовы токенов будут возвращать как токен доступа, так и ID-токен, а все обновления токена доступа также будут обновлять ID-токен.

Если вам нужно получить токен ID внутри компонента или хука, который находится внутри MsalProvider, вы можете использовать хук useMsal, чтобы получить нужные объекты.

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

Если необходимо получить токен идентификатора вне контекста MsalProvider, можно напрямую использовать экземпляр PublicClientApplication и вызвать метод getAllAccounts(), чтобы получить объект учётной записи.

Important

Выполняйте тихое получение токена только вне контекста MsalProvider. Не следует вызывать интерактивный метод (перенаправление или всплывающее окно) вне контекста MsalProvider.

В приведенном ниже примере показана инициализация PublicClientApplication в демонстрационных целях. PublicClientApplication следует инициализировать только один раз при каждой загрузке страницы, и здесь следует использовать тот же экземпляр, который вы передаёте в 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;
}

Обновление интеграции с хранилищем redux / реагирование на события

react-aad-msal обеспечивал встроенную интеграцию с хранилищем Redux, отправляя действия при наступлении таких событий, как вход в систему и выход из неё. @azure/msal-react не предоставляет эту функцию, однако аналогичные функциональные возможности можно достичь с помощью API событий , предоставляемых @azure/msal-browser.

Вы можете зарегистрировать обратный вызов события, который будет вызываться при каждом трансляции события (например, LOGIN_SUCCESS). Ваша функция обратного вызова может проанализировать событие и выполнить какое-либо действие с полезной нагрузкой. Если вы хотите продолжить использование существующего хранилища redux, можно зарегистрировать обратный вызов событий, который отправляет действия в хранилище.

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

Содержимое может отличаться между msal v1 и @azure/msal-browser, поэтому вам может потребоваться внести некоторые изменения, если ваше приложение зависит от определённых полей или структуры объекта. Наша документация по типам содержит самый актуальный список типов событий и типов полезной нагрузки, а сопоставление между ними можно найти в документе по событиям.

См. также

  • Last updated on