[Bot Framework]Direct Line API 3.0中的身份验证

客户端可以通过使用您从Bot Framework门户的Direct Line通道配置页面获得的机密或使用您在运行时获得的令牌来验证对Direct Line API 3.0的请求。应使用以下格式在每个请求的Authorization标头中指定密钥或令牌：

超文本传输协议

Authorization: Bearer SECRET_OR_TOKEN
 

Secrets and tokens

Direct Line secret是一个主密钥，可用于访问属于相关机器人的任何对话。secret也可用于获取令牌。秘密不会过期。

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

决定何时或是否使用密钥或令牌必须基于安全考虑。如果故意和小心地暴露密钥是可以接受的。事实上，这是默认行为，因为这允许Direct Line判断客户端是否合法。不过，一般来说，如果你试图持久化用户数据，安全性是一个问题。有关更多信息，请参阅“安全注意事项”一节。

如果您正在创建一个服务到服务应用程序，那么在Direct Line API请求的Authorization头中指定秘密可能是最简单的方法。如果您正在编写客户端在web浏览器或移动应用程序中运行的应用程序，则可能需要将您的机密交换为令牌（仅适用于单个会话，除非刷新，否则将过期），并在Direct Line API请求的授权头中指定令牌。选择最适合您的安全模型。

注：

您的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.com/v3/directline/tokens/generate 

Authorization: Bearer SECRET

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

以下代码段提供了生成令牌请求和响应的示例。

Request

超文本传输协议

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

包含令牌参数的请求有效负载是可选的，但建议使用。在生成可以发送回Direct Line服务的令牌时，提供以下有效载荷以使连接更加安全。通过包含这些值，Direct Line可以对用户ID和名称执行额外的安全验证，从而防止恶意客户端篡改这些值。包含这些值还可以提高Direct Line发送对话更新活动的能力，使其能够在用户加入对话后立即生成对话更新。如果没有提供此信息，用户必须先发送内容，然后Direct Line才能发送对话更新。

JSON

{
 "user": {
   "id": "string",
   "name": "string"
 },
 "trustedOrigins": [
   "string"
 ]
}

Response

如果请求成功，响应将包含一个对一次对话有效的令牌和一个expires_in值，该值指示令牌到期前的秒数。为了使令牌保持可用，您必须在令牌过期之前刷新它。

超文本传输协议

HTTP/1.1 200 OK
[other headers]

JSON

{
 "conversationId": "abc123",
 "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
 "expires_in": 1800
}

生成令牌与启动对话

Generate Token操作（POST/v3/directline/tokens/Generate）与Start Conversation操作（POT/v3/directline/translations）相似，因为这两个操作都返回一个可用于访问单个会话的令牌。但是，与Start Conversation操作不同，Generate Token操作不会启动对话，不会联系机器人，也不会创建流式WebSocket URL。

如果您计划将令牌分发给客户端并希望他们发起对话，请使用Generate token操作。如果您打算立即开始对话，请改用“开始对话”操作。

刷新直线令牌

Direct Line令牌可以无限次刷新，只要它没有过期。过期的令牌无法刷新。要刷新Direct Line令牌，请发出以下请求：

超文本传输协议

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer TOKEN_TO_BE_REFRESHED

在此请求的Authorization标头中，将TOKEN_TO_BE_REFRESHED替换为要刷新的Direct Line令牌。

以下代码段提供了刷新令牌请求和响应的示例。

请求
 

POST https://directline.botframework.com/v3/directline/tokens/refresh
Authorization: Bearer CurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

答复

如果请求成功，响应将包含一个与前一个令牌对同一会话有效的新令牌和一个expires_in值，该值指示新令牌到期前的秒数。为了使新令牌保持可用，您必须在令牌过期之前刷新它。

超文本传输协议

HTTP/1.1 200 OK
[other headers]

JSON

{
 "conversationId": "abc123",
 "token": "RCurR_XV9ZA.cwA.BKA.y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xniaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0",
 "expires_in": 1800
}

Azure AI Bot服务身份验证

本节中提供的信息基于通过Azure AI bot Service向您的机器人添加身份验证文章。

Azure AI Bot Service身份验证使您能够对用户进行身份验证，并从各种身份提供者（如Microsoft Entra ID、GitHub、Uber等）获取访问令牌。您还可以为自定义OAuth2身份提供者配置身份验证。所有这些使您能够编写一段跨所有支持的身份提供程序和通道工作的身份验证代码。要使用这些功能：

1. 在您的机器人上静态配置设置，其中包含您向身份提供者注册应用程序的详细信息。
2. 使用由您在上一步中提供的应用程序信息支持的OAuthCard登录用户。
3. 通过Azure AI Bot服务API检索访问令牌。

