向机器人添加身份验证

适用于 C#、JavaScript 和 Python 机器人。

适用于 C#、JavaScript 和 Python 机器人。

适用于使用所有编程语言的机器人：C#、JavaScript、Java 和 Python。

1. 在 Azure 门户中，打开机器人的“Azure 机器人”资源页。

2. 选择“设置”。

3. 在页面底部附近的“OAuth 连接设置”下，选择“添加设置”。

4. 按如下所示填写表单：

   1. Name。 输入连接的名称。 在机器人代码中会用到。

   2. 服务提供商。 选择 Microsoft Entra ID 以显示特定于 Microsoft Entra ID 的字段。

   3. “客户端 ID”。输入为 Microsoft Entra ID 标识提供者记录的应用程序（客户端）ID。

   4. 客户端密码。 输入为 Microsoft Entra ID 标识提供者记录的机密。

      提示

      如果要使用证书，可以选择“使用证书的 AAD v2”提供程序。 需要向机器人服务令牌存储 (appid: 5b404cf4-a79d-4cfe-b866-24bf8e1a4921) 授予获取证书的权限。

   5. 令牌交换 URL。 将它留空，因为它仅用于 Microsoft Entra ID 中的 SSO。

   6. 租户 ID。 请输入此前为 Microsoft Entra ID 应用记录的“目录（租户）ID”，或者输入 common，具体取决于在创建 Azure DD 应用时所选的受支持帐户的类型。 若要确定要分配的值，请遵循以下条件：

      • 如果已选择“仅在此组织目录中的帐户 (仅 Microsoft - 单一租户)”，请在创建 Microsoft Entra ID 应用时，输入此前为 Microsoft Entra ID 应用记录的租户 ID。
      • 但是，如果选择了“任何组织目录中的帐户 (任何 Microsoft Entra ID 目录 - 多租户和个人 Microsoft 帐户，例如 Xbox、Outlook.com)”或“任何组织目录中的帐户 (Microsoft Entra ID 目录 - 多租户)”，请输入 common 而不是租户 ID。 否则，Microsoft Entra ID 应用会通过租户验证谁的 ID 已选中，并排除个人 Microsoft 帐户。

      此租户将与可进行身份验证的用户相关联。 有关详细信息，请参阅 Microsoft Entra ID 中的租户。

   7. 对于“范围”，输入从应用程序注册中选择的权限的名称。 对于测试，可只输入：openid profile。

      注意

      对于 Microsoft Entra ID，“范围”字段的值区分大小写，以空格分隔。

5. 选择“保存”。

1. 在 Azure 门户中，导航到机器人的资源页。

2. 选择“设置”。

3. 在页面底部附近的“OAuth 连接设置”下，选择“添加设置”。

4. 按如下所示填写表单：

   1. 对于“名称”，输入连接的名称。 稍后将在机器人代码中使用此名称。

   2. 对于“服务提供方”，选择 Microsoft Entra ID。 选择该选项后，将显示特定于 Microsoft Entra ID 的字段。

   3. 对于“客户端 ID”，请输入为 Azure AD v1 应用程序记录的应用程序（客户端）ID。

   4. 对于“客户端机密”，请输入所创建的机密，以便为机器人授予访问 Microsoft Entra ID 应用的权限。

   5. 对于“授权类型”，输入 authorization_code。

   6. 对于“登录 URL”，输入 https://login.partner.microsoftonline.cn。

   7. 对于“租户 ID”，请输入此前为 Microsoft Entra ID 应用记录的目录（租户）ID，或者输入 common，具体取决于在创建 ADD 应用时所选的受支持帐户的类型。 若要确定要分配的值，请遵循以下条件：

      • 如果已选择“仅在此组织目录中的帐户 (仅 Microsoft - 单一租户)”，请在创建 Microsoft Entra ID 应用时，输入此前为 Microsoft Entra ID 应用记录的租户 ID。
      • 但是，如果选择了“任何组织目录中的帐户 (任何 Microsoft Entra ID 目录 - 多租户和个人 Microsoft 帐户，例如 Xbox、Outlook.com)”或“任何组织目录中的帐户 (Microsoft Entra ID 目录 - 多租户)”，请输入 common 而不是租户 ID。 否则，Microsoft Entra ID 应用会通过租户验证谁的 ID 已选中，并排除个人 MS 帐户。

      此租户将与可进行身份验证的用户相关联。 有关详细信息，请参阅 Microsoft Entra ID 中的租户。

   8. 对于资源 URL，输入 https://graph.chinacloudapi.cn/。

   9. 将“作用域”留空。

5. 选择“保存”。

1. 从 GitHub 存储库克隆要使用的示例：机器人身份验证或 Microsoft Graph 的机器人身份验证。

