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

Примечание.

Проверка подлинности вложенных приложений (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, для вызова конечных точек.

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

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

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

Варианты использования NAA

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

Настройка NAA

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

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

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

Необходимо создать регистрацию приложения с идентификатором Microsoft Entra для надстройки на портал 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. В отличие от потока OBO, вам не нужно предварительно авторизовать узлы для вызова конечных точек.

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

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

Примечание.

Свойство 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\"]}}}"
     }
   ]
 }
}

Важно!

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

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

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

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

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

Повышение производительности за счет сокращения задержек проверки подлинности во время запуска приложения
Включение единого входа во вложенных приложениях без повторных входов

Примечание.

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

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

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

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

Примечание.

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

Пример кода

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

См. также

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

Была ли эта страница полезна?

Last updated on 2025-10-02

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

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

Варианты использования NAA

Настройка NAA

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

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

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

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

Вызов API

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

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

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

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

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

Пример кода

См. также

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

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