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

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

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

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

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

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

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

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

• Знание основ бота, управления состоянием, библиотеки диалогов и способа реализации последовательного потока беседы.

• Знание Azure и разработки OAuth 2.0.

• Текущие версии Microsoft Visual Studio и Git.

• Учетная запись Azure. При необходимости вы можете создать бесплатную учетную запись Azure.

• Указанный ниже пример.

  Пример	Версия BotBuilder	Демонстрирует
  Проверка подлинности бота в cs-auth-sample	версия 4	Поддержку OAuthCard
  Проверка подлинности бота в js-auth-sample	версия 4	Поддержку OAuthCard
  Проверка подлинности бота в py-auth-sample	версия 4	Поддержку OAuthCard

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

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

Вы воспользуетесь группой ресурсов с целью создания отдельных ресурсов для 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. Для параметра Тип приложения выберите Мультитенантное в разделе Идентификатор приложения Майкрософт.

   

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

   

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

   Azure подготавливает бота за несколько секунд.

   

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

   

   Бот Azure создан.

   

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

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

   

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

   

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

   

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

   

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

   

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

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

   

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

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

   

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

   

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

   

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

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

Для проверки подлинности требуется поставщик удостоверений. В этой процедуре используется поставщик Microsoft Entra. Кроме того, можно также использовать другие поставщики удостоверений, поддерживаемые Microsoft Entra идентификаторами.

1. В портал Azure на панели навигации слева выберите идентификатор Microsoft Entra.

   Совет

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

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

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

4. Укажите следующую информацию:

   1. Имя. Введите имя приложения. Примером может быть BotTeamsIdentity. Помните, что имя должно быть уникальным.
   2. Выберите поддерживаемые типы учетных записей для приложения. Выберите Учетные записи в любом каталоге организации (клиент с идентификатором любого Microsoft Entra — мультитенантный) и личные учетные записи Майкрософт (например, 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. Прежде чем покинуть эту страницу, запишите секрет. Это значение будет использоваться позже в качестве секрета клиента при регистрации приложения Microsoft Entra в боте.

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

Примечание.

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

Microsoft Azure Active Directory (Azure AD) v1

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

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

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

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

   

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

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

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

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

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

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

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

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

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

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

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

   

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

Microsoft Azure Active Directory (Azure AD) v2

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

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

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

   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   

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

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

   

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

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

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

C#/.NET

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

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

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

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

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

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

   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "",
     "MicrosoftAppPassword": "",
     "ConnectionName": "",
   

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

JavaScript

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

2. В консоли перейдите к проекту:
   
   cd samples/bot-teams-authentication/nodejs

3. Установка модулей
   
   npm install

4. Обновите конфигурацию ENV следующим образом.

   • Установите для MicrosoftAppId значение идентификатора приложения бота, сохраненного во время регистрации бота.
   • Установите для MicrosoftAppPassword значение секрета клиента, сохраненного во время регистрации бота.
   • Установите для connectionName имя подключения поставщика удостоверений. В зависимости от символов в вашем секрете бота может потребоваться применить escape-последовательность XML для пароля. Например, все амперсанды (&) необходимо закодировать как &.

   MicrosoftAppId=
   MicrosoftAppPassword=
   connectionName=
   MicrosoftAppType= MultiTenant # Set this to SingleTenant if you are using a single tenant app registration
   MicrosoftAppTenantId= common # Set your tenantId here if you are using single tenant app registration.
   

5. В папке teamsAppManifest откройте manifest.json и укажите idидентификатор приложения Майкрософт и botIdидентификатор приложения бота , сохраненный во время регистрации бота.

Python

1. Клонируйте py-auth-sample из репозитория GitHub.

2. Обновите config.py:

   • Установите для ConnectionName имя параметра подключения OAuth, добавленного в бот.

   • Установите для MicrosoftAppId и MicrosoftAppPassword значение идентификатора приложения и секрета приложения вашего бота.

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

     APP_ID = os.environ.get("MicrosoftAppId", "")
     APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
     CONNECTION_NAME = os.environ.get("ConnectionName", "")
     

Развертывание бота в 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. Для настройки:

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

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

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

    

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

    

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

Примечание.

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

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

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

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

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

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

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

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

7. Появится всплывающее диалоговое окно Подтвердить открытый URL-адрес для проверки подлинности пользователя бота (вы).

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

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

   

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

    

11. Чтобы выйти из системы, введите logout в поле входного чата.

    

Примечание.

Если при входе возникают проблемы, попробуйте проверить подключение еще раз, как описано в предыдущих шагах. Это может привести к повторному созданию маркера проверки подлинности. При использовании клиента веб-чата 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-манифест. Откроется следующее окно:

   

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. Указанное ниже изображение является примером.

   

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, 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 ведет себя немного иначе, чем другие каналы.

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

Действие Invoke отправляется боту, а не действие события, используемое другими каналами, что выполняется путем подкласса ActivityHandler.

C#/.NET

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;
}

JavaScript

bots/dialogBot.js

const { TeamsActivityHandler } = require('botbuilder');
class DialogBot extends TeamsActivityHandler {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super();
        if (!conversationState) {
            throw new Error('[DialogBot]: Missing parameter. conversationState is required');
        }
        if (!userState) {
            throw new Error('[DialogBot]: Missing parameter. userState is required');
        }
        if (!dialog) {
            throw new Error('[DialogBot]: Missing parameter. dialog is required');
        }

        this.conversationState = conversationState;
        this.userState = userState;
        this.dialog = dialog;
        this.dialogState = this.conversationState.createProperty('DialogState');

