Добавление проверки подлинности для бота Teams

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

В этой статье показано, как использовать проверку подлинности пакета SDK Службы Azure Bot версии 4 на основе OAuth 2.0. Это упрощает разработку бота, который может использовать маркеры проверки подлинности на основе учетных данных пользователя. Ключом во всем этом является использование поставщиков удостоверений, как мы увидим позже.

OAuth 2.0 — это открытый стандарт проверки подлинности и авторизации, используемый Microsoft Azure Active Directory (Azure AD) и многими другими поставщиками удостоверений. Базовое понимание OAuth 2.0 является необходимым условием для работы с проверкой подлинности в Teams.

Основные сведения см. в статье Упрощенный обзор OAuth 2, а полные спецификации — в статье OAuth 2.0.

Дополнительные сведения о том, как Служба Azure Bot выполняет проверку подлинности, см. в статье Проверка подлинности пользователя в беседе.

В данной статье вы узнаете следующее.

  • Как создать бота с поддержкой проверки подлинности. Вы примените cs-auth-sample для обработки учетных данных для входа пользователя и создания маркера проверки подлинности.
  • Как развернуть бот в Azure и связать его с поставщиком удостоверений. Поставщик выпускает маркер на основе учетных данных для входа пользователя. Бот может использовать маркер для доступа к ресурсам, таким как почтовая служба, для которых требуется проверка подлинности. Дополнительные сведения см. в статье Поток проверки подлинности Microsoft Teams для ботов.
  • Как интегрировать бота в Microsoft Teams. После интеграции бота вы можете войти и обмениваться с ним сообщениями в чате.

Предварительные условия

Создание группы ресурсов

Группа ресурсов и план обслуживания не являются строго обязательными, но они позволяют легко выпускать создаваемые вами ресурсы. Это рекомендуется для упорядочения ресурсов и управления ими.

Вы воспользуетесь группой ресурсов с целью создания отдельных ресурсов для Bot Framework. Для обеспечения производительности убедитесь, что эти ресурсы находятся в одном регионе Azure.

  1. В браузере войдите на портал Microsoft Azure.
  2. На панели навигации слева выберите Группы ресурсов.
  3. В левом верхнем углу отображаемого окна выберите вкладку Добавить, чтобы создать группу ресурсов. Вам будет предложено указать следующее.
    1. Подписка. Используйте свою существующую подписку.
    2. Группа ресурсов. Введите имя группы ресурсов. Примером может быть TeamsResourceGroup. Помните, что имя должно быть уникальным.
    3. В раскрывающемся меню Регион выберите Западная часть США или регион, близкий к вашим приложениям.
    4. Нажмите кнопку Проверить и создать. Должен появиться баннер с сообщением Проверка пройдена.
    5. Нажмите кнопку Создать. Создание группы ресурсов может занять несколько минут.

Совет

Как и в случае с ресурсами, которые вы создадите далее в этом руководстве, рекомендуется закрепить эту группу ресурсов на панели мониторинга для удобного доступа. Если вы хотите это сделать, щелкните значок 📌 закрепления в правом верхнем углу панели мониторинга.

Создание плана обслуживания

  1. На портале Azure в панели навигации слева выберите Создать ресурс.
  2. В поле поиска введите План службы приложений. Выберите карточку План службы приложений в результатах поиска.
  3. Нажмите Создать.
  4. Вам будет предложено указать следующую информацию.
    1. Подписка. Вы можете использовать существующую подписку.
    2. Группа ресурсов. Выберите ранее созданную группу.
    3. Имя. Введите имя плана обслуживания. Примером может быть TeamsServicePlan. Помните, что имя должно быть уникальным в пределах группы.
    4. Операционная система. Выберите Windows или применимую ОС.
    5. Регион. Выберите Западная часть США или регион, близкий к вашим приложениям.
    6. Ценовая категория. Выберите Стандартный S1. Это должно быть значение по умолчанию.
    7. Нажмите кнопку Проверить и создать. Должен появиться баннер с сообщением Проверка пройдена.
    8. Нажмите Создать. Создание плана службы приложений может занять несколько минут. План будет указан в группе ресурсов.

Создание регистрации ресурсов Azure Bot

