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

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:

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

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

Настройка NAA

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

1. Регистрация SPA
2. Добавление доверенных брокеров
3. Инициализация общедоступного клиентского приложения
4. Получение первого маркера
5. Вызов 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.

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

Инициализируйте 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 обрабатывает получение маркера для проверки подлинности пользователей. Он пытается получить маркер доступа автоматически. Если это не удалось, пользователю будет предложено предоставить согласие. Затем маркер используется для вызова API Graph Майкрософт или других защищенных ресурсов Microsoft Entra ID. В отличие от потока OBO, вам не нужно предварительно авторизовать узлы для вызова конечных точек.

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

1. Используйте MSAL.js для получения маркеров для идентификатора приложения. Дополнительные сведения см. в статье Получение и использование маркера доступа.

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

   Примечание.

   Свойство homeAccountId эквивалентно userObjectId в TeamsJS.

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

4. Если учетная запись недоступна, 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
    });

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

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

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

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

  Примечание.

  Вы не должны использовать NAA, если вы используете поставщик удостоверений, не Microsoft Entra. Вместо этого можно использовать проверку подлинности со всплывающей окнами.

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

• Протестируйте приложение в нескольких средах. Если ожидается, что ваше приложение будет работать как в веб-представлении, так и в развертываниях браузера, рекомендуется протестировать приложение в обеих средах развертывания, чтобы убедиться, что оно будет работать должным образом. Некоторые API, которые работают в браузере, могут не работать в веб-представлениях.

Пример кода

См. также

• Платформа удостоверений Майкрософт и поток OBO OAuth 2.0
• Кэширование в MSAL
• Знакомство с проверкой подлинности вложенных приложений: улучшенный протокол проверки подлинности для приложения Teams