【 Bot Framework SDK 】通过Azure bot

语言 Chinese, Simplified

SEO Title

Bot Framework SDK - Add authentication to your bot via Azure Bot Service

Sample	BotBuilder version	Description
AadV1Bot	v3	Demonstrates OAuthCard support in the v3 C# SDK, using the Azure AD v1 endpoint
AadV2Bot	v3	Demonstrates OAuthCard support in the v3 C# SDK, using the Azure AD v2 endpoint
GitHubBot	v3	Demonstrates OAuthCard support in the v3 C# SDK, using GitHub
BasicOAuth	v3	Demonstrates OAuth 2.0 support in the v3 C# SDK

概述

本教程创建了一个使用Azure AD v1或v2令牌连接到Microsoft Graph的示例机器人。作为此过程的一部分，您将使用GitHub仓库中的代码，本教程描述了如何设置该代码，包括bot应用程序。

要完成这些步骤，您需要安装Visual Studio 2017、npm、node和git。您还应该熟悉Azure、OAuth 2.0和机器人开发。

完成后，您将拥有一个机器人，它可以对Azure AD应用程序的一些简单任务做出响应，例如检查和发送电子邮件，或显示您是谁以及您的经理是谁。为此，您的机器人将使用Azure AD应用程序中的令牌来对抗Microsoft。图形库。

最后一节分解了一些机器人代码

Notes on the token retrieval flow

创建您的机器人和身份验证应用程序

您需要创建一个注册机器人，在其中将消息传递端点设置为部署的机器人代码，并且您需要创建Azure AD（v1或v2）应用程序，以允许您的机器人访问Office 365。

注：

这些身份验证功能适用于其他类型的机器人。然而，本教程使用了一个仅限注册的机器人。

在Azure AD中注册应用程序

你需要一个Azure AD应用程序，你的机器人程序可以将其用作身份提供程序来连接到Microsoft Graph API。

对于此机器人，您可以使用Azure AD v1或v2终结点。有关v1和v2终结点之间差异的信息，请参阅v1-v2比较和Azure AD v2.0终结点概述。

创建Azure AD身份提供程序应用程序

使用以下步骤创建新的Azure AD应用程序。您可以将v1或v2端点与您创建的应用程序一起使用。

小贴士

您需要在租户中创建和注册Azure AD应用程序，您可以在其中同意委派应用程序请求的权限。

在Azure门户中打开[AAzure Active Directory][Azure aad刀片]面板。如果您不在正确的租户中，请单击“切换目录”切换到正确的租户。（有关创建租户的说明，请参阅访问门户并创建租户。）

打开应用程序注册面板。
在应用程序注册面板中，单击新建注册。
填写必填字段并创建应用程序注册。
命名您的应用程序。
1. 为您的应用程序选择支持的帐户类型。
2. 对于重定向URI
  1. 选择Web。
  2. 将URL设置为https://token.botframework.com/.auth/web/redirect.
3. 单击注册。
  1. 创建后，Azure将显示应用程序的概述页面。
  2. 记录应用程序（客户端）ID值。稍后，当您向机器人注册Azure AD应用程序时，您将使用此值作为客户端id。
  3. 同时记录目录（租户）ID值。您还将使用此功能向您的机器人注册此应用程序。

注：

当支持的帐户类型设置为单租户时，如果您使用个人订阅而不是Microsoft帐户，模拟器将发送错误：机器人的Microsoft App ID或Microsoft App密码不正确。>在这种情况下，支持的帐户类型必须设置为任何组织目录（任何Azure AD目录-多租户）中的帐户和个人Microsoft帐户（例如Xbox）。

在导航窗格中，单击证书和机密为您的应用程序创建机密。
1. 在“客户端机密”下，单击“新建客户端机密”。
2. 添加一个描述，以从您可能需要为此应用程序创建的其他人那里识别此秘密，例如机器人登录。
3. 将“过期”设置为“永不”。
4. 单击“添加”。
5. 在离开此页面之前，记录下这个秘密。稍后，当您向机器人注册Azure AD应用程序时，您将使用此值作为客户端机密。
在导航窗格中，单击API权限打开API权限面板。最佳做法是显式设置应用程序的API权限。
1. 单击添加权限以显示请求API权限窗格。
2. 对于此示例，请选择Microsoft API和Microsoft Graph。
3. 选择“委派权限”，并确保已选择所需的权限。此示例需要这些权限。

注：

任何标记为“需要管理员同意”的权限都需要用户和租户管理员登录，因此您的机器人往往会远离这些权限。

openid
profile
Mail.Read
Mail.Send
User.Read
User.ReadBasic.All

单击添加权限。（用户第一次通过机器人访问此应用程序时，需要给予同意。）

您现在已配置Azure AD应用程序。

在Azure上创建你的机器人

