Добавление проверки подлинности в ботAdd authentication to a bot

применимо к: Пакет SDK v4APPLIES TO: SDK v4

Пакет SDK для службы Azure Bot версии 4 упрощает разработку программы-роботы, которая может получать доступ к сетевым ресурсам, требующим проверки подлинности пользователей.The Azure Bot Service v4 SDK facilitates the development of bots that can access online resources that require user authentication. Роботу не требуется управлять маркерами проверки подлинности, так как Azure позволяет использовать OAuth 2,0 для создания маркера на основе учетных данных каждого пользователя.Your bot does not need to manage authentication tokens because Azure does it for you using OAuth 2.0 to generate a token based on each user's credentials. Бот будет использовать маркеры, созданные в Azure, для доступа к нужным ресурсам.Your bot uses the token generated by Azure to access those resources. Таким образом, пользователю не нужно передавать идентификатор и пароль для доступа к защищенному ресурсу в бот, а только доверенному поставщику удостоверений.In this way, the user does not have to provide ID and password to the bot to access a secured resource but only to a trusted identity provider.

Общие сведения о том, как платформа Bot обрабатывает такой тип проверки подлинности, см. в разделе Проверка подлинности пользователя.For an overview of how the Bot Framework handles this kind of authentication, see User authentication.

Примечание

Проверка подлинности также работает с Bot Builder версии 3.Authentication also works with BotBuilder v3. Но в этой статье рассматривается только пример кода версии 4.However, this article covers just the v4 sample code.

Эта статья содержит ссылки на два примера.This article references two samples. Один из них демонстрирует, как получить маркер проверки подлинности.One shows how to obtain an authentication token. другой является более сложным и показывает, как получить доступ к Microsoft Graph от имени пользователя.The other is more complex and shows how to access Microsoft Graph on behalf of the user. В обоих случаях маркер OAuth для бота можно получить, используя Azure Active Directory (AD) версии 1 или 2 в качестве поставщика удостоверений.In both cases you can use Azure Active Directory (AD) v1 or Azure AD v2 as an identity provider to obtain an OAuth token for the bot. В этой статье рассматриваются следующие вопросы:This article covers how to:

Завершив работу с этой статьей, вы получите готовый бот, который умеет выполнять несколько простых задач.Once you finish this article, you will have a bot that can respond to a few simple tasks. В примере для Microsoft Graph можно отправить электронное сообщение, отобразить информацию о себе и проверить последние электронные сообщения.In the case of the Microsoft Graph example, you can send an email, display who you are, and check recent emails. Вам не обязательно публиковать бота, чтобы протестировать возможности OAuth, но боту требуется допустимый идентификатор приложения Azure и пароль к нему.You do not need to publish the bot to test the OAuth features; however, the bot will need valid Azure app ID and password.

Рекомендации по веб-чатам и Direct LineWeb Chat and Direct Line considerations

Важно!

Чтобы снизить риски безопасности при подключении к роботу с помощью элемента управления "веб-чат", необходимо использовать прямую линию с включенной расширенной проверкой подлинности.You need to use Direct Line with enhanced authentication enabled to mitigate security risks when connecting to a bot using the Web Chat control. Дополнительные сведения см. в разделе Прямая строка Расширенная проверка подлинности.For more information, see Direct Line enhanced authentication.

Предварительные требованияPrerequisites

ОбразецSample Версия Bot BuilderBotBuilder version Что демонстрируетDemonstrates
Проверка подлинности в C# или JavaScript или Java или PythonAuthentication in C# or JavaScript or Java or Python версия 4v4 Поддержка OAuthCardOAuthCard support
Мсграф проверки подлинности в C# или JavaScript , Java или PythonAuthentication MSGraph in C# or JavaScript or Java or Python версия 4v4 Поддержка API Microsoft Graph с использованием OAuth 2Microsoft Graph API support with OAuth 2

Сведения об образцахAbout the samples

Чтобы выполнить указанные в этой статье примеры, вам потребуется следующее:To run the samples referenced in this article, you need the following:

  1. Приложение Azure Active Directory (AAD) для регистрации ресурса бота в Azure.An Azure Active Directory (AD) application to register a bot resource in Azure. Это приложение позволяет боту обращаться к внешнему защищенному ресурсу, например Microsoft Graph.This application allows the bot to access an external secured resource, such as Microsoft Graph. Также оно позволяет пользователю взаимодействовать с ботом через несколько каналов, таких как Web Chat.It also allows the user to communicate with the bot via several channels such as Web Chat.
  2. Отдельное приложение AAD в роли поставщика удостоверений.A separate Azure AD application that functions as the identity provider. Это приложение предоставит учетные данные, необходимые для установки соединения OAuth между ботом и защищенным ресурсом.This application provides the credentials needed to establish an OAuth connection between the bot and the secured resource. Обратите внимание, что в этой статье в качестве поставщика удостоверений используется Active Directory.Notice that this article uses Active Directory as an identity provider. Поддерживаются и другие поставщики.Many other providers are also supported.

