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

Примечание.

Проверка подлинности вложенных приложений (NAA) поддерживается только в одностраничных приложениях (SPA), таких как вкладки.

NAA — это новый протокол проверки подлинности для приложений SPA, внедренных в хост-среды, такие как Teams, Outlook и Microsoft 365. Он упрощает процесс проверки подлинности для обеспечения единого входа (SSO) в приложениях, вложенных в поддерживаемые хост-приложения. Модель NAA поддерживает основное удостоверение для ведущего приложения, которое включает несколько удостоверений для вложенных приложений. Корпорация Майкрософт использует эту модель для вкладок Teams, личных приложений и надстроек Office.

Модель NAA имеет несколько преимуществ по сравнению с потоком On-Behalf-Of (OBO):

NAA требует, чтобы вы использовали только библиотеку MSAL.js. Эта функция не требуется в клиентской getAuthToken библиотеке JavaScript Teams (TeamsJS).
Вы можете вызывать службы, такие как Microsoft Graph, с помощью маркера доступа из кода клиента в качестве SPA. Нет необходимости в сервере среднего уровня.
Вы можете использовать добавочное и динамическое согласие для областей (разрешений).

Вам не нужно предварительно авторизовать узлы, такие как Teams или Microsoft 365, чтобы звонить в конечные точки.

В следующей таблице описана разница между единым входом Microsoft Entra и NAA в Teams:

Шаги, необходимые для разработки	Традиционный единый вход Teams Entra	NAA
Предоставление URI перенаправления	Обязательный	Обязательный
Регистрация API в Microsoft Entra ID	Обязательный
Определение пользовательской области в Microsoft Entra ID	Обязательный
Авторизация клиентских приложений Teams	Обязательный
Изменение манифеста приложения (прежнее название — манифест приложения Teams)	Обязательный	Рекомендуется*
Получение маркера доступа с помощью пакета SDK TeamsJS	Обязательный
Запрос согласия пользователя на дополнительные разрешения	Обязательный
Проведение обмена OBO на сервере	Обязательный

ИТ-администратор может заблокировать приложение или дать согласие только на определенные разрешения для приложения в Microsoft Entra ID. Чтобы избежать этого, необходимо включить идентификатор приложения и ресурс по умолчанию в манифест приложения, чтобы администратор мог утвердить разрешения в Центре администрирования Teams.

Примеры использования NAA

Сценарий	Описание
Согласие на единый вход (и другие разрешения)	Тому (новому участнику команды разработчиков Contoso) необходимо использовать приложение Contoso на собраниях Teams для совместной работы на досках. При первом использовании диалоговое окно предлагает Тому предоставить разрешения, в том числе на чтение его аватара в профиле (User.Read). После предоставления согласия Том сможет без проблем использовать Contoso на разных устройствах в будущих собраниях.
Повторная проверка подлинности или условный доступ Поэтапная проверка подлинности	Том, работая из Австралии, сталкивается с триггером условного доступа, требующим многофакторной проверки подлинности (MFA) для доступа к Contoso в Teams. Том в диалоговом окне сообщает, что требуется дополнительная проверка, и он может пройти процедуру MFA, чтобы продолжить использование Contoso.
сведения об ошибках;	Том сталкивается с ошибкой при входе в Contoso из-за проблемы с получением сведений об учетной записи. Том сталкивается с кнопкой повтора попытки с запросом на повторную проверку подлинности. Однако они обнаруживают, что системный администратор ограничил доступ к Contoso.

Настройка NAA

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

Регистрация SPA
Добавление доверенных брокеров
Инициализация общедоступного клиентского приложения
Получите свой первый токен
Вызов API

Регистрация SPA

Вы должны зарегистрировать приложение Microsoft Entra ID для своей надстройки на портале Azure. Для регистрации приложения необходимо указать имя, поддерживаемый тип учетной записи и перенаправление SPA. После регистрации приложения портал Azure создает идентификатор регистрации приложения Microsoft Entra. Если надстройка требует дополнительной регистрации приложения, помимо NAA и единого входа, см. раздел Регистрация одностраничного приложения.

Добавление доверенных брокеров

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

brk-multihub://<your_domain>

Где:

brk-multihub позволяет проверять подлинность при посредничестве любых поддерживаемых узлов Microsoft 365, для работы в которых она настроена, таких как Teams, Outlook или Microsoft365.com.
< > your_domain — это полное доменное имя, в котором размещено ваше приложение. Например, brk-multihub://contoso.com.

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

✔️ brk-multihub://myapp.teams.microsoft.com
❌ brk-multihub://myapp.teams.microsoft.com/go

Дополнительные сведения об обновлении приложения Teams для запуска в Outlook и Microsoft365.com см. в статье расширения возможностей приложений Teams в Microsoft 365.

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

Примечание.

Для успешной проверки подлинности инициализируйте TeamsJS перед инициализацией MSAL.

Инициализируйте MSAL и получите экземпляр приложения общедоступного клиента, чтобы при необходимости получать маркеры доступа.

