Direct Line API 1.1 中的身份验证

项目
2024-10-28

重要

本文介绍了如何在 Direct Line API 1.1 中进行身份验证。如果要在客户端应用程序和机器人之间创建新连接，请改用 Direct Line API 3.0。

客户端可以使用从 Bot Framework 门户中的 Direct Line 通道配置页获取的机密或使用在运行时获得的令牌来对 Direct Line API 1.1 的请求进行身份验证。

应在每个请求的 Authorization 标头中使用“Bearer”方案或“BotConnector”方案来指定机密或令牌。

Bearer 方案：

Authorization: Bearer SECRET_OR_TOKEN

BotConnector 方案：

Authorization: BotConnector SECRET_OR_TOKEN

机密和令牌

Direct Line 机密是可用于访问属于关联的机器人的任何会话的主密钥。机密还可用于获取令牌。机密不会过期。

Direct Line 令牌是可用于访问单个会话的密钥。令牌会过期，但可以进行刷新。

如果你要创建服务到服务应用程序，在 Direct Line API 请求的 Authorization 标头中指定机密可能是最简单的方法。如果你要编写客户端在 Web 浏览器或移动应用中运行的应用程序，你可能想要交换你的机密以获取令牌（仅适用于单个会话，且在不刷新的情况下会过期）并在 Direct Line API 请求的 Authorization 标头中指定令牌。选择最适合你的安全模型。

注意

你的 Direct Line 客户端凭据与你的机器人的凭据是不同的。这让你能够独立修改你的密钥，并使你能够在不泄漏你的机器人的密码的情况下共享客户端令牌。

获取 Direct Line 机密

可以在 Azure 门户中通过 Direct Line 通道配置页为机器人获取 Direct Line 机密：

Direct Line 站点的配置设置的屏幕截图。

生成 Direct Line 令牌

若要生成可用于访问单个对话的 Direct Line 令牌，请首先从 Azure 门户中的 Direct Line 通道配置页获取 Direct Line 机密。然后，发出交换 Direct Line 机密的请求，以获取 Direct Line 令牌：

POST https://directline.botframework.azure.cn/api/tokens/conversation
Authorization: Bearer SECRET

在此请求的 Authorization 标头中，将 SECRET 替换为 Direct Line 机密的值。

以下代码段提供了 Generate Token 请求和响应的示例。

请求

POST https://directline.botframework.azure.cn/api/tokens/conversation
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

响应

如果请求成功，响应将包含对单个会话有效的令牌。该令牌将在 30 分钟后过期。为了使令牌仍然可用，必须在其过期前刷新令牌。

HTTP/1.1 200 OK
[other headers]

"RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn"

生成令牌和启动会话

生成令牌操作 (POST /api/tokens/conversation) 类似于启动会话操作 (POST /api/conversations)，因为这两个操作都返回可用于访问单个会话的 token。但是，与开始对话操作不同，生成令牌操作不会启动对话或联系机器人。

如果计划将令牌分发给客户端并希望它们启动会话，请使用生成令牌操作。如果打算立即启动会话，请改用启动会话操作。

刷新 Direct Line 令牌

Direct Line 令牌自生成之日起 30 分钟内有效，只要未过期，就可以无限次刷新。不能刷新已到期的令牌。若要刷新 Direct Line 令牌，请发出此请求：

POST https://directline.botframework.azure.cn/api/tokens/{conversationId}/renew
Authorization: Bearer TOKEN_TO_BE_REFRESHED

在此请求的 URI 中，将 {conversationId} 替换为令牌有效的会话的 ID，并在此请求的 Authorization 标头中，将 TOKEN_TO_BE_REFRESHED 替换为你想要刷新的 Direct Line 令牌。

以下代码段提供了 Refresh Token 请求和响应的示例。

请求

POST https://directline.botframework.azure.cn/api/tokens/abc123/renew
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

响应

如果请求成功，响应将包含对和以前令牌相同的会话有效的新令牌。新令牌将在 30 分钟后过期。为使新令牌仍然可用，必须在其过期前刷新令牌。

HTTP/1.1 200 OK
[other headers]

"RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0"

通过