安全考虑

当您在Web聊天中使用Azure AI Bot Service身份验证时，必须记住一些重要的安全考虑因素。

• 模仿。冒充是指攻击者让机器人相信攻击者是别人。在网络聊天中，攻击者可以通过更改其网络聊天实例的用户ID来冒充其他人。为了防止冒充，我们建议机器人开发人员使用户ID不可检测。

如果启用增强的身份验证选项，Azure AI Bot Service可以进一步检测并拒绝任何用户ID更改。这意味着从Direct Line发送给您的机器人的消息上的用户ID（Activity.From.ID）将始终与您初始化网络聊天时使用的用户ID相同。此功能要求用户ID以dl_开头。

注：

当一个用户。Id是在将密钥交换为令牌时提供的，即该用户。Id嵌入在令牌中。Direct Line确保发送给机器人的消息具有该ID作为活动的发件人。Id。如果客户端向具有不同发件人的Direct Line发送消息。Id，在将消息转发给机器人之前，它将被更改为令牌中的Id。因此，在用用户Id初始化通道密钥后，您不能使用其他用户Id

• 用户身份。每个用户都有多个用户身份：
  • 频道中的用户身份。
  • 机器人感兴趣的身份提供者中的用户身份。

当一个机器人程序要求频道中的用户a登录到身份提供者P时，登录过程必须确保用户a是登录到P的用户。如果允许另一个用户B登录，那么用户a将可以通过机器人程序访问用户B的资源。在网络聊天中，我们有两种机制来确保正确的用户登录，如下所述。

• 在过去，登录结束时，用户会看到一个随机生成的6位代码（魔术代码）。用户必须在发起登录的对话中键入此代码才能完成登录过程。这种机制往往会导致糟糕的用户体验。此外，它仍然容易受到网络钓鱼攻击。恶意用户可以诱骗其他用户登录并通过网络钓鱼获得密码。
• 由于之前方法的问题，Azure AI Bot Service消除了对魔法代码的需求。Azure AI Bot Service保证登录过程只能在与网络聊天本身相同的浏览器会话中完成。要启用此保护，作为机器人开发人员，您必须使用包含可承载机器人网络聊天客户端的受信任域列表的Direct Line令牌启动网络聊天。以前，您只能通过将未记录的可选参数传递给Direct Line令牌API来获取此令牌。现在，使用增强的身份验证选项，您可以在Direct Line配置页面中静态指定受信任的域（源）列表。

有关更多信息，请参阅通过Azure AI bot Service向您的机器人添加身份验证。

代码示例

以下.NET控制器在启用增强身份验证选项的情况下工作，并返回Direct Line Token和用户ID。

public class HomeController : Controller
{
   public async Task<ActionResult> Index()
   {
       var secret = GetSecret();
       HttpClient client = new HttpClient();
       HttpRequestMessage request = new HttpRequestMessage(
           HttpMethod.Post,
           $"https://directline.botframework.com/v3/directline/tokens/generate");
       request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", secret);
       var userId = $"dl_{Guid.NewGuid()}";
       request.Content = new StringContent(
           JsonConvert.SerializeObject(
               new { User = new { Id = userId } }),
               Encoding.UTF8,
               "application/json");
       var response = await client.SendAsync(request);
       string token = String.Empty;
       if (response.IsSuccessStatusCode)
       {
           var body = await response.Content.ReadAsStringAsync();
           token = JsonConvert.DeserializeObject<DirectLineToken>(body).token;
       }
       var config = new ChatConfig()
       {
           Token = token,
           UserId = userId
       };
       return View(config);
   }
}
public class DirectLineToken
{
   public string conversationId { get; set; }
   public string token { get; set; }
   public int expires_in { get; set; }
}
public class ChatConfig
{
   public string Token { get; set; }
   public string UserId { get; set; }
}

The following JavaScript controller works with enhanced authentication options enabled and returns a Direct Line Token and user ID.

var router = express.Router(); // get an instance of the express Router
// Get a directline configuration (accessed at GET /api/config)
const userId = "dl_" + createUniqueId();
router.get('/config', function(req, res) {
   const options = {
       method: 'POST',
       uri: 'https://directline.botframework.com/v3/directline/tokens/generate',
       headers: {
           'Authorization': 'Bearer ' + secret
       },
       json: {
           User: { Id: userId }
       }
   };
   request.post(options, (error, response, body) => {
       if (!error && response.statusCode < 300) {
           res.json({
                   token: body.token,
                   userId: userId
               });
       }
       else {
           res.status(500).send('Call to retrieve token from Direct Line failed');
       }
   });
});

• Key concepts
• Connect a bot to Direct Line
• Add authentication to your bot via Azure AI Bot Service