Важно!

Каждому зарегистрированному в Azure боту назначается приложение AAD.Whenever you register a bot in Azure, it gets assigned an Azure AD application. Но это приложение защищает доступ из канала к боту.However, this application secures channel-to-bot access. Вам потребуются дополнительные приложения AAD для каждого внешнего защищенного ресурса, к которым бот должен обращаться от имени пользователя.You need an additional Azure AD application for each external secured resource you want the bot to access on behalf of the user.

Создание ресурсаCreate the resource

Создайте ресурс Azure Bot , который позволит зарегистрировать программу Bot в службе Azure Bot.Create the Azure Bot resource, which will allow you to register your bot with the Azure Bot Service.

Предупреждение

Регистрация веб-приложения и канала Bot не рекомендуется, но существующие ресурсы будут продолжать работать.Web App Bot and Bot Channels Registration will be deprecated but existing resources will continue to work. Вместо этого следует использовать Azure Bot.You should use Azure Bot, instead.

  1. Перейдите на портал Azure.Go to the Azure portal.

  2. В области справа выберите создать ресурс.In the right pane, select Create a resource.

  3. В поле поиска введите Bot, а затем нажмите клавишу Ввод.In the search box enter bot, then press Enter.

  4. Выберите карту Azure Bot .Select the Azure Bot card.

    Выбор ресурса Azure Bot

  5. Нажмите кнопку создания.Select Create.

    Создание ресурса Azure Bot

  6. Введите необходимые значения.Enter the required values. На следующем рисунке показано, как создать новый идентификатор приложения Microsoft .The following figure shows Create new Microsoft App ID selected.

    Создание значений ресурсов Azure Bot

    Можно также выбрать параметр использовать регистрацию существующего приложения и ввести существующий идентификатор приложения и пароль.You can also select Use existing app registration and enter your existing app Id and password.

    Создание существующих значений ресурса Azure Bot

  7. Выберите Review + create (Просмотреть и создать).Select Review + create.

  8. Если проверка пройдена, выберите создать.If the validation passes, select Create.

  9. Выберите Перейти к группе ресурсов.Select Go to resource group. Вы увидите робот и связанные Azure Key Vault ресурсы, перечисленные в выбранной группе ресурсов.You should see the bot and the related Azure Key Vault resources listed in the resource group you selected.

    Совет

    Секрет приложения (пароль) хранится в хранилище ключей, и для каждой группы ресурсов существует одно хранилище ключей.The app secret (password) is stored in the the key vault and there is one key vault per resource group. Рекомендуется использовать хранилище ключей вместо копирования и хранения конфиденциальных данных.Using key vault is recommended instead of copying and storing sensitive data.

  10. Выберите получить пакет SDK из GitHub , чтобы создать программу-робот с пакетом SDK для Bot Framework.Select Get the SDK from Github to build your bot with the Bot Framework SDK.

    Создание программы-робота в пакете SDK

Azure Key VaultAzure Key Vault

Когда Azure создает ресурс Azure Bot, он также создает идентификатор приложения и пароль и сохраняет пароль в Azure Key Vault.When Azure creates the Azure Bot resource, it also generates an app Id and a password and stores the password in Azure Key Vault.

Key Vault — это служба, которая обеспечивает централизованное управление секретами с полным контролем над политиками доступа и журналом аудита.Key Vault is a service that provides centralized secrets management, with full control over access policies and audit history. Дополнительные сведения см. в статье использование Key Vault ссылок для службы приложений и функций Azure.For more information, see Use Key Vault references for App Service and Azure Functions. Обратите внимание, что плата за использование службы будет взиматься за небольшую плату.Note that you will be charged a small fee for using the service. Дополнительные сведения см. в разделе цены на Key Vault.For more information, see Key Vault pricing.

Идентификатор и пароль приложенияApp Id and password

