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

Изменение манифеста Microsoft Entra

  • Статья

Microsoft Teams Toolkit теперь управляет приложением Microsoft Entra с файлом манифеста приложения в качестве источника истины в течение жизненного цикла разработки приложения Microsoft Teams.

Настройка шаблона манифеста Microsoft Entra

Вы можете настроить шаблон манифеста Microsoft Entra для обновления приложения Microsoft Entra.

  1. Откройте aad.template.json в проекте.

    Снимок экрана: шаблон.

  2. Обновите шаблон напрямую или сослаться на значения из другого файла. Ниже приведены сценарии настройки.

    Добавление разрешения приложения

    Если приложению Teams требуются дополнительные разрешения для вызова API с дополнительными разрешениями, необходимо обновить requiredResourceAccess свойство в шаблоне манифеста Microsoft Entra. Вы можете увидеть следующий пример для этого свойства:

            "requiredResourceAccess": [
{
        "resourceAppId": "Microsoft Graph",
        "resourceAccess": [
            {
                "id": "User.Read", // For Microsoft Graph API, you can also use uuid for permission id
                "type": "Scope" // Scope is for delegated permission
            },
            {
                "id": "User.Export.All",
                "type": "Role" // Role is for application permission
            }
        ]
    },
    {
        "resourceAppId": "Office 365 SharePoint Online",
        "resourceAccess": [
            {
                    "id": "AllSites.Read",
            "type": "Scope"
            }
        ]
    }
]

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

    • Свойство resourceAppId используется для разных API. Для Microsoft Graph и Office 365 SharePoint Onlineвведите имя непосредственно вместо UUID, а для других API используйте UUID.

    • Свойство resourceAccess.id используется для различных разрешений. Для Microsoft Graph и Office 365 SharePoint Onlineвведите имя разрешения непосредственно вместо UUID, а для других API используйте UUID.

    • Свойство resourceAccess.type используется для делегированного разрешения или разрешения приложения. Scope означает делегированное разрешение и Role означает разрешение приложения.

    Предварительная проверка подлинности клиентского приложения

    Свойство можно использовать для preAuthorizedApplications авторизации клиентского приложения, чтобы указать, что API доверяет приложению. Пользователи не соглашаются, когда клиент вызывает открытый API. Вы можете увидеть следующий пример для этого свойства:

    
      "preAuthorizedApplications": [
      {
          "appId": "1fec8e78-bce4-4aaf-ab1b-5451cc387264",
          "permissionIds": [
               "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}"
           ]
      }
      ...
  ]

    preAuthorizedApplications.appId свойство используется для приложения, которое требуется авторизовать. Если вы не знаете идентификатор приложения и знаете только имя приложения, выполните следующие действия для поиска идентификатора приложения:

    1. Перейдите на портал Azure и откройте раздел Регистрация приложений.

    2. Выберите Все приложения и найдите имя приложения.

    3. Выберите имя приложения и получите идентификатор приложения на странице обзора.

    Обновление URL-адреса перенаправления для ответа на проверку подлинности

    URL-адреса перенаправления используются при возврате ответов проверки подлинности, таких как маркеры после успешной проверки подлинности. URL-адреса перенаправления можно настроить с помощью свойства replyUrlsWithType. Например, чтобы добавить https://www.examples.com/auth-end.html в качестве URL-адреса перенаправления, его можно добавить в следующем примере:

        "replyUrlsWithType": [
       ...
     {
         "url": "https://www.examples.com/auth-end.html",
         "type": "Spa"
     }
]

  3. Обновление изменений приложения Microsoft Entra для локальной или удаленной среды.

    1. Выберите Preview CodeLens в aad.template.json.

      Снимок экрана: предварительный просмотр.

    2. Выберите локальную среду или среду разработки .

      Снимок экрана: список сред.

    3. Выберите Deploy Azure AD Manifest CodeLens в aad.local.json или aad.dev.json.

      Снимок экрана: выделенный параметр развертывания.

    4. Развертываются изменения для приложения Microsoft Entra, используемого в локальной среде или среде разработки.

    5. Кроме того, можно открыть палитру команд и выбрать Teams: Обновить приложение Microsoft Entra , чтобы обновить приложение Microsoft Entra. Снимок экрана: параметр Палитра команд.

