Включение единого входа в надстройке Office с проверкой подлинности вложенного приложения

Статья
12/23/2024

Вы можете использовать библиотеку MSAL.js с проверкой подлинности вложенного приложения, чтобы использовать единый вход (SSO) из надстройки Office. Использование проверки подлинности вложенных приложений (NAA) обеспечивает ряд преимуществ по сравнению с потоком On-Behalf-Of (OBO).

Вам нужно использовать только библиотеку MSAL.js и не требуется getAccessToken функция в Office.js.
Вы можете вызывать службы, такие как Microsoft Graph, с маркером доступа из клиентского кода в качестве SPA. Сервер среднего уровня не требуется.
Для областей можно использовать добавочное и динамическое согласие.
Вам не нужно предварительно авторизовать узлы (например, Teams, Office) для вызова конечных точек.

Поддерживаемые учетные записи и узлы NAA

NAA поддерживает как учетные записи Майкрософт, так и Microsoft Entra ID (рабочие и учебные удостоверения). Он не поддерживает Azure Active Directory B2C для сценариев управления удостоверениями между клиентами. В следующей таблице объясняется текущая поддержка платформы. Платформы, перечисленные как общедоступные (общедоступная версия), готовы к использованию в рабочей среде в надстройке.

Приложение	Web	Windows	Mac	iOS/iPad	Android
Excel	В предварительной версии	В предварительной версии	В предварительной версии	В предварительной версии на iPad	Неприменимо
Outlook	Общедоступная версия	Общедоступная версия в текущем и ежемесячном корпоративном каналах, предварительная версия в Semi-Annual каналах	Общедоступная версия	Общедоступная версия (iOS)	Общедоступная версия
PowerPoint	В предварительной версии	В предварительной версии	В предварительной версии	В предварительной версии на iPad	Неприменимо
Word	В предварительной версии	В предварительной версии	В предварительной версии	В предварительной версии на iPad	Неприменимо

Важно!

Чтобы использовать NAA на платформах, которые по-прежнему находятся в предварительной версии (Word, Excel и PowerPoint), присоединитесь к программе предварительной оценки Microsoft 365 (https://insider.microsoft365.com/join) и выберите Текущий канал (предварительная версия). Не используйте NAA в рабочих надстройках для предварительных версий платформ. Мы приглашаем вас опробовать NAA в тестовой среде или среде разработки и приветствовать отзывы о вашем опыте через GitHub (см. раздел Отзывы в конце этой страницы).

Регистрация одностраничного приложения

Вам потребуется создать регистрацию microsoft приложение Azure для надстройки на портал Azure. Регистрация приложения должна иметь как минимум следующее:

Имя
Поддерживаемый тип учетной записи
Перенаправление SPA

Если надстройка требует дополнительной регистрации приложений помимо NAA и единого входа, см . раздел Одностраничные приложения: регистрация приложений.

Добавление доверенного брокера через перенаправление SPA

Чтобы включить NAA, регистрация приложения должна включать определенный URI перенаправления, чтобы указать платформа удостоверений Майкрософт, что ваша надстройка может быть брокером поддерживаемых узлов. URI перенаправления приложения должен иметь тип Одностраничное приложение и соответствовать следующей схеме.

brk-multihub://your-add-in-domain

Ваш домен должен включать только источник, а не его подпутьи. Например:

✔️ brk-multihub://localhost:3000
✔️ brk-multihub://www.contoso.com
❌ brk-multihub://www.contoso.com/go

Группы доверенных брокеров являются динамическими и могут быть обновлены в будущем, чтобы включить дополнительные узлы, на которых надстройка может использовать потоки NAA. В настоящее время группа brk-multihub включает office Word, Excel, PowerPoint, Outlook и Teams (при активации Office внутри).

Настройка конфигурации MSAL для использования NAA

Настройте надстройку для использования NAA, вызвав функцию createNestablePublicClientApplication в MSAL. MSAL возвращает общедоступное клиентское приложение, которое может быть вложено в узел собственного приложения (например, Outlook) для получения маркеров для приложения.

Ниже показано, как включить NAA в taskpane.js файле или taskpane.ts в проекте, созданном с помощью yo office (проект области задач надстройки Office ).

@azure/msal-browser Добавьте пакет в dependencies раздел package.json файла проекта. Дополнительные сведения об этом пакете см. в статье Библиотека проверки подлинности Майкрософт для JavaScript (MSAL.js) для приложений Browser-Based Single-Page. Рекомендуется использовать последнюю версию пакета (на момент последнего обновления статьи она была 3.26.0).
```
"dependencies": {
    "@azure/msal-browser": "^3.27.0",
    ...
```
Сохраните и запустите npm install для установки @azure/msal-browser.
Добавьте следующий код в начало taskpane.js файла или taskpane.ts . Это приведет к импорту библиотеки браузера MSAL.
```
import { createNestablePublicClientApplication } from "@azure/msal-browser";
```

Инициализация общедоступного клиентского приложения

Далее необходимо инициализировать MSAL и получить экземпляр общедоступного клиентского приложения. Он используется для получения маркеров доступа при необходимости. Рекомендуется поместить в метод код, создающий общедоступное клиентское Office.onReady приложение.

В функции Office.onReady добавьте вызов , createNestablePublicClientApplication как показано ниже. Замените Enter_the_Application_Id_Here заполнитель идентификатором приложения Azure, сохраненным ранее.

let pca = undefined;
Office.onReady(async (info) => {
  if (info.host) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";
    document.getElementById("run").onclick = run;

    // Initialize the public client application
    pca = await createNestablePublicClientApplication({
      auth: {
        clientId: "Enter_the_Application_Id_Here",
        authority: "https://login.microsoftonline.com/common"
      },
    });
  }
});