Регистрация ресурса Azure Bot регистрирует веб-службу в качестве бота с помощью Bot Framework, которая предоставляет идентификатор приложения Майкрософт и пароль приложения (секрет клиента).

Важно!

Необходимо зарегистрировать бот только в том случае, если он не размещен в Azure. Если вы создали бот с помощью портал Azure, он уже зарегистрирован в службе. Если вы создали бот с помощью Bot Framework или портала разработчика, он не зарегистрирован в Azure.

  1. Перейдите на портал Azure и выполните поиск по запросу Azure Bot в разделе Создание ресурса.

  2. Откройте Azure Bot нажмите Создать.

  3. Введите имя дескриптора бота в поле Дескриптор бота.

  4. Выберите свою подписку в раскрывающемся списке.

  5. Выберите свою группу ресурсов в раскрывающемся списке.

  6. Для параметра Тип приложения выберите Мультитенантное в разделе Идентификатор приложения Майкрософт.

    Снимок экрана: выбор нескольких клиентов для Microsoft AppID.

  7. Выберите Проверить и создать.

    Снимок экрана: создание бота Azure.

  8. Если проверка пройдена, нажмите Создать.

    Подготовка службы бота займет несколько секунд.

    Снимок экрана: прохождение проверки бота Azure.

  9. Выберите пункт Перейти к ресурсу. Бот и связанные ресурсы указаны в группе ресурсов.

    Снимок экрана: выбор группы ресурсов.

    Теперь ваш бот Azure создан.

    Снимок экрана: создание ресурсов бота Azure.

Чтобы создать секрет клиента:

  1. В разделе Параметры выберите Конфигурация. Сохраните Идентификатор приложения Майкрософт (идентификатор клиента) для дальнейшего использования.

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

  2. Рядом с полем Идентификатор приложения Майкрософт выберите Управление.

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

  3. В разделе Секреты клиента выберите Новый секрет клиента. Появится окно Добавить секрет клиента.

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

  4. Введите описание и нажмите Добавить.

    На снимку экрана показано, как ввести описание секрета клиента.

  5. В столбце Значение выберите Копировать в буфер обмена и сохраните идентификатор секрета клиента для дальнейшего использования.

    На снимку экрана показано, как сохранить идентификатор секрета клиента для дальнейшего использования.

Чтобы добавить канал Microsoft Teams:

  1. Перейдите на домашнюю страницу.

    Снимок экрана: домашняя страница бота.

  2. Откройте бот, который указан в разделе Последние ресурсы.

  3. Выберите Каналы в области слева и выберите Microsoft Teams .

    Снимок экрана: выбор Teams в каналах.

  4. Установите флажок, чтобы принять условия обслуживания, и нажмите кнопку Принять.

    Снимок экрана: настройка условий, если служба.

  5. Нажмите Сохранить.

    Снимок экрана: добавление канала Microsoft Teams.

Дополнительные сведения см. в статье Создание бота для Teams.

Создание поставщика удостоверений

Вам нужен поставщик удостоверений, которого можно использовать для проверки подлинности. В этой процедуре используется поставщик Azure AD. Также можно использовать другие Azure AD поддерживаемые поставщики удостоверений.

  1. На портале Azure в области навигации слева выберите Azure Active Directory.

    Совет

    Вам потребуется создать и зарегистрировать этот ресурс Azure AD в клиенте, в котором можно предоставить согласие на делегирование разрешений, запрашиваемых приложением. Инструкции по созданию клиента см. в статье Доступ к порталу и создание клиента.

  2. На панели слева выберите Регистрация приложений.

  3. На панели справа выберите вкладку Новая регистрация в левом верхнем углу.

  4. Вам будет предложено указать следующую информацию.

    1. Имя. Введите имя приложения. Примером может быть BotTeamsIdentity. Помните, что имя должно быть уникальным.
    2. Выберите поддерживаемые типы учетных записей для приложения. Выберите Учетные записи в любом каталоге организации (Любая Microsoft Azure Active Directory (Azure AD) — Мультитенантная учетная запись) и личные учетные записи Майкрософт (например, Skype, Xbox).
    3. Для URI перенаправления:
      ✓ Выберите Интернет.
      ✓ Задайте ДЛЯ URL-адреса значение https://token.botframework.com/.auth/web/redirect.
    4. Нажмите Зарегистрировать.
  5. После создания azure отобразит страницу Обзор для приложения. Скопируйте и сохраните следующие сведения в файл.

    1. Значение Идентификатор приложения (клиент). Это значение будет использоваться позже в качестве идентификатора клиента при регистрации этого приложения удостоверений Azure в боте.
    2. Значение Идентификатора каталога (клиент). Это значение также будет использоваться позже в качестве идентификатора клиента для регистрации этого приложения удостоверений Azure в боте.
  6. На панели слева выберите Секреты сертификатов&, чтобы создать секрет клиента для приложения.

    1. В разделе Секреты клиента выберите ➕ Новый секрет клиента.
    2. Добавьте описание, чтобы отличать этот секрет от других секретов, которые может потребоваться создать для этого приложения, например Приложение удостоверений бота в Teams.
    3. Задайте значение для параметра Срок действия.
    4. Нажмите Добавить.
    5. Прежде чем покинуть эту страницу, запишите секрет. Это значение будет использоваться позже в качестве секрета клиента при регистрации приложения Azure AD в боте.