Заполнители шаблонов манифеста Microsoft Entra

Файл манифеста Microsoft Entra содержит аргументы заполнителей с {{...}} операторы, он заменяется во время сборки для разных сред. Вы можете ссылаться на переменные среды с помощью аргументов заполнителя.

Эталонная переменная среды в шаблоне манифеста Microsoft Entra

Вам не нужно вводить постоянные значения в шаблон манифеста Microsoft Entra, а файл шаблона манифеста Microsoft Entra поддерживает значения ссылочных переменных среды. Синтаксис ${{YOUR_ENV_VARIABLE_NAME}} в средстве можно использовать в качестве значений параметров для разрешения значений переменных среды.

Изменение и просмотр манифеста Microsoft Entra с помощью CodeLens

Файл шаблона манифеста Microsoft Entra содержит CodeLens для просмотра и изменения кода.

Файл шаблона манифеста Microsoft Entra

В начале файла шаблона манифеста Microsoft Entra есть предварительная версия CodeLens. Выберите CodeLens, чтобы создать манифест Microsoft Entra в соответствии с вашей средой.

Снимок экрана: предварительный просмотр добавления codelens.

Аргумент заполнителя CodeLens

Аргумент заполнителя CodeLens помогает просматривать значения для локальной отладки и разработки среды. При наведении указателя мыши на аргумент заполнителя отобразится окно подсказки для значений всех сред.

Снимок экрана: добавление аргументов.

Требуемый доступ к ресурсам CodeLens

Шаблон манифеста Microsoft Entra в наборе средств Teams также поддерживает читаемые пользователем строки для Microsoft Graph разрешений и Office 365 SharePoint Online . Официальная схема манифеста Microsoft Entra, которая является и resourceAccess в requiredResourceAccess свойстве resourceAppId поддерживает только UUID. Если ввести UUID, в CodeLens отображаются удобочитаемые строки, в противном случае — UUID.

Снимок экрана: добавление ресурса в необходимый доступ к ресурсу.

Предварительно авторизованные приложения CodeLens

CodeLens показывает имя приложения для предварительно авторизованного идентификатора preAuthorizedApplications приложения для свойства .

Просмотр приложения Microsoft Entra на портале Azure

  1. Скопируйте идентификатор клиента приложения Microsoft Entra из .env.xxx файла () в свойстве AAD_APP_CLIENT_ID .

    Снимок экрана: идентификатор клиента.

    Примечание.

    xxx в идентификаторе клиента указывает имя среды, в которой развернуто приложение Microsoft Entra.

  2. Перейдите на портал Azure и войдите в учетную запись Microsoft 365.

    Примечание.

    Убедитесь, что учетные данные для входа в приложение Teams и учетная запись M365 совпадают.

  3. Откройте страницу Регистрация приложений и выполните поиск в приложении Microsoft Entra, используя идентификатор клиента, скопированный ранее.

    Снимок экрана: идентификатор клиента на вкладке Все приложения.

  4. Выберите приложение Microsoft Entra в результатах поиска, чтобы просмотреть подробные сведения.

  5. На странице сведений о приложении Microsoft Entra выберите меню Манифест , чтобы просмотреть манифест этого приложения. Схема манифеста аналогична схеме в aad.template.json файле. Дополнительные сведения о манифесте см. в разделе Манифест приложения Microsoft Entra.

    Снимок экрана: экран манифеста.

  6. Вы можете выбрать Другое меню , чтобы просмотреть или настроить приложение Microsoft Entra на портале.

Использование существующего приложения Microsoft Entra

Для проекта Teams можно использовать существующее приложение Microsoft Entra. Дополнительные сведения см. в статье Использование существующего приложения Microsoft Entra для приложения Teams.

Жизненный цикл разработки приложения Microsoft Entra в Teams