使用Azure门户创建Bot Channels注册。

在您的机器人中注册您的Azure AD应用程序

下一步是向您的机器人注册您刚刚创建的Azure AD应用程序。

Azure AD v1

导航到Azure门户上的机器人资源页面。
单击设置。
在页面底部附近的OAuth连接设置下，单击添加设置。
请按照以下步骤填写表格：
- 在“名称”中，输入连接的名称。您将在机器人代码中使用此名称。
- 对于服务提供商，选择Azure Active Directory。选择此选项后，将显示Azure AD特定的字段。
- 对于客户端id，输入您为Azure AD v1应用程序记录的应用程序（客户端）id。
- 对于客户端密钥，输入您创建的密钥，以授予机器人访问Azure AD应用程序的权限。
- 在“授权类型”中，输入authorization_code。
- 对于登录URL，请输入https://login.microsoftonline.com.
- 对于租户ID，输入您之前为Azure AD应用程序记录的目录（租户）ID。
  - 这将是与可以进行身份验证的用户关联的租户。
- 对于资源URL，请输入https://graph.microsoft.com/.
- 将范围留空。
单击“保存”。

注：

这些值使您的应用程序能够通过Microsoft Graph API访问Office 365数据。

Azure AD v2

导航到Azure门户上机器人的bot Channels注册页面。
单击设置。
在页面底部附近的OAuth连接设置下，单击添加设置。
请按照以下步骤填写表格：
- 在“名称”中，输入连接的名称。你将在你的机器人代码中使用它。
- 对于服务提供商，选择Azure Active Directory v2。选择此选项后，将显示Azure AD特定的字段。
- 对于客户端id，输入您为Azure AD v1应用程序记录的应用程序（客户端）id。
- 对于客户端密钥，输入您创建的密钥，以授予机器人访问Azure AD应用程序的权限。
- 对于租户ID，输入您之前为Azure AD应用程序记录的目录（租户）ID。
- 这将是与可以进行身份验证的用户关联的租户。
- 对于“范围”，输入您从应用程序注册中选择的权限名称：Mail。阅读邮件。发送openid配置文件用户。读取用户。阅读基础。全部。

注：

对于Azure AD v2，Scopes采用区分大小写、空格分隔的值列表。

单击“保存”。

注：

这些值使您的应用程序能够通过Microsoft Graph API访问Office 365数据。

测试您的连接

打开您刚才创建的连接。
单击“服务提供商连接设置”窗格顶部的“测试连接”。
第一次，这应该会打开一个新的浏览器选项卡，列出您的应用程序正在请求的权限，并提示您接受。
单击“接受”。
然后，这应该会将您重定向到“测试连接成功”页面。

准备机器人示例代码

在以下位置克隆github存储库https://github.com/Microsoft/BotBuilder.
打开并构建解决方案BotBuilder\CSharp\Microsoft。Bot.Builder.sln。
关闭该解决方案并打开BotBuilder\CSharp\Samples\Microsoft。Bot.Builder。样品s.sln。
设置启动项目。
1. 对于使用v1 Azure AD应用程序的机器人，请使用Microsoft。植物样本。AadV1Bot项目。
2. 对于使用v2 Azure AD应用程序的机器人，请使用Microsoft。植物样本。AadV2Bot项目。
打开Web.config文件，并按如下方式修改应用程序设置：
1. 将ConnectionName设置为配置机器人OAuth 2.0连接设置时使用的值。
2. 将MicrosoftAppId值设置为机器人的应用程序ID。
3. 将MicosoftAppPassword值设置为机器人的密码。

重要事项

根据密码中的字符，您可能需要XML转义密码。例如，任何与号（&）都需要编码为&amp；。

XML

要获取Microsoft应用程序ID和Microsoft应用程序密码值，请参阅获取注册密码。

注：

现在，您可以将此机器人代码发布到Azure订阅中（右键单击项目并选择“发布”），但本教程不需要这样做。您需要设置一个发布配置，该配置使用您在Azure门户中配置机器人时使用的应用程序和托管计划。

使用模拟器测试您的机器人

您需要安装Bot Emulator以在本地测试您的机器人。您可以使用v3或v4模拟器。

启动你的机器人（有或没有调试）。
注意页面的localhost端口号。您将需要此信息与您的机器人进行交互。
启动模拟器。
连接到你的机器人。
1. 如果您尚未配置连接，请提供地址以及您的机器人的Microsoft应用程序ID和密码。将/api/messages添加到机器人的URL中。您的URL看起来像http://localhost:portNumber/api/messages.
键入help查看bot的可用命令列表，并测试身份验证功能。
登录后，在注销之前，您不需要再次提供凭据。
要注销并取消身份验证，请键入signout。

注：