Чтобы настроить программу-робот для развертывания, необходимо указать идентификатор и пароль приложения Azure Bot.You need the Azure bot resource app Id and password to configure your bot for deployment. Вы назначите их значения связанным переменным: MicrosoftAppId и они MicrosoftAppPassword содержатся в файле конфигурации проекта Bot.You will assign their values to the related variables: MicrosoftAppId and MicrosoftAppPassword contained in your bot project configuration file. Файл зависит от языка программирования, используемого для создания программы-робота, как показано ниже.The file differs depending on the programming language you use to create the bot, as shown below.

appsettings.jsonФайл содержит следующие параметры:The appsettings.json file contains these settings:

{
  "MicrosoftAppId": "<your app id>",
  "MicrosoftAppPassword": "<your password>"
}

Получение идентификатора приложения Azure Bot Resource IDGet Azure bot resource app Id

  1. Перейдите на портал Azure.Go to the Azure portal.
  2. Выберите ресурс Azure Bot, чтобы получить идентификатор своего приложения.Select the Azure bot resource to obtain its app Id.
  3. в левой области в разделе Параметры выберите конфигурация.In the left pane, in the Settings section, select Configuration.
  4. Скопируйте и сохраните значение, содержащееся в поле идентификатор приложения Microsoft .Copy and save the value contained in the Microsoft App ID box.

Получение пароля ресурса Azure Bot из Azure Key VaultGet Azure bot resource password from Azure Key Vault

Когда Azure создает ресурс Azure Bot, он сохраняет пароль приложения в Azure Key Vault.When Azure creates the Azure Bot resource, it stores the app password in Azure Key Vault. Дополнительные сведения о доступе к хранилищу ключей для получения пароля см. в следующих статьях:For information on how to access the key vault to obtain your password, see:

Служба удостоверений Azure ADAzure AD identity service

Облачная служба идентификации Azure Active Directory (Azure AD) позволяет создавать приложения с поддержкой безопасного входа пользователей по стандартным отраслевым протоколам, таким как OAuth 2.0.The Azure Active Directory (Azure AD) is a cloud identity service that allows you to build applications that securely sign in users using industry standard protocols like OAuth2.0.

Вы можете выбрать одну из двух служб идентификации:You can use one of these two identity services:

  1. Платформа разработчиков Azure AD (версия 1.0).Azure AD developer platform (v1.0). Это конечная точка AAD версии 1, которая позволяет создавать приложения с поддержкой безопасного входа пользователей с рабочей или учебной учетной записью Майкрософт.Also known as the Azure AD v1 endpoint, which allows you to build apps that securely sign in users with a Microsoft work or school account. См. сведения об Azure Active Directory для разработчиков (версия 1.0).For more information, see the Azure Active Directory for developers (v1.0) overview.
  2. Платформа удостоверений Майкрософт (версия 2.0)Microsoft identity platform (v2.0). Это конечная точка AAD версии 2 — доработанная и улучшенная версия платформы AAD (версия 1.0).Also known as the Azure AD v2 endpoint, which is an evolution of the Azure AD platform (v1.0). С ее помощью вы можете создавать приложения, которые поддерживают вход через любых поставщиков удостоверений Майкрософт и получение токенов для вызова таких программных API Майкрософт, как API Microsoft Graph или других API, созданных разработчиками.It allows you to build applications that sign in to all Microsoft identity providers and get tokens to call Microsoft APIs, such as Microsoft Graph, or other APIs that developers have built. См. сведения о платформе удостоверений Майкрософт (версия 2.0).For more information, see the Microsoft identity platform (v2.0) overview,

См. сведения о различиях между конечными точками версий 1 и 2 в статье Зачем выполнять обновление до платформы удостоверений Майкрософт (версия 2.0)?For information about the differences between the v1 and v2 endpoints, see Why update to Microsoft identity platform (v2.0)?. См. сведения в статье Платформа удостоверений Майкрософт (ранее Azure Active Directory для разработчиков).For complete information, see Microsoft identity platform (formerly Azure Active Directory for developers).

Создание поставщика удостоверений Azure ADCreate the Azure AD identity provider

В этом разделе показано, как создать поставщик удостоверений Azure AD, использующий OAuth2 для проверки подлинности Bot.This section shows how to create an Azure AD identity provider that uses OAuth2 to authenticate the bot. Вы можете использовать конечные точки AAD версии 1 или 2.You can use Azure AD v1 or Azure AD v2 endpoints.

Совет