2. 更新 appsettings.json：

   • 将 ConnectionName 设置为要添加到机器人的 OAuth 连接设置的名称。

   • 将 MicrosoftAppId 和 MicrosoftAppPassword 设置为机器人的应用 ID 和应用机密。

     根据机器人机密中的字符，可能需要 XML 转义密码。 例如，任何连字符 (&) 都需要编码为 &。

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

   若要配合公有云中的数据驻留在机器人中使用 OAuth，必须在 appsettings 中添加以下配置

   "OAuthUrl": "<Regional-OAuth-Uri>",
   "ToChannelFromBotOAuthScope": "https://api.botframework.azure.cn",
   "ToChannelFromBotLoginUrlTemplate": "https://api.botframework.azure.cn",
   "PublicAzureChannel": "https://api.botframework.azure.cn",
   "ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.azure.cn/v1/.well-known/openidconfiguration",
   "ToBotFromEmulatorOpenIdMetadataUrl": "https://login.partner.microsoftonline.cn/common/v2.0/.well-known/openid-configuration",
   "ToBotFromChannelTokenIssuer": "https://api.botframework.azure.cn",
   "ToChannelFromBotLoginUrl": "https://login.partner.microsoftonline.cn/botframework.com",
   

3. 更新 Startup.cs：

   若要在“非公有 Azure 云”（如政府云）中使用 OAuth，必须在 Startup.cs 文件中添加以下代码。

   string uri = "<uri-to-use>";
   MicrosoftAppCredentials.TrustServiceUrl(uri);
   OAuthClientConfig.OAuthEndpoint = uri;
   
   

   其中 <uri-to-use> 是以下 URI 之一：

   URI	说明
   https://api.botframework.azure.cn	对于没有数据驻留的美国政府云机器人。
   https://api.botframework.azure.cn	对于没有数据驻留的公有云机器人。 这是默认 URI，不需要更改 Startup.cs。

1. 从 GitHub 存储库克隆要使用的内容：机器人身份验证或 Microsoft Graph 的机器人身份验证。

2. 更新 .env：

   • 将 connectionName 设置为要添加到机器人的 OAuth 连接设置的名称。

   • 将 MicrosoftAppId 和 MicrosoftAppPassword 值设置为机器人的应用 ID 和应用机密。

     根据机器人机密中的字符，可能需要 XML 转义密码。 例如，任何连字符 (&) 都需要编码为 &。

   MicrosoftAppType=
   MicrosoftAppId=
   MicrosoftAppPassword=
   MicrosoftAppTenantId=
   connectionName=
   

1. 从 GitHub 存储库克隆要使用的示例：机器人身份验证或 Microsoft Graph 的机器人身份验证。

2. 更新 application.properties：

   • 将 ConnectionName 设置为要添加到机器人的 OAuth 连接设置的名称。
   • 将 MicrosoftAppId 和 MicrosoftAppPassword 设置为机器人的应用 ID 和应用机密。

   MicrosoftAppType=
   MicrosoftAppId=
   MicrosoftAppPassword=
   MicrosoftAppTenantId=
   connectionName=
   

1. 从 GitHub 存储库克隆要使用的示例：机器人身份验证或 Microsoft Graph 的机器人身份验证。

2. 更新 config.py：

   • 将 ConnectionName 设置为要添加到机器人的 OAuth 连接设置的名称。

   • 将 MicrosoftAppId 和 MicrosoftAppPassword 设置为机器人的应用 ID 和应用机密。

     根据机器人机密中的字符，可能需要 XML 转义密码。 例如，任何连字符 (&) 都需要编码为 &。

   #!/usr/bin/env python3
   # Copyright (c) Microsoft Corporation. All rights reserved.
   # Licensed under the MIT License.
   
   import os
   
   """ Bot Configuration """
   
   
   class DefaultConfig:
       """ Bot Configuration """
   
       PORT = 3978
       APP_ID = os.environ.get("MicrosoftAppId", "")
       APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
       APP_TYPE = os.environ.get("MicrosoftAppType", "MultiTenant")
       APP_TENANTID = os.environ.get("MicrosoftAppTenantId", "")
       CONNECTION_NAME = os.environ.get("ConnectionName", "")
   
   

Dialogs\MainDialog.cs

将 OAuth 提示添加到其构造函数中的 MainDialog。 在这里，连接名称的值已从 appsettings.json 文件中检索。

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 提示，该提示要求用户登录。

• 如果用户已登录，则会在不提示用户的情况下生成一个令牌响应事件，
• 否则会提示用户登录。 Azure AI 机器人服务会在用户尝试登录后发送令牌响应事件。

return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

在以下对话步骤中，检查上一步的结果中是否存在令牌。 如果该令牌不为 null，则表明用户已成功登录。

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

dialogs/mainDialog.js

将 OAuth 提示添加到其构造函数中的 MainDialog。 在这里，连接名称的值已从 .env 文件中检索。

this.addDialog(new WaterfallDialog(MAIN_WATERFALL_DIALOG, [
    this.promptStep.bind(this),
    this.loginStep.bind(this),
    this.displayTokenPhase1.bind(this),
    this.displayTokenPhase2.bind(this)
]));

在对话步骤中，请使用 beginDialog 来启动 OAuth 提示，该提示要求用户登录。

• 如果用户已登录，则会在不提示用户的情况下生成一个令牌响应事件，
• 否则会提示用户登录。 Azure AI 机器人服务会在用户尝试登录后发送令牌响应事件。