Примечание.

В предыдущем примере кода центру присваиваетсяобщее значение , которое поддерживает рабочие и учебные учетные записи или личные учетные записи Майкрософт. Если вы хотите настроить один клиент или другие типы учетных записей, см . раздел Параметры конфигурации приложения для дополнительных параметров центра.

Получение первого маркера

Маркеры, полученные MSAL.js через NAA, будут выданы для идентификатора регистрации приложения Azure. В этом примере кода вы получите маркер для API Graph Майкрософт. Если у пользователя есть активный сеанс с Microsoft Entra ID маркер получается автоматически. В противном случае библиотека предложит пользователю войти в систему в интерактивном режиме. Затем маркер используется для вызова API Graph Майкрософт.

На следующих шагах показан шаблон, используемый для получения маркера.

Укажите области. NAA поддерживает добавочное и динамическое согласие, поэтому всегда запрашивайте минимальные области, необходимые коду для выполнения задачи.
вызова метода acquireTokenSilent; Это позволит получить маркер без необходимости взаимодействия с пользователем.
В случае acquireTokenSilent сбоя вызовите acquireTokenPopup для отображения интерактивного диалогового окна для пользователя. acquireTokenSilent может завершиться ошибкой, если срок действия маркера истек или пользователь еще не дал согласие на все запрошенные области.

В следующем коде показано, как реализовать этот шаблон проверки подлинности в собственном проекте.

Замените функцию run в taskpane.js или taskpane.ts следующим кодом. Код задает минимальные области, необходимые для чтения файлов пользователя.
```
async function run() {
// Specify minimum scopes needed for the access token.
const tokenRequest = {
  scopes: ["Files.Read", "User.Read", "openid", "profile"],
};
let accessToken = null;

// TODO 1: Call acquireTokenSilent.

// TODO 2: Call acquireTokenPopup.

// TODO 3: Log error if token still null.

// TODO 4: Call the Microsoft Graph API.

}
```
Важно!

Запрос маркера должен включать области, отличные от только offline_access, openid, profileили email. Можно использовать любое сочетание предыдущих областей, но необходимо включить по крайней мере одну дополнительную область. В противном случае запрос маркера может завершиться ошибкой.

Замените TODO 1 на приведенный ниже код. Этот код вызывает acquireTokenSilent для получения маркера доступа.

try {
  console.log("Trying to acquire token silently...");
  const userAccount = await pca.acquireTokenSilent(tokenRequest);
  console.log("Acquired token silently.");
  accessToken = userAccount.accessToken;
} catch (error) {
  console.log(`Unable to acquire token silently: ${error}`);
}