Вам понадобится создать и зарегистрировать приложение Azure AD в клиенте, в котором можно дать согласие на делегирование разрешений, запрошенных приложением.You will need to create and register the Azure AD application in a tenant in which you can consent to delegate permissions requested by an application.

  1. Откройте панель Azure Active Directory на портале Azure.Open the Azure Active Directory panel in the Azure portal. Если вы не попадете сразу в нужный арендатор, щелкните действие Переключить каталог.If you are not in the correct tenant, click Switch directory to switch to the correct tenant. (См. инструкции по созданию арендатора с помощью портала.)(For instruction on creating a tenant, see Access the portal and create a tenant.)

  2. Откройте панель Регистрация приложений.Open the App registrations panel.

  3. На панели Регистрация приложений щелкните Новая регистрация.In the App registrations panel, click New registration.

  4. Заполните обязательные поля и создайте регистрацию приложения.Fill in the required fields and create the app registration.

    1. Присвойте имя приложению.Name your application.

    2. Выберите Поддерживаемые типы учетных записей для приложения.Select the Supported account types for your application. (Все эти параметры будут работать с этим примером.)(Any of these options will work with this sample.)

    3. Для URI перенаправления:For the Redirect URI

      1. Выберите Интернет.Select Web.
      2. Укажите для URL-адреса значение https://token.botframework.com/.auth/web/redirect.Set the URL to https://token.botframework.com/.auth/web/redirect.
    4. Щелкните Зарегистрировать.Click Register.

      • После создания в Azure отображается страница Обзор для приложения.Once it is created, Azure displays the Overview page for the app.
      • Запишите идентификатор приложения (клиента) .Record the Application (client) ID value. Это значение будет использоваться позже в качестве идентификатора клиента при создании строки подключения и регистрации поставщика Azure AD с регистрацией Bot.You will use this value later as the Client id when you create the connection string and register the Azure AD provider with the bot registration.
      • Также запишите идентификатор каталога (арендатора) .Also record the Directory (tenant) ID value. Кроме того, вы будете использовать его для регистрации приложения поставщика с помощью программы Bot.You will also use this to register this provider application with your bot.
  5. В области навигации щелкните Сертификаты и секреты, чтобы создать секрет для приложения.In the navigation pane, click Certificates & secrets to create a secret for your application.

    1. В разделе Секреты клиента щелкните New client secret (Новый секрет клиента).Under Client secrets, click New client secret.
    2. Добавьте описание, чтобы отличать этот секрет от других секретов, которые могут вам понадобиться для создания этого приложения, включая bot login.Add a description to identify this secret from others you might need to create for this app, such as bot login.
    3. Задайте для параметра Срок действия истекает значение Никогда.Set Expires to Never.
    4. Нажмите кнопку Добавить.Click Add.
    5. Перед закрытием этой страницы запишите секрет.Before leaving this page, record the secret. Это значение вам нужно будет ввести позднее в поле Секрет клиента при регистрации приложения AAD в боте.You will use this value later as the Client secret when you register your Azure AD application with your bot.
  6. В области навигации щелкните Разрешения API, чтобы открыть панель Разрешения API.In the navigation pane, click API permissions to open the API permissions panel. Рекомендуется явно задать разрешения API для приложения.It is a best practice to explicitly set the API permissions for the app.

    1. Щелкните Добавить разрешение, чтобы отобразить область Запрос разрешений API.Click Add a permission to show the Request API permissions pane.

    2. Для этого примера выберите API Microsoft и Microsoft Graph.For this sample, select Microsoft APIs and Microsoft Graph.

    3. Выберите Делегированные разрешения и убедитесь, что выбраны все разрешения,Choose Delegated permissions and make sure the permissions you need are selected. требуемые для этого примера.This sample requires theses permissions.

      Примечание

      Для любого разрешения, отмеченного как Требуется согласие администратора, необходимо, чтобы пользователь и администратор клиента вошли в систему. Поэтому для бота лучше использовать поменьше разрешений такого типа.Any permission marked as ADMIN CONSENT REQUIRED will require both a user and a tenant admin to login, so for your bot tend to stay away from these.

      • openidopenid
      • profileprofile
      • Mail.ReadMail.Read
      • Mail.SendMail.Send
      • User.ReadUser.Read
      • User.ReadBasic.AllUser.ReadBasic.All
    4. Щелкните Добавить разрешения.Click Add permissions. (При первом обращении пользователя к этому приложению через бота требуется предоставить согласие.)(The first time a user accesses this app through the bot, they will need to grant consent.)

Теперь приложение Azure AD настроено.You now have an Azure AD application configured.

Примечание

При создании строки подключения и регистрации поставщика удостоверений с регистрацией Bot вы назначаете идентификатор приложения (клиент) и секрет клиента.You will assign the Application (client) ID and the Client secret, when you create the connection string and register the identity provider with the bot registration. Ознакомьтесь со следующим разделом.See next section.