Вам необходимо взаимодействовать с приложением Microsoft Entra на различных этапах жизненного цикла разработки приложения Teams.

  1. Создание проекта

    Вы можете создать проект с помощью Teams Toolkit, который поставляется с поддержкой единого входа (SSO) по умолчанию, например SSO-enabled tab. Дополнительные сведения о создании нового приложения см. в статье Создание приложения Teams с помощью набора средств Teams. Файл манифеста Microsoft Entra автоматически создается в aad.template.json. Teams Toolkit создает или обновляет приложение Microsoft Entra во время локальной разработки или при перемещении приложения в облако.

  2. Добавление единого входа в бот или вкладку

    После создания приложения Teams без встроенного единого входа Набор средств Teams постепенно помогает добавлять единый вход для проекта. В результате файл манифеста Microsoft Entra автоматически создается в aad.template.json.

    Teams Toolkit создает или обновляет приложение Microsoft Entra во время следующего сеанса локальной разработки или во время перемещения приложения в облако.

  3. Локальная сборка

    Набор средств Teams выполняет следующие функции во время локальной разработки:

    • Прочитайте файл, .env.local чтобы найти существующее приложение Microsoft Entra. Если приложение Microsoft Entra уже существует, Teams Toolkit повторно использует существующее приложение Microsoft Entra. В противном случае необходимо создать новое приложение с помощью aad.template.json файла .

    • Изначально игнорирует некоторые свойства в файле манифеста, для чего требуется дополнительный контекст, например replyUrls свойство, которому требуется локальная конечная точка разработки во время создания нового приложения Microsoft Entra с файлом манифеста.

    • После успешного запуска локальной среды разработки свойства , replyUrlsи другие свойства приложения identifierUrisMicrosoft Entra, недоступные на этапе создания, обновляются соответствующим образом.

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

  4. Подготовка облачных ресурсов

    Необходимо подготовить облачные ресурсы и развернуть приложение при перемещении приложения в облако. На таких этапах, как локальная отладка, Набор средств Teams:

    • Считывает файл, .env.{env} чтобы найти существующее приложение Microsoft Entra. Если приложение Microsoft Entra уже существует, Teams Toolkit повторно использует существующее приложение Microsoft Entra. В противном случае необходимо создать новое приложение с помощью aad.template.json файла .

    • Игнорирует некоторые свойства в файле манифеста, для чего требуется дополнительный контекст, replyUrls например свойство. Для этого свойства требуется интерфейсная конечная точка или конечная точка бота во время создания нового приложения Microsoft Entra с файлом манифеста.

    • Завершает подготовку других ресурсов, затем приложение identifierUrisMicrosoft Entra и replyUrls обновляется в соответствии с правильными конечными точками.

  5. Создание приложения

    • Облачная команда развертывает приложение в подготовленных ресурсах. Он не включает развертывание внесенных изменений в приложение Microsoft Entra.

    • Teams Toolkit обновляет приложение Microsoft Entra в соответствии с файлом шаблона манифеста Microsoft Entra.

Ограничения

  1. Расширение Teams Toolkit не поддерживает все свойства, перечисленные в схеме манифеста Microsoft Entra.

    В следующей таблице перечислены свойства, которые не поддерживаются расширением Teams Toolkit.

    Не поддерживаемые свойства Причина
    passwordCredentials Запрещено в манифесте
    createdDateTime Доступно только для чтения и не может измениться
    logoUrl Доступно только для чтения и не может измениться
    publisherDomain Доступно только для чтения и не может измениться
    oauth2RequirePostResponse Не существует в API Graph
    oauth2AllowUrlPathMatching Не существует в API Graph
    samlMetadataUrl Не существует в API Graph
    orgRestrictions Не существует в API Graph
    certification Не существует в API Graph

  2. Свойство requiredResourceAccess используется для читаемых пользователем имен приложений ресурсов или строк имен разрешений только для Microsoft Graph API и Office 365 SharePoint Online . Необходимо использовать UUID для других API. Чтобы получить идентификаторы на портале Azure, выполните следующие действия.

    1. Зарегистрируйте новое приложение Microsoft Entra на портале Azure.
    2. Выберите API permissions на странице приложения Microsoft Entra.
    3. Выберите add a permission , чтобы добавить необходимое разрешение.
    4. Выберите Manifest из requiredResourceAccess свойства, где можно найти идентификаторы API и разрешения.

См. также