Настройка подключения поставщика удостоверений и его регистрация в боте

Примечание. Здесь доступны два варианта для поставщиков услуг: Azure AD версии 1 и Azure AD версии 2. Различия между двумя поставщиками обобщены здесь, но в целом версия 2 обеспечивает большую гибкость в отношении изменения разрешений бота. В поле областей перечислены разрешения API Graph, а при добавлении новых разрешений боты позволяют пользователям предоставлять согласие на новые разрешения при следующем входе. В версии 1 пользователь должен удалить согласие бота, чтобы в диалоговом окне OAuth были предложены новые разрешения.

Microsoft Azure Active Directory (Azure AD) версии 1

  1. На портале Azure выберите группу ресурсов на панели мониторинга.

  2. Выберите ссылку регистрации бота.

  3. Откройте страницу ресурса и выберите Конфигурация в разделе Параметры.

  4. Нажмите Добавить параметры подключения OAuth. На следующем изображении показан соответствующий выбор на странице ресурса.

    Конфигурация SampleAppDemoBot

  5. Заполните форму следующим образом:

    1. Имя. Введите имя подключения. Это имя будет использоваться в боте в файле appsettings.json. Например, BotTeamsAuthADv1.

    2. Поставщик службы. Выберите Microsoft Azure Active Directory (Azure AD). После выбора этого параметра отобразятся поля, относящиеся к Azure AD.

    3. Идентификатор клиента. Введите идентификатор приложения (клиент), записанный для приложения поставщика удостоверений Azure, на описанных выше шагах.

    4. Секрет клиента. Введите секрет, записанный для приложения поставщика удостоверений Azure, на описанных выше шагах.

    5. Тип предоставления. Введите authorization_code.

    6. URL-адрес входа. Введите https://login.microsoftonline.com.

    7. ИД клиента. Введите идентификатор каталога (клиент), записанный ранее для приложения удостоверений Azure, или общий вариант в зависимости от поддерживаемого типа учетной записи, выбранного при создании приложения поставщика удостоверений. Чтобы решить, какое значение следует назначить, выполните следующие условия:

      • Если вы выбрали учетные записи только в этом каталоге организации (только Майкрософт — один клиент) или учетные записи в любом каталоге организации(Microsoft Azure Active Directory (Azure AD) — Мультитенант), введите идентификатор клиента, записанный ранее для приложение Microsoft Azure Active Directory (Azure AD). Это будет клиент, связанный с пользователями, которые могут проходить проверку подлинности.

      • Если вы выбрали Учетные записи в любом каталоге организации (Любая Microsoft Azure Active Directory (Azure AD) — мультитенантные и личные учетные записи Майкрософт, например Skype, Xbox, Outlook), введите слово common вместо идентификатора клиента. В противном случае приложение Azure AD (Azure AD) проверяет клиент, идентификатор которого был выбран, и исключает личные учетные записи Майкрософт.

    з. Для URL-адреса ресурса введите https://graph.microsoft.com/. Это не используется в текущем примере кода.
    и. Оставьте Области пустыми. Указанное ниже изображение является примером.

    Снимок экрана: добавление подключения удостоверений бота проверки подлинности бота Teams adv1.

  6. Нажмите кнопку Сохранить.