Регистрация поставщика удостоверений Azure AD с помощью программы-роботаRegister the Azure AD identity provider with the bot

Следующим шагом является регистрация только что созданного приложения AAD в боте.The next step is to register the Azure AD application that you just created with the bot.

AAD версии 2Azure AD v2

  1. Перейдите к странице регистрации каналов бота на портале Azure.Navigate to your bot's Bot Channels Registration page on the Azure Portal.

  2. Щелкните Параметры.Click Settings.

  3. В разделе OAuth Connection Settings (Параметры подключения OAuth), который находится в нижней части страницы, щелкните Добавить настройку.Under OAuth Connection Settings near the bottom of the page, click Add Setting.

  4. Заполните форму следующим образом.Fill in the form as follows:

    1. Имя.Name. Введите имя для подключения.Enter a name for your connection. которое было использовано в коде бота.You'll use it in your bot code.

    2. Поставщик услуг.Service Provider. выберите Azure Active Directory v2.Select Azure Active Directory v2. После выбора этого параметра появятся отдельные поля Azure AD.Once you select this, the Azure AD-specific fields will be displayed.

    3. Идентификатор клиента. Введите идентификатор приложения (клиента), записанный для поставщика удостоверений Azure AD v2.Client id. Enter the application (client) ID you recorded for your Azure AD v2 identity provider.

    4. Секрет клиента.Client secret. Введите секрет, который вы записали для поставщика удостоверений Azure AD v2.Enter the secret you recorded for your Azure AD v2 identity provider.

    5. URL-адрес Exchange токена.Token Exchange URL. Оставьте это поле пустым, так как оно используется только для единого входа в Azure AD v2.Leave it blank because it is used for SSO in Azure AD v2 only.

    6. Идентификатор клиента.Tenant ID. Введите идентификатор каталога (клиента) , записанный ранее для приложения AAD, или Общие в зависимости от поддерживаемых типов учетных записей, выбранных при создании приложения Azure DD.Enter the directory (tenant) ID that your recorded earlier for your AAD app or common depending on the supported account types selected when you created the Azure DD app. Чтобы решить, какое значение следует задать, руководствуйтесь следующими критериями:To decide which value to assign follow these criteria:

      • Если при создании приложения AAD вы выбрали параметр Учетные записи только в этом каталоге организации (только Майкрософт — один клиент) , введите идентификатор клиента, который вы записали ранее для этого приложения AAD.When creating the Azure AD app if you selected Accounts in this organizational directory only (Microsoft only - Single tenant) enter the tenant ID you recorded earlier for the AAD app.
      • Если же вы выбрали Учетные записи в любом каталоге организации (любой каталог Azure AD — мультитенантный и личные учетные записи Майкрософт (например, Xbox, Outlook.com)) или Учетные записи в любом каталоге организации (любой каталог Azure AD — мультитенантный) , введите слово общие вместо идентификатора клиента.However, if you selected Accounts in any organizational directory (Any AAD directory - Multi tenant and personal Microsoft accounts e.g. Xbox, Outlook.com) or Accounts in any organizational directory(Microsoft Azure AD directory - Multi tenant) enter the word common instead of a tenant ID. В противном случае приложение AAD будет проверять клиент по выбранному для него идентификатору и исключать личные учетные записи Майкрософт.Otherwise, the AAD app will verify through the tenant whose ID was selected and exclude personal MS accounts.

      Данный клиент будет связан с пользователями, которые могут пройти проверку подлинности.This will be the tenant associated with the users who can be authenticated. Дополнительные сведения см. в этой статье.For more information, see Tenancy in Azure Active Directory.

    7. В поле области введите имена разрешений, которые вы выбрали при регистрации приложения.For Scopes, enter the names of the permission you chose from the application registration. В целях тестирования можно просто ввести: openid profile .For testing purposes, you can just enter: openid profile.

      Примечание

      Для приложения Azure AD версии 2 в поле Области принимаются списки разделенных пробелами значений с учетом регистра.For Azure AD v2, Scopes field takes a case-sensitive, space-separated list of values.

  5. Выберите команду Сохранить.Click Save.

Примечание

Используя API Microsoft Graph, эти значения позволяют приложению получать доступ к данным Office 365.These values enable your application to access Office 365 data via the Microsoft Graph API. Кроме того, поле URL-адрес обмена маркерами следует оставить пустым, так как оно используется только для единого входа в Azure AD версии 2.Also, the Token Exchange URL should be left blank because it is used for SSO in Azure AD v2 only.

