Проверка подлинности в API прямой линии 3,0Authentication in Direct Line API 3.0

Клиент может проверить подлинность запросов к API Direct Line версии 3.0 с помощью секрета, который можно получить на странице конфигурации канала Direct Line на портале Bot Framework, или с помощью маркера, который можно получить во время выполнения.A client can authenticate requests to Direct Line API 3.0 either by using a secret that you obtain from the Direct Line channel configuration page in the Bot Framework Portal or by using a token that you obtain at runtime. Секрет или маркер необходимо указать в заголовке Authorization каждого запроса, используя следующий формат:The secret or token should be specified in the Authorization header of each request, using this format:

Authorization: Bearer SECRET_OR_TOKEN

Секреты и маркерыSecrets and tokens

Секрет Direct Line — это главный ключ, который можно использовать для доступа ко всем диалогам, связанным с соответствующим ботом.A Direct Line secret is a master key that can be used to access any conversation that belongs to the associated bot. Секрет также можно использовать для получения маркера.A secret can also be used to obtain a token. Срок действия секрета не ограничен.Secrets do not expire.

Маркер Direct Line — это ключ, который можно использовать для доступа к одному диалогу.A Direct Line token is a key that can be used to access a single conversation. Срок действия маркера ограничен, но его можно продлить.A token expires but can be refreshed.

При принятии решения о том, следует ли использовать секретный ключ или токен и когда это нужно делать, нужно учитывать вопросы безопасности.Deciding when or if to use the secret key or a token must be based on security considerations. Секретный ключ должен предоставляться с какой-то целью (намеренно) и с осторожностью.Exposing the secret key could be acceptable if done intentionally and with care. Собственно, это поведение по умолчанию, благодаря чему Direct Line может определять, является ли клиент допустимым.As matter of a fact, this is the default behavior because this allows Direct Line to figure out if the client is legitimate. Но в целом, если вы пытаетесь сохранить данные пользователя, обеспечение безопасности является критически важным.Generally speaking though, security is a concern if you're trying to persist user data. См. сведения о вопросах безопасности.For more information, see section Security considerations.

При создании приложения между службами проще всего указать секрет в заголовке Authorization запросов API Direct Line.If you're creating a service-to-service application, specifying the secret in the Authorization header of Direct Line API requests may be simplest approach. Если вы создаете приложение, в котором клиент запускается в веб-браузере или в мобильном приложении, вы можете обменять секрет на маркер (который будет действительным только для одного диалога и перестанет действовать, если не будет продлен) и указать маркер в заголовке Authorization запросов API Direct Line.If you're writing an application where the client runs in a web browser or mobile app, you may want to exchange your secret for a token (which only works for a single conversation and will expire unless refreshed) and specify the token in the Authorization header of Direct Line API requests. Выберите наиболее подходящую вам модель безопасности.Choose the security model that works best for you.

Примечание

Учетные данные клиента Direct Line отличаются от учетных данных вашего бота.Your Direct Line client credentials are different from your bot's credentials. Это позволяет проверить ключи независимо друг от друга и предоставить маркеры клиента, не раскрывая пароль бота.This enables you to revise your keys independently and lets you share client tokens without disclosing your bot's password.

Получение секрета Direct LineGet a Direct Line secret

Вы можете получить секрет Direct Line на странице настройки канала Direct Line для вашего бота на портале Azure:You can obtain a Direct Line secret via the Direct Line channel configuration page for your bot in the Azure Portal:

Конфигурация Direct Line

Создание маркера Direct LineGenerate a Direct Line token

Чтобы создать маркер Direct Line, который можно использовать для доступа к одному диалогу, необходимо сначала получить секрет Direct Line на странице настройки канала Direct Line на портале Azure.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. Затем выполните следующий запрос, чтобы обменять секрет Direct Line на маркер Direct Line: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

В заголовке Authorization этого запроса замените SECRET значением секрета Direct Line.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.

ЗапросRequest

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. При создании маркера, который можно отправить обратно в службу Direct Line, предоставьте следующие полезные данные для более безопасного подключения.When generating a token that can be sent back to the Direct Line service, provide the following payload to make the connection more secure. Благодаря этим значениям Direct Line сможет выполнять дополнительную проверку идентификатора и имени пользователя, препятствуя изменению этих значений злоумышленниками.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. Также эти значения упрощают для Direct Line отправку действия обновления диалога, что позволяет создать обновление беседы немедленно при присоединении пользователя.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. Если эта информация не предоставляется, Direct Line сможет обновить беседу только после того, как пользователь отправит в нее какое-либо содержимое.When this information is not provided, the user must send content before Direct Line can send the conversation update.