Microsoft Azure Active Directory (Azure AD) версии 2

  1. На портале Azure выберите Azure Bot на панели мониторинга.

  2. На странице ресурса выберите Конфигурация в разделе Параметры.

  3. Нажмите Добавить параметры подключения OAuth.
    На следующем изображении показан соответствующий выбор на странице ресурса.

    Снимок экрана: соответствующий выбор на странице ресурса.

  4. Заполните форму следующим образом:

    1. Имя. Введите имя подключения. Это имя будет использоваться в боте в файле appsettings.json. Например, BotTeamsAuthADv2.

    2. Поставщик службы. Выберите Microsoft Azure Active Directory версии 2. После этого будут отображаться Azure AD определенных полей.

    3. Идентификатор клиента. Введите идентификатор приложения (клиент), записанный для приложения поставщика удостоверений Azure, на описанных выше шагах.

    4. Секрет клиента. Введите секрет, записанный для приложения поставщика удостоверений Azure, на описанных выше шагах.

    5. URL-адрес Exchange маркера. Не заполняйте это поле.

    6. ИД клиента. Введите идентификатор каталога (клиент), записанный ранее для приложения удостоверений Azure, или общий вариант в зависимости от поддерживаемого типа учетной записи, выбранного при создании приложения поставщика удостоверений. Чтобы решить, какое значение следует назначить, выполните следующие условия:

      • Если вы выбрали учетные записи только в этом каталоге организации (только Майкрософт — один клиент) или учетные записи в любом каталоге организации (Microsoft Azure Active Directory — Мультитенант), введите идентификатор клиента, записанный ранее для приложения Azure AD. Это будет клиент, связанный с пользователями, которые могут проходить проверку подлинности.

      • Если вы выбрали Учетные записи в любом каталоге организации (Любая Microsoft Azure Active Directory (Azure AD) — мультитенантные и личные учетные записи Майкрософт, например Skype, Xbox, Outlook), введите слово common вместо идентификатора клиента. В противном случае приложение Azure AD проверяет клиент, идентификатор которого был выбран, и исключает личные учетные записи Майкрософт.

    7. В поле Области введите разделенный пробелами список разрешений графа, необходимых этому приложению, например: User.Read User.ReadBasic.All Mail.Read

  5. Нажмите кнопку Сохранить.

Проверка подключения

  1. Выберите запись подключения, чтобы открыть созданное подключение.

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

  3. При первом выполнении откроется новое окно браузера с просьбой выбрать учетную запись. Выберите учетную запись, которую нужно использовать.

  4. Затем вам будет предложено разрешить поставщику удостоверений использовать ваши данные (учетные данные). Указанное ниже изображение является примером.

    На снимке экрана показано, как добавить строку подключения для проверки подлинности бота Teams adv1.

  5. Выберите Принять.

  6. Затем вы должны будете перенаправляться на страницу "Проверка подключения" на страницу <"Успешно> выполнено ". Обновите страницу, если возникает ошибка. Указанное ниже изображение является примером.

    На снимке экрана показано, как добавить строку подключения проверки подлинности приложения Teams adv1.

Имя подключения используется кодом бота для получения маркеров проверки подлинности пользователя.