Тестирование подключенияTest your connection

  1. Щелкните запись созданного подключения, чтобы открыть его.Click on the connection entry to open the connection you just created.
  2. Щелкните Проверка подключения в верхней части области Service Provider Connection Setting (Параметры подключения поставщика службы).Click Test Connection at the top of the Service Provider Connection Setting pane.
  3. При выполнении данного действия в первый раз должна открыться новая вкладка браузера с перечисленными разрешениями, которые запрашивает приложение, и предложение их принять.The first time, this should open a new browser tab listing the permissions your app is requesting and prompt you to accept.
  4. Нажмите кнопку Принимаю.Click Accept.
  5. Вы перейдете на страницу Проверка подключения к <your-connection-name> успешно выполнена.This should then redirect you to a Test Connection to <your-connection-name> Succeeded page.

Для получения токенов пользователя можно использовать имя этого подключения в коде бота.You can now use this connection name in your bot code to retrieve user tokens.

Подготовка кода ботаPrepare the bot code

Вам потребуются идентификатор приложения бота и пароль, чтобы выполнить этот процесс.You will need your bot's app ID and password to complete this process.

  1. Клонируйте нужный пример из репозитория GitHub: Аутентификация бота или Аутентификация бота (MSGraph).Clone from the github repository the sample you want to work with: Bot authentication or Bot authentication MSGraph.

  2. Обновите файл appsettings.json:Update appsettings.json:

    • параметру ConnectionName присвойте значение имени подключения OAuth, которое вы добавили в бот;Set ConnectionName to the name of the OAuth connection setting you added to your bot.

    • параметрам MicrosoftAppId и MicrosoftAppPassword присвойте значения идентификатора приложения бота и секрета приложения.Set MicrosoftAppId and MicrosoftAppPassword to your bot's app ID and app secret.

      В зависимости от символов, из которых состоит секрет бота, может потребоваться XML-экранирование пароля.Depending on the characters in your bot secret, you may need to XML escape the password. Например, символ амперсанда (&) потребуется кодировать как &amp;.For example, any ampersands (&) will need to be encoded as &amp;.

    {
      "MicrosoftAppId": "",
      "MicrosoftAppPassword": "",
      "ConnectionName": ""
    }
    
  3. Обновление запуска. CS:Update startup.cs:

    Чтобы использовать OAuth в не общедоступных облаках Azure, например в облаке для государственных организаций, необходимо добавить в файл следующий код startup.cs :To use OAuth in non-public Azure clouds, like government cloud, you must add the following code in the startup.cs file:

    string uri = "https://api.botframework.azure.us";
    MicrosoftAppCredentials.TrustServiceUrl(uri);
    OAuthClientConfig.OAuthEndpoint = uri;
    

Чтобы получить идентификатор приложения Microsoft и значения пароля Microsoft App , см. статью Получение пароля регистрации.To obtain the Microsoft app ID and Microsoft app password values, see Get registration password.

Примечание

Теперь код бота можно опубликовать в подписке Azure (щелкните проект правой кнопкой мыши и выберите Опубликовать), но для этой статьи это не требуется.You could now publish this bot code to your Azure subscription (right-click on the project and choose Publish), but it is not necessary for this article. Вам нужно настроить конфигурацию публикации, которая использует план приложения и размещения, с помощью которого выполнялась настройка бота на портале Azure.You would need to set up a publishing configuration that uses the application and hosting plan that you used when configuration the bot in the Azure portal.

Тестирование программы-робота с помощью EmulatorTest the bot using the Emulator

Установите Bot Framework Emulator, если вы этого еще не сделали.If you have not done so already, install the Bot Framework Emulator. См. также Отладка с Emulator.See also Debug with the Emulator.

чтобы имя входа для примера bot работало, необходимо настроить Emulator, как показано в подокне настройка Emulator для проверки подлинности.In order for the bot sample login to work you must configure the Emulator as shown in Configure the Emulator for authentication.

ТестированиеTesting

Когда вы настроите механизм аутентификации, можно протестировать пример бота.After you have configured the authentication mechanism, you can perform the actual bot sample testing.

Примечание

