Проверка подлинности в API Direct Line 3.0

Статья
10/27/2023

Клиент может проверить подлинность запросов к API Direct Line версии 3.0 с помощью секрета, который можно получить на странице конфигурации канала Direct Line на портале Bot Framework, или с помощью маркера, который можно получить во время выполнения. Секрет или маркер необходимо указать в заголовке Authorization каждого запроса, используя следующий формат:

Authorization: Bearer SECRET_OR_TOKEN

Секреты и маркеры

Секрет Direct Line — это главный ключ, который можно использовать для доступа ко всем диалогам, связанным с соответствующим ботом. Секрет также можно использовать для получения маркера. Срок действия секретов не истекает.

Маркер Direct Line — это ключ, который можно использовать для доступа к одному диалогу. Срок действия маркера ограничен, но его можно продлить.

При принятии решения о том, следует ли использовать секретный ключ или токен и когда это нужно делать, нужно учитывать вопросы безопасности. Секретный ключ должен предоставляться с какой-то целью (намеренно) и с осторожностью. Собственно, это поведение по умолчанию, благодаря чему Direct Line может определять, является ли клиент допустимым. Но в целом, если вы пытаетесь сохранить данные пользователя, обеспечение безопасности является критически важным. См. сведения о вопросах безопасности.

При создании приложения между службами проще всего указать секрет в заголовке Authorization запросов API Direct Line. Если вы создаете приложение, в котором клиент запускается в веб-браузере или в мобильном приложении, вы можете обменять секрет на маркер (который будет действительным только для одного диалога и перестанет действовать, если не будет продлен) и указать маркер в заголовке Authorization запросов API Direct Line. Выберите наиболее подходящую вам модель безопасности.

Примечание.

Учетные данные клиента Direct Line отличаются от учетных данных вашего бота. Это позволяет проверить ключи независимо друг от друга и предоставить маркеры клиента, не раскрывая пароль бота.

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

Секрет Direct Line можно получить с помощью страницы конфигурации канала Direct Line для бота в портал Azure:

Direct Line configuration

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

Чтобы создать маркер Direct Line, который можно использовать для доступа к одной беседе, сначала получите секрет Direct Line на странице конфигурации канала Direct Line в портал Azure. Затем выполните следующий запрос, чтобы обменять секрет Direct Line на маркер Direct Line:

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

В заголовке Authorization этого запроса замените SECRET значением секрета Direct Line.

Ниже приведены примеры фрагментов кода для запроса на создание маркера и соответствующего ответа.

Запросить

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

Полезные данные запроса, куда входят параметры маркера, необязательны, но рекомендуются. При создании маркера, который можно отправить обратно в службу Direct Line, предоставьте следующие полезные данные для более безопасного подключения. Благодаря этим значениям Direct Line сможет выполнять дополнительную проверку идентификатора и имени пользователя, препятствуя изменению этих значений злоумышленниками. Также эти значения упрощают для Direct Line отправку действия обновления диалога, что позволяет создать обновление беседы немедленно при присоединении пользователя. Если эта информация не указана, пользователь должен отправить содержимое, прежде чем Direct Line сможет отправить обновление беседы.

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

Параметр	Тип	Описание:
`user.id`	строка	Необязательно. Идентификатор пользователя в конкретном канале, который кодируется в маркере. Для пользователя Direct Line это значение начинается с `dl_`. Вы можете создать уникальный идентификатор пользователя для каждой беседы, а для повышения безопасности следует исключить возможность угадать этот идентификатор.
`user.name`	строка	Необязательно. Понятное отображаемое имя пользователя, которое кодируется в маркере.
`trustedOrigins`	строка массив	Необязательно. Список доверенных доменов для внедрения в маркер. Здесь перечисляются домены, которые могут размещать клиент веб-чата для бота. Этот список должен совпадать с тем, который указан на странице настройки Direct Line для бота.

Отклик

Если запрос выполнен успешно, ответ содержит token для одного диалога, а значение expires_in указывает количество секунд до истечения срока действия маркера. Чтобы токен оставался полезным, необходимо обновить токен до истечения срока его действия.

HTTP/1.1 200 OK
[other headers]

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

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

Операция создания маркера (POST /v3/directline/tokens/generate) аналогична операции начала диалога (POST /v3/directline/conversations) в том, что обе операции возвращают token, который можно использовать для доступа к одному диалогу. Однако, в отличие от операции запуска беседы, операция создания маркера не запускает беседу, не связывается с ботом и не создает URL-адрес потоковой передачи WebSocket.

Если вы хотите передать маркер клиентам, а также желаете, чтобы они начали диалог, используйте операцию создания маркера. Если вы хотите начать диалог немедленно, используйте операцию начала диалога.

Обновление маркера Direct Line

Маркер 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

Отклик