Подготовка примера кода бота

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

  1. Клонируйте cs-auth-sample.

  2. Откройте Visual Studio.

  3. На панели инструментов выберите Файл > Открыть > проект или решение и откройте проект бота.

  4. В C# обновите файл appsettings.json следующим образом:

    • Установите для ConnectionName имя подключения поставщика удостоверений, добавленного в регистрацию бота. В этом примере используется имя BotTeamsAuthADv1.
    • Установите для MicrosoftAppId значение идентификатора приложения бота, сохраненного во время регистрации бота.
    • Установите для MicrosoftAppPassword значение секрета клиента, сохраненного во время регистрации бота.

    В зависимости от символов в вашем секрете бота может потребоваться применить escape-последовательность XML для пароля. Например, все амперсанды (&) должны быть закодированы как &amp;.

    {
      "MicrosoftAppType": "",
      "MicrosoftAppId": "",
      "MicrosoftAppPassword": "",
      "ConnectionName": "",
    
  5. В Обозреватель решений перейдите в папкуTeamsAppManifest, откройте manifest.json и задайте id идентификатор botIdприложения бота, сохраненный во время регистрации бота.

Развертывание бота в Azure

Чтобы развернуть бота, выполните действия, описанные в статье Развертывание бота в Azure.

Кроме того, в Visual Studio вы можете выполнить следующие действия.

  1. В Visual Studio Обозреватель решений выберите и удерживайте (или щелкните правой кнопкой мыши) имя проекта.

  2. В раскрывающемся меню выберите Опубликовать.

  3. В появившемся окне щелкните ссылку Создать.

  4. В диалоговом окне выберите Служба приложений слева и Создать справа.

  5. Нажмите кнопку Опубликовать.

  6. В следующем диалоговом окне введите необходимые сведения. Ниже приведен пример.

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

  7. Нажмите Создать.

  8. Если развертывание завершится успешно, вы увидите, что оно отображается в Visual Studio. В браузере по умолчанию отобразится страница с сообщением Ваш бот готов!. URL-адрес будет примерно таким: https://botteamsauth.azurewebsites.net/. Сохраните его в файл.

  9. В браузере перейдите к портал Azure.

  10. Проверьте группу ресурсов. Бот должен быть указан вместе с другими ресурсами. Указанное ниже изображение является примером.

    Снимок экрана: проверка группы ресурсов и бота.

  11. В группе ресурсов выберите имя регистрации бота (ссылка).

  12. На левой панели выберите Параметры.

  13. В поле Конечная точка обмена сообщениями введите URL-адрес, полученный выше, с api/messages в конце. Пример: https://botteamsauth.azurewebsites.net/api/messages.

    Примечание.

    Для бота разрешена только одна конечная точка обмена сообщениями.

  14. Нажмите кнопку Сохранить в левом верхнем углу.

Тестирование бота с помощью Emulator

Если вы еще не сделали этого, установите Microsoft Bot Framework Emulator. См. также статью Отладка с помощью Emulator.

Чтобы работал вход примера бота, необходимо настроить Emulator.

Настройка Emulator для проверки подлинности

Если боту требуется проверка подлинности, необходимо настроить Emulator. Для настройки:

  1. Запустите Emulator.
  2. В эмуляторе щелкните значок ⚙ шестеренки в левом нижнем углу или вкладку Параметры эмулятора в правом верхнем углу.
  3. Установите флажок Использовать маркеры проверки подлинности версии 1.0.
  4. Введите локальный путь к средству ngrok. См.вики-статью об интеграции Bot Framework Emulator и туннелирования ngrok. Дополнительные сведения о средстве см. в разделе ngrok.
  5. Установите флажок Запускать ngrok при запуске Emulator.
  6. Нажмите кнопку Сохранить.

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

Локальное тестирование бота

Настроив механизм проверки подлинности, можно выполнить фактическое тестирование бота.

  1. Запустите пример бота локально на компьютере, например с помощью Visual Studio.

  2. Запустите Emulator.

  3. Нажмите кнопку Открыть бот.

  4. В поле URL-адрес бота введите локальный URL-адрес бота. Обычно это http://localhost:3978/api/messages.

  5. В поле Идентификатор приложения Майкрософт введите идентификатор приложения бота из appsettings.json.

  6. В поле Пароль приложения Майкрософт введите пароль приложения бота из appsettings.json.

  7. Нажмите Подключиться.

  8. После запуска бота введите любой текст, чтобы отобразить карточку входа.

  9. Нажмите кнопку Войти.

  10. Откроется всплывающее диалоговое окно для подтверждения открытого URL-адреса. Это позволяет пользователю бота (вам) проходить проверку подлинности.

  11. Выберите Подтвердить.

  12. При появлении запроса выберите учетную запись соответствующего пользователя.

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

    1. Использование кода проверки входа
      ✓ Откроется окно с кодом проверки.
      ✓ Скопируйте и введите код проверки в поле чата, чтобы завершить вход.
    2. Использование маркеров проверки подлинности.
      ✓ Вы вошли в систему на основе учетных данных.

    На следующем изображении показан пример пользовательского интерфейса бота после входа.

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

  14. Если вы выберете Да , когда бот спрашивает, хотите ли вы просмотреть маркер? вы получите ответ, аналогичный следующему:

    Снимок экрана: выбор согласия.

  15. Введите выход в поле ввода чата, чтобы выйти из системы. Это освобождает маркер пользователя, и бот не сможет действовать от вашего имени, пока вы не выполните вход снова.

Примечание.

Для проверки подлинности бота требуется служба соединителя бота. Служба получает доступ к сведениям о регистрации вашего бота.

Тестирование развернутого бота

  1. В браузере перейдите к портал Azure.

  2. Найдите свою группу ресурсов.

  3. Выберите ссылку ресурса. Отобразится страница ресурса.

  4. На странице ресурса выберите Тестировать в веб-чате. Бот запускается и отображает предопределенное приветствие.

  5. Введите что-либо в поле чата.

  6. Выберите поле Войти.

  7. Откроется всплывающее диалоговое окно для подтверждения открытого URL-адреса. Это позволяет пользователю бота (вам) проходить проверку подлинности.

  8. Выберите Подтвердить.

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

    Снимок экрана: пример пользовательского интерфейса бота Teams после входа в систему.

  10. Нажмите кнопку Да, чтобы отобразить маркер проверки подлинности. Указанное ниже изображение является примером.

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

  11. Введите "выход", чтобы выйти.

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

Примечание.

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

Установка и тестирование бота в Teams

  1. В своем проекте бота убедитесь, что папка TeamsAppManifest содержит manifest.json вместе с файлами outline.png и color.png.

  2. В Обозреватель решений перейдите в папкуTeamsAppManifest. Измените manifest.json, назначив следующие значения.

    1. Назначьте полученный во время регистрации бота идентификатор приложения бота для id и botId.
    2. Назначьте это значение: validDomains: [ "token.botframework.com" ].
  3. Выберите и запакуйте файлы manifest.json, outline.png и color.png.

  4. Откройте Microsoft Teams.

  5. В нижней части панели слева щелкните значок Приложения.

  6. В нижней части панели справа выберите Отправить пользовательское приложение.

  7. Перейдите в папку TeamsAppManifest и отправьте zip-манифест. Отобразится следующий мастер.

    Снимок экрана: пример бота после его отправки в Teams.

  8. Нажмите кнопку Добавить в группу.

  9. В следующем окне выберите команду, в которой нужно использовать бота.

  10. Нажмите кнопку Настройка бота.

  11. Выделите три точки (●●●) на левой панели. Затем щелкните значок портала разработчика .

  12. Выберите вкладку Редактор манифеста. Вы должны увидеть значок отправленного бота.

  13. Кроме того, бот должен появиться в списке чатов в качестве контакта, который можно использовать для обмена сообщениями с ботом.

Локальное тестирование бота в Teams

Teams — это полностью облачный продукт. Для этого требуется, чтобы все службы, к которые она обращается, были доступны из облака с помощью конечных точек HTTPS. Таким образом, чтобы бот (наш пример) работал в Teams, необходимо либо опубликовать код в выбранном вами облаке, либо сделать локально работающий экземпляр доступным из внешней среды через средство туннелирования. Мы рекомендуем ngrok, который создает URL-адрес с внешним адресом для порта, который открывается локально на компьютере. Чтобы настроить ngrok в рамках подготовки к локальному запуску приложения Teams, выполните следующие действия.

  1. В окне терминала перейдите в каталог, в котором установлен ngrok.exe. Рекомендуется настроить путь к переменной среды, чтобы указать на него.

  2. Например, запустите ngrok http 3978 --host-header=localhost:3978. При необходимости замените номер порта. При этом запускается ngrok для прослушивания порта, который вы указали. В ответ он предоставляет доступный из внешней среды URL-адрес, действительный до тех пор, пока запущен ngrok. Указанное ниже изображение является примером.

    Снимок экрана: строка подключения для проверки подлинности приложения бота Teams adv1

  3. Скопируйте HTTPS-адрес переадресации. Он должен выглядеть примерно так: https://dea822bf.ngrok.io/.

  4. Добавьте /api/messages для получения https://dea822bf.ngrok.io/api/messages. Это конечная точка сообщений для бота, работающего локально на компьютере и доступного через Интернет в чате в Teams.

  5. Последним шагом является обновление конечной точки сообщений развернутого бота. В этом примере мы развернули бот в Azure. Давайте выполним следующие действия.

    1. В браузере перейдите к портал Azure.
    2. Выберите Регистрация бота.
    3. На левой панели выберите Параметры.
    4. На правой панели в поле Конечная точка обмена сообщениями введите URL-адрес ngrok (в нашем примере: https://dea822bf.ngrok.io/api/messages).
  6. Запустите бот локально, например в режиме отладки Visual Studio.

  7. Протестируйте бот при локальной работе с помощью тестового веб-чата на портале Bot Framework. Как и Emulator, этот тест не позволяет получить доступ к функциям Teams.

  8. В окне терминала, где запущен ngrok, вы можете увидеть HTTP-трафик между ботом и клиентом веб-чата. Если требуется более подробное представление, в окне браузера введите значение http://127.0.0.1:4040, полученное из предыдущего окна терминала. Указанное ниже изображение является примером.

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

Примечание.

Если остановить и перезапустить ngrok, URL-адрес изменится. Чтобы использовать ngrok в проекте и в зависимости от используемых возможностей, необходимо обновить все ссылки на URL-адрес.

Дополнительные сведения

TeamsAppManifest/manifest.json

Этот манифест содержит сведения, необходимые Teams для подключения к боту:

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0.0",
  "id": "",
  "developer": {
    "name": "TeamsBotAuth",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.teams.com/privacy",
    "termsOfUseUrl": "https://www.teams.com/termsofuse"
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "name": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "description": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "",
      "scopes": [
        "groupchat",
        "team"
      ],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [ "token.botframework.com" ]
}

При проверке подлинности Teams ведет себя немного иначе, чем в других каналах, как описано ниже.

Обработка действия вызова

Боту отправляется действие вызова, а не действие события, используемое другими каналами. Это осуществляется с помощью вложенного класса ActivityHandler.

Bots/DialogBot.cs

    public class DialogBot<T> : TeamsActivityHandler where T : Dialog
    {
        protected readonly BotState ConversationState;
        protected readonly Dialog Dialog;
        protected readonly ILogger Logger;
        protected readonly BotState UserState;

        public DialogBot(ConversationState conversationState, UserState userState, T dialog, ILogger<DialogBot<T>> logger)
        {
            ConversationState = conversationState;
            UserState = userState;
            Dialog = dialog;
            Logger = logger;
        }

        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
        {
            await base.OnTurnAsync(turnContext, cancellationToken);

            // Save any state changes that might have occurred during the turn.
            await ConversationState.SaveChangesAsync(turnContext, false, cancellationToken);
            await UserState.SaveChangesAsync(turnContext, false, cancellationToken);
        }

        protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            Logger.LogInformation("Running dialog with Message Activity.");

            // Run the Dialog with the new message Activity.
            await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
        }
    }
}

Bots/TeamsBot.cs

Действие вызова должно перенаправляться в диалоговое окно, если используется OAuthPrompt.

protected override async Task OnTeamsSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with signin/verifystate from an Invoke Activity.");

    // The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.

    // Run the Dialog with the new Invoke Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

TeamsActivityHandler.cs


protected virtual Task OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    switch (turnContext.Activity.Name)
    {
        case "signin/verifyState":
            return OnSigninVerifyStateAsync(turnContext, cancellationToken);

        default:
            return Task.CompletedTask;
    }
}

protected virtual Task OnSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    return Task.CompletedTask;
}

Пример кода

В этом разделе приведен пример пакета SDK для проверки подлинности бота версии 3.

Название примера Описание .NET Node.js Python
Проверка подлинности бота В этом примере показано, как приступить к проверке подлинности в боте для Teams. Просмотр Просмотр View
Вкладка, бот и расширение сообщений (ME) SSO В этом примере показана система единого входа для Tab, Bot и ME — поиск, действие, linkunfurl. View View Недоступно

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