[Bot Framework]在Direct Line API 3.0中进行身份验证

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

Authorization: Bearer SECRET_OR_TOKEN

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

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

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

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

注：

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

You can obtain a Direct Line secret via the Direct Line channel configuration page for your bot in the Azure portal:

To generate a Direct Line token that can be used to access a single conversation, first obtain the Direct Line secret from the Direct Line channel configuration page in the Azure portal. Then issue this request to exchange your Direct Line secret for a Direct Line token:

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer SECRET

In the Authorization header of this request, replace SECRET with the value of your Direct Line secret.

The following snippets provide an example of the Generate Token request and response.

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

The request payload, which contains the token parameters, is optional but recommended. When generating a token that can be sent back to the Direct Line service, provide the following payload to make the connection more secure. By including these values, Direct Line can perform additional security validation of the user ID and name, inhibiting tampering of these values by malicious clients. Including these values also improves Direct Line's ability to send the conversation update activity, allowing it to generate the conversation update immediately upon the user joining the conversation. When this information isn't provided, the user must send content before Direct Line can send the conversation update.

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

If the request is successful, the response contains a token that is valid for one conversation and an expires_in value that indicates the number of seconds until the token expires. For the token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]

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

The Generate Token operation (POST /v3/directline/tokens/generate) is similar to the Start Conversation operation (POST /v3/directline/conversations) in that both operations return a token that can be used to access a single conversation. However, unlike the Start Conversation operation, the Generate Token operation doesn't start the conversation, doesn't contact the bot, and doesn't create a streaming WebSocket URL.

If you plan to distribute the token to clients and want them to initiate the conversation, use the Generate Token operation. If you intend to start the conversation immediately, use the Start Conversation operation instead.

A Direct Line token can be refreshed an unlimited number of times, as long as it hasn't expired. An expired token can't be refreshed. To refresh a Direct Line token, issue this request:

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

In the Authorization header of this request, replace TOKEN_TO_BE_REFRESHED with the Direct Line token that you want to refresh.

The following snippets provide an example of the Refresh Token request and response.

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

If the request is successful, the response contains a new token that is valid for the same conversation as the previous token and an expires_in value that indicates the number of seconds until the new token expires. For the new token to remain useful, you must refresh the token before it expires.

HTTP/1.1 200 OK
[other headers]

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

The information presented in this section is based on the Add authentication to your bot via Azure AI Bot Service article.

Azure AI Bot Service authentication enables you to authenticate users to and get access tokens from various identity providers such as Microsoft Entra ID, GitHub, Uber and so on. You can also configure authentication for a custom OAuth2 identity provider. All this enables you to write one piece of authentication code that works across all supported identity providers and channels. To use these capabilities:

1. Statically configure settings on your bot that contains the details of your application registration with an identity provider.
2. Use an OAuthCard, backed by the application information you supplied in the previous step, to sign-in a user.
3. Retrieve access tokens through Azure AI Bot Service API.

When you use Azure AI Bot Service authentication with Web Chat, there are some important security considerations you must keep in mind.

1. Impersonation. Impersonation is when an attacker convinces the bot that the attacker is someone else. In Web Chat, an attacker can impersonate someone else by changing the user ID of their Web Chat instance. To prevent impersonation, we recommend that bot developers make the user ID unguessable.

   If you enable enhanced authentication options, Azure AI Bot Service can further detect and reject any user ID change. This means the user ID (Activity.From.Id) on messages from Direct Line to your bot will always be the same as the one you initialized the Web Chat with. This feature requires the user ID to start with dl_.

   Note

   When a User.Id is provided while exchanging a secret for a token, that User.Id is embedded in the token. Direct Line makes sure the messages sent to the bot have that ID as the activity's From.Id. If a client sends a message to Direct Line having a different From.Id, it will be changed to the ID in the token before forwarding the message to the bot. So you can't use another user ID after a channel secret is initialized with a user ID

2. User identities. Each user has multiple user identities:

   1. The user's identity in a channel.
   2. The user's identity in an identity provider that the bot is interested in.

When a bot asks user A in a channel to sign-in to an identity provider P, the sign-in process must assure that user A is the one that signs into P. If another user B is allowed to sign-in, then user A would have access to user B's resource through the bot. In Web Chat, we have two mechanisms for ensuring the right user signed in as described next.

1. At the end of sign-in, in the past, the user was presented with a randomly generated 6-digit code (magic code). The user must type this code in the conversation that initiated the sign-in to complete the sign-in process. This mechanism tends to result in a bad user experience. Additionally, it's still susceptible to phishing attacks. A malicious user can trick another user to sign-in and obtain the magic code through phishing.

2. Because of the issues with the previous approach, Azure AI Bot Service removed the need for the magic code. Azure AI Bot Service guarantees that the sign-in process can only be completed in the same browser session as the Web Chat itself. To enable this protection, as a bot developer, you must start Web Chat with a Direct Line token that contains a list of trusted domains that can host the bot's Web Chat client. Before, you could only obtain this token by passing an undocumented optional parameter to the Direct Line token API. Now, with enhanced authentication options, you can statically specify the trusted domain (origin) list in the Direct Line configuration page.

For more information, see Add authentication to your bot via Azure AI Bot Service.

The following .NET controller works with enhanced authentication options enabled and returns a Direct Line Token and user 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