const tokenResponse = stepContext.result;

在以下对话步骤中，检查上一步的结果中是否存在令牌。 如果该令牌不为 null，则表明用户已成功登录。

await stepContext.context.sendActivity('Login was not successful please try again.');
return await stepContext.endDialog();

MainDialog.java

将 OAuth 提示添加到其构造函数中的 MainDialog。 在这里，连接名称的值已从 application.properties 文件中检索。

OAuthPromptSettings settings = new OAuthPromptSettings();
settings.setText("Please Sign In");
settings.setTitle("Sign In");
settings.setConnectionName(configuration.getProperty("ConnectionName"));
settings.setTimeout(300000); // User has 5 minutes to login (1000 * 60 * 5)

addDialog(new OAuthPrompt("OAuthPrompt", settings));

在对话步骤中，请使用 beginDialog 来启动 OAuth 提示，该提示要求用户登录。

• 如果用户已登录，则会在不提示用户的情况下生成一个令牌响应事件，
• 否则会提示用户登录。 Azure AI 机器人服务会在用户尝试登录后发送令牌响应事件。

return stepContext.beginDialog("OAuthPrompt");

在以下对话步骤中，检查上一步的结果中是否存在令牌。 如果该令牌不为 null，则表明用户已成功登录。

// Get the token from the previous step. Note that we could also have gotten the
// token directly from the prompt itself. There instanceof an example of this in the next method.
TokenResponse tokenResponse = (TokenResponse) stepContext.getResult();

dialogs/main_dialog.py

将 OAuth 提示添加到其构造函数中的 MainDialog。 在这里，连接名称的值已从 config.py 文件中检索。

self.add_dialog(
    WaterfallDialog(
        "WFDialog",
        [
            self.prompt_step,
            self.login_step,
            self.display_token_phase1,
            self.display_token_phase2,
        ],
    )
)

在对话步骤中，请使用 begin_dialog 来启动 OAuth 提示，该提示要求用户登录。

• 如果用户已登录，则会在不提示用户的情况下生成一个令牌响应事件，
• 否则会提示用户登录。 Azure AI 机器人服务会在用户尝试登录后发送令牌响应事件。

return await step_context.begin_dialog(OAuthPrompt.__name__)

在以下对话步骤中，检查上一步的结果中是否存在令牌。 如果该令牌不为 null，则表明用户已成功登录。

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?")
        ),
    )

await step_context.context.send_activity(
    "Login was not successful please try again."
)

Bots\AuthBot.cs

AuthBot 派生自 ActivityHandler，会显式处理令牌响应事件活动。 在这里，我们会继续活动对话，这样 OAuth 提示就能处理事件并检索令牌。

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

bots/authBot.js

AuthBot 派生自 ActivityHandler，会显式处理令牌响应事件活动。 在这里，我们会继续活动对话，这样 OAuth 提示就能处理事件并检索令牌。

await this.dialog.run(context, this.dialogState);

await next();

AuthBot.java

AuthBot 派生自 Dialog，会显式处理令牌响应事件活动。 在这里，我们会继续活动对话，这样 OAuth 提示就能处理事件并检索令牌。

@Override
protected CompletableFuture<Void> onTokenResponseEvent(TurnContext turnContext) {
    LoggerFactory.getLogger(AuthBot.class).info("Running dialog with Token Response Event Activity.");

    // Run the Dialog with the new Token Response Event Activity.
    return Dialog.run(dialog, turnContext, conversationState.createProperty("DialogState"));
}

bots/auth_bot.py

AuthBot 会显式处理令牌响应事件活动。 在这里，我们会继续活动对话，这样 OAuth 提示就能处理事件并检索令牌。

async def on_token_response_event(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

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

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

LogoutDialog.java

private CompletableFuture<DialogTurnResult> interrupt(DialogContext innerDc) {
    if (innerDc.getContext().getActivity().getType().equals(ActivityTypes.MESSAGE)) {
        String text = innerDc.getContext().getActivity().getText().toLowerCase();

        if (text.equals("logout")) {
            // The bot adapter encapsulates the authentication processes.
            BotFrameworkAdapter botAdapter = (BotFrameworkAdapter) innerDc.getContext().getAdapter();
            botAdapter.signOutUser(
                innerDc.getContext(),
                getConnectionName(),
                innerDc.getContext().getActivity().getFrom().getId())
                    .thenApply(result -> innerDc.getContext().sendActivity(MessageFactory.text("You have been signed out."))
                    .thenApply(sendResult -> null));
            return innerDc.cancelAllDialogs();
        }
    }

    return CompletableFuture.completedFuture(null);
}

dialogs/logout_dialog.py

return result
    return await super().on_continue_dialog(inner_dc)

async def _interrupt(self, inner_dc: DialogContext):
    if inner_dc.context.activity.type == ActivityTypes.message:
        text = inner_dc.context.activity.text.lower()
        if text == "logout":
            user_token_client: UserTokenClient = inner_dc.context.turn_state.get(