Bot身份验证需要使用Bot连接器服务。该服务访问您的机器人的机器人频道注册信息，这就是为什么您需要在门户上设置机器人的消息传递端点。身份验证还需要使用HTTPS，这就是为什么你需要为本地运行的机器人创建一个HTTPS转发地址。

令牌检索流程说明

当用户要求机器人做一些需要机器人让用户登录的事情时，机器人可以使用Microsoft.Bot.Builder.Dialogs.GetTokenDialog用于启动检索给定连接的令牌。接下来的几个片段来自GetTokenDialog 类。

检查缓存的令牌

在这段代码中，首先机器人会进行快速检查，以确定Azure机器人服务是否已经拥有用户的令牌（由当前活动发送者标识）和给定的ConnectionName（配置中使用的连接名称）。Azure Bot Service要么已经缓存了令牌，要么没有。对GetUserTokenAsync的调用执行此“快速检查”。如果Azure Bot Service有一个令牌并返回，则可以立即使用该令牌。如果Azure Bot Service没有令牌，则此方法将返回null。在这种情况下，机器人可以发送一个定制的OAuthCard供用户登录。

// First ask Bot Service if it already has a token for this user
var token = await context.GetUserTokenAsync(ConnectionName).ConfigureAwait(false);
if (token != null)
{
   // use the token to do exciting things!
}
else
{
   // If Bot Service does not have a token, send an OAuth card to sign in
   await SendOAuthCardAsync(context, (Activity)context.Activity);
}

向用户发送OAuthCard

您可以使用所需的任何文本和按钮文本自定义OAuthCard。重要部分包括：

将ContentType设置为OAuthCard。内容类型。
将ConnectionName属性设置为要使用的连接的名称。
包含一个带有ActionTypes类型的CardAction按钮。登录；请注意，您不需要为登录链接指定任何值。

在这个调用结束时，机器人需要“等待令牌”返回。这种等待发生在主活动流上，因为用户可能需要做很多事情才能登录。

private async Task SendOAuthCardAsync(IDialogContext context, Activity activity)
{
   await context.PostAsync($"To do this, you'll first need to sign in.");
   var reply = await context.Activity.CreateOAuthReplyAsync(_connectionName, _signInMessage, _buttonLabel).ConfigureAwait(false);
   await context.PostAsync(reply);
   context.Wait(WaitForToken);
}

等待TokenResponseEvent

在这段代码中，Bot的对话类正在等待TokenResponseEvent（下面将详细介绍如何将其路由到对话堆栈）。WaitForToken方法首先确定此事件是否已发送。如果它被发送，它可以被机器人使用。如果没有，WaitForToken方法会接收发送给机器人的任何文本，并将其传递给GetUserTokenAsync。这样做的原因是，一些客户端（如WebChat）不需要Magic Code验证码，可以直接在TokenResponseEvent中发送Token。其他客户仍然需要魔法代码（如Facebook或Slack）。Azure Bot Service将向这些客户端显示一个六位数的魔法代码，并要求用户在聊天窗口中键入该代码。虽然不理想，但这是“回退”行为，因此如果WaitForToken收到代码，机器人可以将此代码发送到Azure bot Service并取回令牌。如果此调用也失败，则可以决定报告错误或执行其他操作。不过，在大多数情况下，机器人现在将拥有一个用户令牌。

如果您查看MessageController.cs文件，您会看到这种类型的事件活动也被路由到对话框堆栈。

private async Task WaitForToken(IDialogContext context, IAwaitable<object> result)
{
   var activity = await result as Activity;
   var tokenResponse = activity.ReadTokenResponseContent();
   if (tokenResponse != null)
   {
       // Use the token to do exciting things!
   }
   else
   {
       if (!string.IsNullOrEmpty(activity.Text))
       {
           tokenResponse = await context.GetUserTokenAsync(ConnectionName,
                                                              activity.Text);
           if (tokenResponse != null)
           {
               // Use the token to do exciting things!
               return;
           }
       }
       await context.PostAsync($"Hmm. Something went wrong. Let's try again.");
       await SendOAuthCardAsync(context, activity);
   }
}

消息控制器

在后续调用机器人时，请注意此示例机器人从未缓存令牌。这是因为机器人始终可以向Azure机器人服务请求令牌。这避免了机器人需要管理令牌生命周期、刷新令牌等，因为Azure bot Service会为您完成所有这些工作。

else if(message.Type == ActivityTypes.Event)
{
if(message.IsTokenResponseEvent())
{
await Conversation.SendAsync(message, () => new Dialogs.RootDialog());
}
}

额外资源

Bot Framework SDK

本文地址

https://architect.pub

登录发表评论
8 次浏览

发布日期

星期四, 八月 8, 2024 - 09:17

最后修改

星期四, 八月 8, 2024 - 09:39

热门内容

今日:

总体:

最近浏览：