import {
  AccountInfo,
  IPublicClientApplication,
  createNestablePublicClientApplication,
} from "@azure/msal-browser";

const msalConfig = {
  auth: {
    clientId: "your_client_id",
    authority: "https://login.microsoftonline.com/{your_tenant_id}",
    supportsNestedAppAuth: true
  },
};

let pca: IPublicClientApplication;

export function initializePublicClient() {
  console.log("Starting initializePublicClient");
  return createNestablePublicClientApplication(msalConfig).then(
    (result) => {
      console.log("Client app created");
      pca = result;
      return pca;
    }
  );
}

Получите свой первый токен

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

Чтобы получить маркер, выполните следующие действия.

Используйте MSAL.js для получения маркеров для идентификатора приложения. Дополнительные сведения см. в статье Получение и использование маркера доступа.
С getActiveAccount помощью API проверьте наличие активной учетной записи для вызова publicClientApplication. Если активной учетной записи нет, попробуйте извлечь ее из кэша с getAccountпомощью , используя дополнительные параметры фильтра, такие как tenantID, , homeAccountId, и loginHint из интерфейса Context.

Примечание.

Свойство homeAccountId эквивалентно userObjectId в TeamsJS.
Вызов publicClientApplication.acquireTokenSilent(accessTokenRequest) для получения маркера без взаимодействия с пользователем. accessTokenRequest Определяет области, для которых запрашивается маркер доступа. NAA поддерживает добавочное и динамическое согласие. Убедитесь, что вы всегда запрашиваете минимальные области, необходимые вашему коду для выполнения своей задачи.

Если учетная запись недоступна, MSAL.js возвращает .InteractionRequiredAuthError Вызов publicClientApplication.acquireTokenPopup(accessTokenRequest) , чтобы отобразить интерактивное диалоговое окно для пользователя. acquireTokenSilent может завершиться сбоем, если срок действия маркера истек или пользователь не дал согласия на все запрошенные области.

В следующем фрагменте кода показан пример доступа к маркеру:


  // MSAL.js exposes several account APIs, logic to determine which account to use is the responsibility of the developer
  const account = publicClientApplication.getActiveAccount();

  const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
  };

  publicClientApplication
    .acquireTokenSilent(accessTokenRequest)
    .then(function (accessTokenResponse) {
      // Acquire token silent success
      let accessToken = accessTokenResponse.accessToken;
      // Call your API with token
      callApi(accessToken);
    })
    .catch(function (error) {
      //Acquire token silent failure, and send an interactive request
      if (error instanceof InteractionRequiredAuthError) {
        publicClientApplication
          .acquireTokenPopup(accessTokenRequest)
          .then(function (accessTokenResponse) {
            // Acquire token interactive success
            let accessToken = accessTokenResponse.accessToken;
            // Call your API with token
            callApi(accessToken);
          })
          .catch(function (error) {
            // Acquire token interactive failure
            console.log(error);
          });
      }
      console.log(error);
    });

Вызов API

После получения маркера используйте его для вызова API. Это гарантирует, что API вызывается с допустимым маркером для выполнения запросов к серверу с проверкой подлинности.

В следующем примере показано, как сделать аутентифицированный запрос к Microsoft API Graph для доступа к данным Microsoft 365:


var headers = new Headers();
var bearer = "Bearer " + access_token;
headers.append("Authorization", bearer);
var options = {
    method: "GET",
    headers: headers
};

var graphEndpoint = "<https://graph.microsoft.com/v1.0/me>";

fetch(graphEndpoint, options)
    .then(function (response) {
        //do something with response
    });

Предварительная выборка маркера для проверки подлинности вложенных приложений (NAA)

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

Включение предварительной получения маркера

Чтобы включить предварительную выборку маркеров, обновите манифест приложения Teams до версии 1.22 или более поздней и включите nestedAppAuthInfo этот раздел внутрь webApplicationInfo.

{
 "webApplicationInfo": {
   "id": "33333ddd-0000-0000-0000-88888757bbbb",
   "resource": "api://app.com/botid-33333ddd-0000-0000-0000-88888757bbbb",
   "nestedAppAuthInfo": [
     {
       "redirectUri": "brk-multihub://app.com",
       "scopes": ["openid", "profile", "offline_access"],
       "claims": "{\"access_token\":{\"xms_cc\":{\"values\":[\"CP1\"]}}}"
     }
   ]
 }
}

Важно!