        this.onMessage(async (context, next) => {
            console.log('Running dialog with Message Activity.');

            // Run the Dialog with the new message Activity.
            await this.dialog.run(context, this.dialogState);

            await next();
        });
    }

    /**
     * Override the ActivityHandler.run() method to save state changes after the bot logic completes.
     */
    async run(context) {
        await super.run(context);

        // Save any state changes. The load happened during the execution of the Dialog.
        await this.conversationState.saveChanges(context, false);

bots/teamsBot.js

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

const { DialogBot } = require('./dialogBot');

class TeamsBot extends DialogBot {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super(conversationState, userState, dialog);

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            for (let cnt = 0; cnt < membersAdded.length; cnt++) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity('Welcome to TeamsBot. Type anything to get logged in. Type \'logout\' to sign-out.');
                }
            }

            await next();
        });
    }
    
    async handleTeamsSigninVerifyState(context, query) {
        console.log('Running dialog with signin/verifystate from an Invoke Activity.');
        await this.dialog.run(context, this.dialogState);
    }

    async handleTeamsSigninTokenExchange(context, query) {

dialogs/mainDialog.js

На шаге диалогового окна используйте beginDialog, чтобы запустить запрос OAuth, который предлагает пользователю выполнить вход.

• Если пользователь уже вошел в систему, он создает событие ответа маркера без запроса пользователя.
• В противном случае пользователю будет предложено выполнить вход. Служба Azure Bot отправляет событие отклика маркера после попытки пользователя выполнить вход.

async promptStep(stepContext) {
    try {

На следующем шаге диалогового окна проверьте наличие маркера в результате из предыдущего шага. Если значение не равно NULL, пользователь успешно вошел в систему.

async promptStep(stepContext) {
    try {
        return await stepContext.beginDialog(OAUTH_PROMPT);
    } catch (err) {
        console.error(err);
    }
}

async loginStep(stepContext) {
    // Get the token from the previous step. Note that we could also have gotten the
    // token directly from the prompt itself. There is an example of this in the next method.
    const tokenResponse = stepContext.result;
    if (!tokenResponse || !tokenResponse.token) {
        await stepContext.context.sendActivity('Login was not successful please try again.');

dialogs/logoutDialog.js

async interrupt(innerDc) {
    if (innerDc.context.activity.type === ActivityTypes.Message) {
        const text = innerDc.context.activity.text.toLowerCase();
        if (text === 'logout') {
            const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

            const { activity } = innerDc.context;
            await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

            await innerDc.context.sendActivity('You have been signed out.');
            return await innerDc.cancelAllDialogs();
        }

Python

bots/dialog_bot.py

def __init__(
    self,
    conversation_state: ConversationState,
    user_state: UserState,
    dialog: Dialog,
):
    if conversation_state is None:
        raise Exception(
            "[DialogBot]: Missing parameter. conversation_state is required"
        )
    if user_state is None:
        raise Exception("[DialogBot]: Missing parameter. user_state is required")
    if dialog is None:
        raise Exception("[DialogBot]: Missing parameter. dialog is required")

    self.conversation_state = conversation_state
    self.user_state = user_state
    self.dialog = dialog

async def on_turn(self, turn_context: TurnContext):
    await super().on_turn(turn_context)

    # Save any state changes that might have occurred during the turn.
    await self.conversation_state.save_changes(turn_context, False)
    await self.user_state.save_changes(turn_context, False)

async def on_message_activity(self, turn_context: TurnContext):
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

bots/teams_bot.py

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

async def on_teams_signin_verify_state(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    # The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

dialogs/main_dialog.py

На шаге диалогового окна используйте begin_dialog, чтобы запустить запрос OAuth, который предлагает пользователю выполнить вход.

• Если пользователь уже вошел в систему, он создает событие ответа маркера без запроса пользователя.
• В противном случае пользователю будет предложено выполнить вход. Служба Azure Bot отправляет событие отклика маркера после попытки пользователя выполнить вход.

async def prompt_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    return await step_context.begin_dialog(OAuthPrompt.__name__)

На следующем шаге диалогового окна проверьте наличие маркера в результате из предыдущего шага. Если значение не равно NULL, пользователь успешно вошел в систему.

async def login_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    # Get the token from the previous step. Note that we could also have gotten the
    # token directly from the prompt itself. There is an example of this in the next method.
    if step_context.result:
        await step_context.context.send_activity("You are now logged in.")
        return await step_context.prompt(
            ConfirmPrompt.__name__,
            PromptOptions(
                prompt=MessageFactory.text("Would you like to view your token?")
            ),
        )

dialogs/logout_dialog.py

text = inner_dc.context.activity.text.lower()
if text == "logout":
    bot_adapter: BotFrameworkAdapter = inner_dc.context.adapter
    await bot_adapter.sign_out_user(inner_dc.context, self.connection_name)
    await inner_dc.context.send_activity("You have been signed out.")
    return await inner_dc.cancel_all_dialogs()

Пример кода

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

Название примера	Описание	.NET	Node.js	Python	Манифест
Проверка подлинности бота	В этом примере показано, как приступить к проверке подлинности в боте для Teams.	Просмотр	Просмотр	Просмотр	Просмотр
Единый вход в tab, bot и message extension (ME)	В этом примере показан Microsoft Entra единого входа для Tab, Bot и ME — поиск, действие, распутывание ссылок.	Просмотр	Просмотр	Н/Д	Просмотр

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

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