{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}
ПараметрParameter ТипType ОписаниеDescription
user.id строкаstring Необязательный параметр.Optional. Идентификатор пользователя в конкретном канале, который кодируется в маркере.Channel-specific ID of the user to encode within the token. Для пользователя Direct Line это значение начинается с dl_.For a Direct Line user, this must begin with dl_. Вы можете создать уникальный идентификатор пользователя для каждой беседы, а для повышения безопасности следует исключить возможность угадать этот идентификатор.You can create a unique user ID for each conversation, and for better security, you should make this ID unguessable.
user.name строкаstring Необязательный параметр.Optional. Понятное отображаемое имя пользователя, которое кодируется в маркере.The display-friendly name of the user to encode within the token.
trustedOrigins массив строкstring array Необязательный параметр.Optional. Список доверенных доменов для внедрения в маркер.A list of trusted domains to embed within the token. Здесь перечисляются домены, которые могут размещать клиент веб-чата для бота.These are the domains that can host the bot's Web Chat client. Этот список должен совпадать с тем, который указан на странице настройки Direct Line для бота.This should match the list in the Direct Line configuration page for your bot.

ОтветResponse

Если запрос выполнен успешно, ответ содержит token для одного диалога, а значение expires_in указывает количество секунд до истечения срока действия маркера.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
}

Сравнение операций создания маркера и начала диалогаGenerate Token versus Start Conversation

Операция создания маркера (POST /v3/directline/tokens/generate) аналогична операции начала диалога (POST /v3/directline/conversations) в том, что обе операции возвращают token, который можно использовать для доступа к одному диалогу.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. Тем не менее, в отличие от операции начала диалога, операция создания маркера не начинает диалог, не связывается с ботом и не создает URL-адрес потоковой передачи WebSocket.However, unlike the Start Conversation operation, the Generate Token operation does not start the conversation, does not contact the bot, and does not 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.

Продление маркера Direct LineRefresh a Direct Line token

Маркер Direct Line можно продлевать неограниченное количество раз, до тех пор, пока срок его действия не истек.A Direct Line token can be refreshed an unlimited amount of times, as long as it has not expired. Продлить маркер с истекшим сроком действия невозможно.An expired token cannot be refreshed. Чтобы продлить маркер Direct Line, выполните следующий запрос:To refresh a Direct Line token, issue this request:

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

В заголовке Authorization этого запроса замените TOKEN_TO_BE_REFRESHED на маркер Direct Line, который вы хотите обновить.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.

ЗапросRequest

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

ОтветResponse

Если запрос выполнен успешно, ответ содержит новый token, который действителен для того же диалога, что и предыдущий маркер, а значение expires_in указывает количество секунд до истечения срока нового действия маркера.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
}

Проверка подлинности службы Azure BotAzure Bot Service authentication

Сведения, представленные в этом разделе, основаны на инструкциях по добавлению проверки подлинности к боту с помощью службы Azure Bot.The information presented in this section is based on the Add authentication to your bot via Azure Bot Service article.

Функция проверки подлинности службы Azure Bot позволяет проверять подлинность пользователей и получать маркеры доступа от различных поставщиков удостоверений, например Azure Active Directory, GitHub, Uber и т. д.Azure Bot Service authentication enables you to authenticate users to and get access tokens from a variety of identity providers such as Azure Active Directory, GitHub, Uber and so on. Кроме того, настроить проверку подлинности можно для пользовательского поставщика удостоверений OAuth2.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 utilize these capabilities you need to perform the following steps:

  1. Статически настройте settings в боте, который содержит сведения о регистрации приложения у поставщика удостоверений.Statically configure settings on your bot that contains the details of your application registration with an identity provider.
  2. Используйте OAuthCard, указав сведения о приложении, которые используются для входа пользователя и были указаны на предыдущем шаге.Use an OAuthCard, backed by the application information you supplied in the previous step, to sign-in a user.
  3. Получите маркеры доступа с помощью API службы Azure Bot.Retrieve access tokens through Azure Bot Service API.

Вопросы безопасностиSecurity considerations