Для каждого запроса на предварительную выборку маркера NAA укажите идентификатор клиента регистрации Microsoft Entra ID агента или приложения в необязательном clientId поле соответствующей nestedAppAuthInfo записи. Если это значение указано, оно используется для предварительной выборки маркера для этой записи. Если запись не включает clientId, средство обработки использует webApplicationInfo.id в качестве идентификатора клиента запрос предварительной выборки маркера NAA этой записи.
webApplicationInfo.id — это резервный идентификатор клиента для записей, в которых не указан clientId. Он не должен совпадать с каждым идентификатором клиента начального уровня. Если приложение использует только webApplicationInfo.id предварительное получение маркера NAA, это значение должно соответствовать идентификатору клиента регистрации Microsoft Entra ID приложения, используемому для фактических запросов токена NAA.
Значения в webApplicationInfo.id и все поля внутри nestedAppAuthInfo должны точно совпадать с параметрами, используемыми в запросе маркера NAA приложения во время выполнения. Любое несоответствие, например различия в областях, URI перенаправления или утверждения, не позволит узлу обслуживать маркер из кэша.
Предварительно полученные маркеры хранятся в памяти в течение короткого времени и предназначены для использования только во время начальной загрузки приложения. Если приложение попытается получить маркер позже, например в ответ на действие пользователя, предварительно полученный маркер может быть недоступен. В таких случаях приложение должно инициировать новый запрос маркера, используя стандартные потоки проверки подлинности.

Принципы действия

Если включена предварительная выборка маркеров, ведущая среда пытается получить и кэшировать необходимые маркеры перед отображением приложения. Эти маркеры сохраняются в памяти и становятся доступными для приложения сразу после запуска.

Это поведение аналогично возможности предварительной выборки в устаревшей модели единого входа Teams, где getAuthToken API автоматически запускался при загрузке вкладки. При аутентификации вложенных приложений (NAA) эта функция реализуется через конфигурацию манифеста, что повышает производительность без необходимости внутреннего обмена токенами.

Преимущества предварительной выборки маркеров в NAA

Повышение производительности за счет уменьшения задержек аутентификации во время запуска приложения
Единый вход (SSO) во вложенных приложениях без повторного входа в систему

Примечание.

Предварительная выборка маркеров в настоящее время поддерживается только в веб-клиентах и классическом клиентах Microsoft Teams.

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

По возможности используйте автоматическую проверку подлинности. MSAL.js предоставляет acquireTokenSilent метод, который обрабатывает обновление маркеров путем выполнения автоматических запросов токенов без обращения к пользователю. Метод сначала ищет допустимый кэшированный маркер в хранилище браузера. Если он не найден, библиотека делает автоматический запрос к Microsoft Entra ID, и при наличии активного сеанса пользователя (определяется файлом cookie, установленным в браузере в домене Microsoft Entra), Microsoft Entra ID возвращает новый маркер. Библиотека не вызывает acquireTokenSilent метод автоматически. Для получения действительного маркера рекомендуется вызвать acquireTokenSilent приложение перед вызовом API.

В некоторых случаях попытка получить маркер с помощью acquireTokenSilent метода завершается ошибкой. Например, при истечении срока действия сеанса пользователя с Microsoft Entra ID или смене пароля пользователем acquireTokenSilent приложения происходит сбой. Вызовите метод интерактивного маркера получения (acquireTokenPopup).
Имейте запасной вариант: потоки NAA обеспечивают совместимость в экосистеме Майкрософт. Однако ваше приложение может отображаться в клиентах нижнего уровня или устаревших клиентах, которые не обновлены для поддержки NAA. В таких случаях приложение не может поддерживать простой единый вход, и вам может потребоваться вызвать специальные API для взаимодействия с пользователем, чтобы открыть диалоговые окна проверки подлинности. Дополнительные сведения см. в статье Включение единого входа для приложения вкладки.

Примечание.

Не следует использовать NAA, если вы работаете с поставщиком удостоверений, не принадлежащим к Microsoft Entra. Вместо этого можно использовать проверку подлинности во всплывающих окнах.
Поддержка NAA: NAA может поддерживаться не во всех средах хост-приложений. Чтобы проверить, поддерживает ли текущий клиент эту функцию, можно вызвать указанный API для определения его состояния. Возвращаемое значение true указывает на поддержку NAA, но false предполагает, что она не поддерживается.
Протестируйте приложение в нескольких средах: если предполагается, что ваше приложение будет работать как в веб-представлении, так и в браузере, рекомендуется протестировать его в обеих средах развертывания, чтобы убедиться, что оно работает должным образом. Некоторые API, функционирующие в браузере, могут не работать в веб-представлениях.

Пример кода

Название примера	Описание	.NET	Node.js
Проверка подлинности вложенных приложений	В этом примере показан единый вход (SSO) Microsoft Entra на вкладке Microsoft Teams с использованием потока On-Behalf-Of (OBO) для вызова Microsoft API Graph от имени пользователя.	Просмотр	Просмотр

См. также

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-02-27

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

Примеры использования NAA

Настройка NAA

Регистрация SPA

Добавление доверенных брокеров

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

Получите свой первый токен

Вызов API

Предварительная выборка маркера для проверки подлинности вложенных приложений (NAA)

Включение предварительной получения маркера

Принципы действия

Преимущества предварительной выборки маркеров в NAA

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

Пример кода

См. также

Обратная связь

Дополнительные ресурсы