Если запрос выполнен успешно, ответ содержит новый token, который действителен для того же диалога, что и предыдущий маркер, а значение expires_in указывает количество секунд до истечения срока нового действия маркера. Чтобы продолжить использование нового маркера, необходимо продлить маркер до того, как его срок действия истечет.

HTTP/1.1 200 OK
[other headers]

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

Проверка подлинности azure AI Служба Bot

Сведения, представленные в этом разделе, основаны на добавлении проверки подлинности в бот с помощью Служба Bot статьи azure AI.

Проверка подлинности azure AI Служба Bot позволяет выполнять проверку подлинности пользователей и получать маркеры доступа от различных поставщиков удостоверений, таких как Идентификатор Microsoft Entra, GitHub, Uber и т. д. Кроме того, настроить проверку подлинности можно для пользовательского поставщика удостоверений OAuth2. Все это позволяет использовать только один фрагмент кода проверки подлинности, который будет работать для всех поддерживаемых поставщиков удостоверений и всех каналов. Чтобы использовать эти возможности, выполните следующие действия.

Статически настройте settings в боте, который содержит сведения о регистрации приложения у поставщика удостоверений.
Используйте OAuthCard, указав сведения о приложении, которые используются для входа пользователя и были указаны на предыдущем шаге.
Получение маркеров доступа с помощью API Служба Bot Azure.

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

При использовании проверки подлинности Azure AI Служба Bot с Веб-чат необходимо учитывать некоторые важные аспекты безопасности.

Олицетворение. Олицетворение заключается в том, что злоумышленник убеждает бота в том, что злоумышленник является кем-то другим. В Веб-чат злоумышленник может олицетворить другого пользователя, изменив идентификатор пользователя своего Веб-чат экземпляра. Чтобы предотвратить олицетворение, мы рекомендуем разработчикам ботов сделать идентификатор пользователя неуправляемым.

Если вы включите расширенные параметры проверки подлинности, Служба Bot Azure AI может дополнительно обнаружить и отклонить любое изменение идентификатора пользователя. Это означает, что идентификатор пользователя (Activity.From.Id) в сообщениях, отправляемых боту из Direct Line, всегда будет тем же, с которым вы инициализировали экземпляр Web Chat. Эта функция требует, чтобы идентификатор пользователя начал с dl_.

Примечание.

Если идентификатор User.Id указывается при смене секрета для маркера, этот User.Id внедряется в маркер. Direct Line гарантирует, что сообщения, отправленные боту, имеют этот идентификатор в качестве From.Id действия. Если клиент отправляет сообщение в Direct Line с другой From.Id, он будет изменен на идентификатор в маркере перед пересылкой сообщения боту. Поэтому вы не можете использовать другой идентификатор пользователя после инициализации секрета канала с идентификатором пользователя
Удостоверения пользователей. Каждый пользователь имеет несколько удостоверений пользователей:
1. Удостоверение пользователя в канале.
2. Удостоверение пользователя в поставщике удостоверений, которое бот интересует.

Когда бот просит пользователя A в канале войти в поставщик удостоверений P, процесс входа должен убедиться, что пользователь A — это тот, который входит в P. Если другому пользователю B разрешен вход, то пользователь A будет иметь доступ к ресурсу B пользователя через бот. В Веб-чат у нас есть два механизма обеспечения правильного входа пользователя, как описано ниже.

В конце входа в прошлом пользователь был представлен случайным образом созданный 6-значный код (волшебный код). Пользователь должен был ввести этот код в диалоге, который инициировал завершение процесса входа. Как правило, такой механизм неудобно использовать. Кроме того, он по-прежнему подвержен фишинговым атакам. Злоумышленник может обманным путем вынудить другого пользователя выполнить вход, чтобы получить магический код путем фишинга.
Из-за проблем с предыдущим подходом Azure AI Служба Bot удалил необходимость в магическом коде. Azure AI Служба Bot гарантирует, что процесс входа можно выполнить только в том же сеансе браузера, что и сам Веб-чат. Чтобы включить эту защиту в качестве разработчика бота, необходимо запустить Веб-чат с маркером Direct Line, который содержит список доверенных доменов, которые могут размещать Веб-чат клиента бота. Ранее этот токен можно получить, только передав незарегистрированный необязательный параметр в API Direct Line. Но теперь благодаря расширенным параметрам проверки подлинности можно настроить статический список доверенных доменов (источников) на странице настройки Direct Line.

Дополнительные сведения см. в статье "Добавление проверки подлинности в бот с помощью azure AI Служба Bot".

Примеры кода

Следующий контроллер .NET использует включенные расширенные параметры проверки подлинности и возвращает маркер Direct Line и идентификатор пользователя.

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 и идентификатор пользователя.

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

Проверка подлинности в API Direct Line 3.0

Секреты и маркеры

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

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

Запросить

Отклик

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

Обновление маркера Direct Line

Запросить

Отклик

Проверка подлинности azure AI Служба Bot

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

Примеры кода

Дополнительные сведения

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