При использовании проверки подлинности службы Azure Bot для Web Chat важно учитывать несколько моментов, связанных с безопасностью.When you use Azure Bot Service authentication with Web Chat there are some important security considerations you must keep in mind.

  1. Олицетворение.Impersonation. Здесь олицетворение означает действие злоумышленника, в результате которого бот считает его другим пользователем.Impersonation here means an attacker makes the bot thinks he is someone else. В Web Chat злоумышленник может олицетворять кого-то, изменив идентификатор пользователя в активном экземпляре канала.In Web Chat, an attacker can impersonate someone else by changing the user ID of his Web Chat instance. Чтобы избежать этого, разработчики должны сделать так, чтобы идентификатор пользователя нельзя было угадать.To prevent this, it is recommend to bot developers to make the user ID unguessable.

    Если включить расширенную проверку подлинности, служба Azure Bot сможет обнаруживать и отклонять любые изменения идентификатора пользователя.If you enable enhanced authentication options, Azure Bot Service can further detect and reject any user ID change. Это означает, что идентификатор пользователя (Activity.From.Id) в сообщениях, отправляемых боту из Direct Line, всегда будет тем же, с которым вы инициализировали экземпляр Web Chat.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. Обратите внимание, что для использования этой функции идентификатор пользователя должен начинаться с dl_.Note that this feature requires the user ID starts with dl_.

    Примечание

    Если идентификатор User.Id указывается при смене секрета для маркера, этот User.Id внедряется в маркер.When a User.Id is provided while exchanging a secret for a token, that User.Id is embedded in the token. В DirectLine все отправляемые боту сообщения обязательно содержат этот идентификатор в виде значения From.Id действия. Если клиент отправляет сообщение в DirectLine с другим идентификатором From.Id, он будет замен на идентификатор в маркере перед перенаправлением сообщения в бот.DirectLine makes sure the messages sent to the bot have that id as the activity's From.Id. If a client sends a message to DirectLine having a different From.Id, it will be changed to the Id in the token before forwarding the message to the bot. Поэтому нельзя использовать другой идентификатор пользователя после инициализации секрета канала с этим идентификатором.So you cannot use another user id after a channel secret is initialized with a user id

  2. Удостоверения пользователей.User identities. Необходимо учитывать, что при работе используется два удостоверения пользователей:You must be aware that your are dealing with two 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.

    Когда программа-робот запрашивает у пользователя A в канале вход в поставщик удостоверений P, процесс входа должен гарантировать, что пользователь A подписывается на P. Если другому пользователю б разрешено входить в систему, то пользователь A сможет получить доступ к ресурсу пользователя б через робот.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. Web Chat предоставляет два механизма, обеспечивающих надлежащий процесс входа, как описано далее.In Web Chat we have 2 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 (aka 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 is still susceptible to phishing attacks. Злоумышленник может обманным путем вынудить другого пользователя выполнить вход, чтобы получить магический код путем фишинга.A malicious user can trick another user to sign-in and obtain the magic code through phishing.

    2. Из-за проблем с предыдущим подходом мы решили не использовать в службе Azure Bot магический код.Because of the issues with the previous approach, Azure Bot Service removed the need for the magic code. Служба Azure Bot гарантирует, что процесс входа может выполняться только в том же сеансе браузера, в котором запущен экземпляр Web Chat.Azure Bot Service guarantees that the sign-in process can only be completed in the same browser session as the Web Chat itself. Чтобы включить эту защиту в качестве программы-робота, необходимо начать Web Chat с прямым маркером , который содержит список доверенных доменов, в которых может размещаться клиент Интернет-чата.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. Ранее этот токен можно получить, только передав незарегистрированный необязательный параметр в API Direct Line.Before, you could only obtain this token by passing an undocumented optional parameter to the Direct Line token API. Но теперь благодаря расширенным параметрам проверки подлинности можно настроить статический список доверенных доменов (источников) на странице настройки Direct Line.Now, with enhanced authentication options, you can statically specify the trusted domain (origin) list in the Direct Line configuration page.

    См. сведения о включении проверки подлинности для бота с помощью службы Azure Bot.See also Add authentication to your bot via Azure Bot Service.

Примеры кодаCode examples

Следующий контроллер .NET использует включенные расширенные параметры проверки подлинности и возвращает маркер Direct Line и идентификатор пользователя.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; }
}

Следующий контроллер JavaScript использует включенные расширенные параметры проверки подлинности и возвращает маркер Direct Line и идентификатор пользователя.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');
        }
    });
});

Дополнительные ресурсыAdditional resources