Замените TODO 2 на приведенный ниже код. Этот код проверяет, получен ли маркер доступа. Если нет, он пытается получить маркер доступа в интерактивном режиме путем вызова acquireTokenPopup.

if (accessToken === null) {
  // Acquire token silent failure. Send an interactive request via popup.
  try {
    console.log("Trying to acquire token interactively...");
    const userAccount = await pca.acquireTokenPopup(tokenRequest);
    console.log("Acquired token interactively.");
    accessToken = userAccount.accessToken;
  } catch (popupError) {
    // Acquire token interactive failure.
    console.log(`Unable to acquire token interactively: ${popupError}`);
  }
}

Замените TODO 3 на приведенный ниже код. Если не удалось выполнить автоматический и интерактивный вход, запишите ошибку и вернитесь.
```
// Log error if both silent and popup requests failed.
if (accessToken === null) {
  console.error(`Unable to acquire access token.`);
  return;
}
```

Вызов API

После получения маркера используйте его для вызова API. В следующем примере показано, как вызвать API Graph Майкрософт путем вызова fetch с маркером, вложенным в заголовок Authorization.

Замените TODO 4 на приведенный ниже код.

// Call the Microsoft Graph API with the access token.
const response = await fetch(
  `https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name&$top=10`,
  {
    headers: { Authorization: accessToken },
  }
);

if (response.ok) {
  // Write file names to the console.
  const data = await response.json();
  const names = data.value.map((item) => item.name);

  // Be sure the taskpane.html has an element with Id = item-subject.
  const label = document.getElementById("item-subject");

  // Write file names to task pane and the console.
  const nameText = names.join(", ");
  if (label) label.textContent = nameText;
  console.log(nameText);
} else {
  const errorText = await response.text();
  console.error("Microsoft Graph call failed - error text: " + errorText);
}

После добавления всего предыдущего кода в функцию run убедитесь, что кнопка в области задач вызывает функцию run . Затем можно загрузить неопубликованную надстройку и опробовать код.

Что такое проверка подлинности вложенных приложений

Проверка подлинности вложенных приложений обеспечивает единый вход для приложений, вложенных в поддерживаемые приложения Майкрософт. Например, Excel в Windows запускает надстройку внутри веб-представления. В этом сценарии надстройка — это вложенное приложение, работающее внутри Excel, которое является узлом. NAA также поддерживает вложенные приложения в Teams. Например, если на вкладке Teams размещается Excel и ваша надстройка загружена, она вложена в Excel, которая также вложена в Teams. Опять же, NAA поддерживает этот вложенный сценарий, и вы можете получить доступ к единому входу, чтобы получить удостоверение пользователя и маркеры доступа пользователя, вошедшего в систему.

Лучшие методики

При использовании MSAL.js с NAA рекомендуется использовать следующие рекомендации.

Использование автоматической проверки подлинности по возможности

MSAL.js предоставляет acquireTokenSilent метод, который обрабатывает продление маркера путем выполнения автоматических запросов маркера без запроса пользователя. Метод сначала ищет допустимый кэшированный токен. Если он не найдется, библиотека выполняет автоматический запрос на Microsoft Entra ID, а при наличии активного сеанса пользователя возвращается новый маркер.

В некоторых случаях acquireTokenSilent попытка метода получить маркер завершается ошибкой. В некоторых случаях это происходит при истечении срока действия сеанса пользователя с Microsoft Entra ID или смены пароля пользователем, что требует взаимодействия с пользователем. При сбое acquireTokenSilent необходимо вызвать метод интерактивного acquireTokenPopup маркера.

Есть резервная версия, если NAA не поддерживается

Хотя мы стремимся обеспечить высокую степень совместимости с этими потоками в экосистеме Майкрософт, ваша надстройка может быть загружена в более старый узел Office, который не поддерживает NAA. В таких случаях надстройка не будет поддерживать простой единый вход, и вам может потребоваться вернуться к альтернативному методу проверки подлинности пользователя. Как правило, вы хотите использовать шаблон проверки подлинности MSAL SPA с ПОМОЩЬЮ API диалогового окна Office JS.