Возможно, вам будет предложено ввести магический код, так как реализуется пример бота.You may be asked to enter a magic code, because the way the bot sample is implemented. Этот магический код рассматривается в документе RFC#7636 и предназначен для добавления дополнительного элемента безопасности.This magic code is part of the RFC#7636 and is there to add an extra security element. Удаление магического кода повышает риск возникновения угрозы безопасности.By removing the magic code, there is an increased security risk. Это можно устранить с помощью прямой линии с включенной расширенной проверкой подлинности.This can be mitigated using Direct Line with enhanced authentication enabled. Дополнительные сведения см. в статье о расширенной проверке подлинности в Bot Framework.For more information, see Bot Framework enhanced authentication.

  1. Запустите пример бота на локальном компьютере.Run the bot sample locally on your machine.
  2. Запустите эмулятор Bot Framework.Start the Emulator.
  3. При подключении к боту необходимо указать идентификатор приложения бота и пароль.You will need to provide your bot's app ID and password when you connect to the bot.
    • Идентификатор приложения и пароль можно получить в области регистрации приложений Azure.You get the app ID and the password from the Azure app registration. Это те же значения, которые вы назначили боту в файле appsettings.json или .env.These are the same values you assigned to the bot app in the appsettings.json or .env file. в Emulator эти значения присваиваются в файле конфигурации или в первый раз при подключении к bot.In the Emulator, you assign these values in the configuration file or the first time you connect to the bot.
    • Вы также можете экранировать пароль (XML) в коде бота.If you needed to XML-escape the password in your bot code, you also need to do so here.
  4. Чтобы просмотреть список доступных команд для бота и проверить функции проверки подлинности, введите help.Type help to see a list of available commands for the bot, and test the authentication features.
  5. После выполнения входа и до момента выхода не требуется повторно предоставлять учетные данные.Once you've signed in, you don't need to provide your credentials again until you sign out.
  6. Чтобы выйти и отменить проверку подлинности, введите logout.To sign out, and cancel your authentication, type logout.

Примечание

Для использования проверки подлинности бота требуется служба Bot Connector.Bot authentication requires use of the Bot Connector Service. Эта служба использует сведения о регистрации каналов бота.The service accesses the bot channels registration information for your bot.

Пример проверки подлинностиAuthentication example

В примере Аутентификация бота диалог получает маркер пользователя после входа пользователя в систему.In the Bot authentication sample, the dialog is designed to retrieve the user token after the user is logged in.

тестовое изображение для проверки подлинности Bot

Пример проверки подлинности МсграфAuthentication MSGraph example

В примере Аутентификация бота MSGraph диалог принимает ограниченный набор команд после входа пользователя в систему.In the Bot authentication MSGraph sample, the dialog is designed to accept a limited set of commands after the user is logged in.

тестовое изображение мсграф Bot


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

Когда пользователь приказывает боту выполнить некоторые действия, которые требуют пользовательского входа, бот может с помощью OAuthPrompt инициировать извлечение токена для данного соединения.When a user asks the bot to do something that requires the bot to have the user logged in, the bot can use an OAuthPrompt to initiate retrieving a token for a given connection. OAuthPrompt создает поток получения маркера, который выполняет следующие действия.The OAuthPrompt creates a token retrieval flow that consists of:

  1. Проверяет, имеет ли служба Azure Bot маркер для текущего сочетания пользователя и подключения.Checking to see if the Azure Bot Service already has a token for the current user and connection. Если маркер есть, он возвращается.If there is a token, the token is returned.
  2. Если служба Azure Bot не имеет нужного маркера в кэше, создается OAuthCard с кнопкой входа, на которую может нажать пользователь.If Azure Bot Service does not have a cached token, an OAuthCard is created which is a sign in button the user can click on.
  3. Когда пользователь нажимает на кнопку входа OAuthCard, служба Azure Bot выполняет одно из двух действий: напрямую отправляет боту маркер пользователя или предоставляет пользователю шестизначный код аутентификации для ввода в окно чата.After the user clicks on the OAuthCard sign in button, Azure Bot Service will either send the bot the user's token directly or will present the user with a 6-digit authentication code to enter in the chat window.
  4. Если пользователю предоставлен код аутентификации, бот позднее обменивает этот код на маркер пользователя.If the user is presented with an authentication code, the bot then exchanges this authentication code for the user's token.

В следующих разделах объясняется, как этот пример реализует некоторые распространенные задачи проверки подлинности.The following sections describe how the sample implements some common authentication tasks.

Использование запроса OAuth для входа пользователя и получения маркераUse an OAuth prompt to sign the user in and get a token

образ архитектуры CSharp

Dialogs\MainDialog.csDialogs\MainDialog.cs

Добавьте запрос OAuth в MainDialog с помощью конструктора.Add an OAuth prompt to MainDialog in its constructor. Здесь мы получаем значение имени подключения из файла appsettings.json.Here, the value for the connection name was retrieved from the appsettings.json file.

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