Используйте следующий код, чтобы проверка, поддерживается ли NAA при загрузке надстройки.

   Office.context.requirements.isSetSupported("NestedAppAuth", "1.1");

Дополнительные сведения см. в следующих ресурсах.

API MSAL.js, поддерживаемые NAA

В следующей таблице показано, какие API-интерфейсы поддерживаются при включении NAA в конфигурации MSAL.

Метод	Поддерживается NAA
`acquireTokenByCode`	Нет (вызывает исключение)
`acquireTokenPopup`	Да
`acquireTokenRedirect`	Нет (вызывает исключение)
`acquireTokenSilent`	Да
`addEventCallback`	Да
`addPerformanceCallback`	Нет (вызывает исключение)
`disableAccountStorageEvents`	Нет (вызывает исключение)
`enableAccountStorageEvents`	Нет (вызывает исключение)
`getAccountByHomeId`	Да
`getAccountByLocalId`	Да
`getAccountByUsername`	Да
`getActiveAccount`	Да
`getAllAccounts`	Да
`getConfiguration`	Да
`getLogger`	Да
`getTokenCache`	Нет (вызывает исключение)
`handleRedirectPromise`	Нет
`initialize`	Да
`initializeWrapperLibrary`	Да
`loginPopup`	Да
`loginRedirect`	Нет (вызывает исключение)
`logout`	Нет (вызывает исключение)
`logoutPopup`	Нет (вызывает исключение)
`logoutRedirect`	Нет (вызывает исключение)
`removeEventCallback`	Да
`removePerformanceCallback`	Нет (вызывает исключение)
`setActiveAccount`	Нет
`setLogger`	Да
`ssoSilent`	Да

Отчеты о безопасности

Если вы обнаружили проблему с безопасностью в наших библиотеках или службах, сообщите о ней secure@microsoft.com с максимальной информацией. Ваша отправка может иметь право на награду в рамках программы Microsoft Bounty . Не публикуйте проблемы безопасности на GitHub или на любом другом общедоступном сайте. Мы свяжемся с вами вскоре после получения отчета о проблеме. Мы рекомендуем вам получать новые уведомления об инцидентах безопасности, перейдя на страницу уведомлений майкрософт по технической безопасности , чтобы подписаться на оповещения рекомендаций по безопасности.

Примеры кода

Название примера	Описание
Надстройка Office с единым входом с использованием проверки подлинности вложенного приложения	Показано, как использовать MSAL.js проверку подлинности вложенного приложения (NAA) в надстройке Office для доступа к API Microsoft Graph для вошедшего пользователя. В примере отображаются имя и адрес электронной почты пользователя, выполнившего вход. Кроме того, в документ вставляются имена файлов из учетной записи Microsoft OneDrive пользователя.
Надстройка Outlook с единым входом с использованием проверки подлинности вложенных приложений	Показано, как использовать MSAL.js проверку подлинности вложенного приложения (NAA) в надстройке Outlook для доступа к API Microsoft Graph для вошедшего пользователя. В примере отображаются имя и адрес электронной почты пользователя, выполнившего вход. Он также вставляет имена файлов из учетной записи Microsoft OneDrive пользователя в новый текст сообщения.

Название примера

Описание

Надстройка Office с единым входом с использованием проверки подлинности вложенного приложения

Показано, как использовать MSAL.js проверку подлинности вложенного приложения (NAA) в надстройке Office для доступа к API Microsoft Graph для вошедшего пользователя. В примере отображаются имя и адрес электронной почты пользователя, выполнившего вход. Кроме того, в документ вставляются имена файлов из учетной записи Microsoft OneDrive пользователя.

Надстройка Outlook с единым входом с использованием проверки подлинности вложенных приложений

Показано, как использовать MSAL.js проверку подлинности вложенного приложения (NAA) в надстройке Outlook для доступа к API Microsoft Graph для вошедшего пользователя. В примере отображаются имя и адрес электронной почты пользователя, выполнившего вход. Он также вставляет имена файлов из учетной записи Microsoft OneDrive пользователя в новый текст сообщения.

См. также

NAA: вопросы и ответы

Поделиться через