В шаге диалога укажите BeginDialogAsync для запуска командной строки OAuth, в которой пользователю будет предложено войти в систему.Within a dialog step, use BeginDialogAsync to start the OAuth prompt, which asks the user to sign in.

  • Если пользователь уже выполнил вход, будет создано событие ответа маркера без подтверждения пользователя.If the user is already signed in, this will generate a token response event, without prompting the user.
  • В противном случае пользователю будет предложено войти в систему.Otherwise, this will prompt the user to sign in. Служба Azure Bot отправляет событие ответа маркера после попытки входа пользователя.The Azure Bot Service sends the token response event after the user attempts to sign in.
return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

В следующем шаге диалога проверьте наличие маркера в результате, полученном от предыдущего шага.Within the following dialog step, check for the presence of a token in the result from the previous step. Если он не равен NULL, значит пользователь успешно выполнил вход.If it is not null, the user successfully signed in.

// 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.
var tokenResponse = (TokenResponse)stepContext.Result;

Ожидание метода TokenResponseEventWait for a TokenResponseEvent

Когда вы запускаете командную строку OAuth, она ожидает события получения маркера, из которого затем извлекает маркер пользователя.When you start an OAuth prompt, it waits for a token response event, from which it will retrieve the user's token.

Bots\AuthBot.csBots\AuthBot.cs

AuthBot наследуется от ActivityHandler и явным образом обрабатывает действия ответа маркера.AuthBot derives from ActivityHandler and explicitly handles token response event activities. Здесь мы продолжаем активный диалог, что позволяет командной строке OAuth обработать событие и получить маркер.Here, we continue the active dialog, which allows the OAuth prompt to process the event and retrieve the token.

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

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

Выход пользователяLog the user out

Мы рекомендуем предоставить пользователям возможность явно выходить из системы, не полагаясь на автоматический разрыв подключения при превышении времени ожидания.It is best practice to let users explicitly sign out or logout, instead of relying on the connection to time out.

Dialogs\LogoutDialog.csDialogs\LogoutDialog.cs

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

Добавление аутентификации TeamsAdding Teams Authentication

В контексте OAuth Teams работает несколько иначе, чем другие каналы. Чтобы правильно реализовать аутентификацию, нужно внести несколько изменений.Teams behaves somewhat differently than other channels in regards to OAuth and requires a few changes to properly implement authentication. мы добавим код из образца Teams проверки подлинности (C# / JavaScript / Java).We will add code from the Teams Authentication Bot sample (C#/JavaScript/Java).

Одно из различий между другими каналами и Teams заключается в том, что Teams отправляет в бот действие invoke, а не действие event.One difference between other channels and Teams is that Teams sends an invoke activity to the bot, rather than an event activity.

Bots/TeamsBot.csBots/TeamsBot.cs

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

При использовании запроса OAuth это действие invoke должно быть переадресовано в диалог.If you use an OAuth prompt, this invoke activity must be forwarded to the dialog. Это будет сделано в TeamsActivityHandler.We will do so in the TeamsActivityHandler. Добавьте в файл основного диалога следующий код.Add the following code to your main dialog file.

Bots/DialogBot.csBots/DialogBot.cs

public class DialogBot<T> : TeamsActivityHandler where T : Dialog

Наконец, добавьте соответствующий файл TeamsActivityHandler (TeamsActivityHandler.cs для ботов C# teamsActivityHandler.js для ботов JavaScript) в папку бота самого верхнего уровня.Finally, make sure to add an appropriate TeamsActivityHandler file (TeamsActivityHandler.cs for C# bots and teamsActivityHandler.js for Javascript bots) at the topmost level in your bot's folder.

TeamsActivityHandler также отправляет действия message reaction.The TeamsActivityHandler also sends message reaction activities. Действие message reaction ссылается на исходное действие с помощью поля reply to ID.A message reaction activity references the original activity using the reply to ID field. Это действие также должно отображаться в веб-канале активности в Microsoft Teams.This activity should also be visible through the Activity Feed in Microsoft Teams.

Примечание

Вам нужно создать манифест и включить token.botframework.com в раздел validDomains. В противном случае при нажатии кнопки входа в OAuthCard окно проверки подлинности не будет открываться.You need to create a manifest and include token.botframework.com in the validDomains section; otherwise the OAuthCard Sign in button will not open the authentication window. Создайте манифест с помощью App Studio.Use the App Studio to generate your manifest.

Дополнительные материалыFurther reading