Autenticação na API de Linha Direta 3.0

  • Artigo

Um cliente pode autenticar solicitações para a API de Linha Direta 3.0 usando um segredo obtido na página de configuração do canal de Linha Direta no Portal do Bot Framework ou usando um token obtido em tempo de execução. O segredo ou token deve ser especificado no Authorization cabeçalho de cada solicitação, usando este formato:

Authorization: Bearer SECRET_OR_TOKEN

Segredos e fichas

Um segredo de Linha Direta é uma chave mestra que pode ser usada para acessar qualquer conversa que pertença ao bot associado. Um segredo também pode ser usado para obter um token. Os segredos não expiram.

Um token de Linha Direta é uma chave que pode ser usada para acessar uma única conversa. Um token expira, mas pode ser atualizado.

Decidir quando ou se usar a chave secreta ou um token deve ser baseado em considerações de segurança. Expor a chave secreta pode ser aceitável se feito intencionalmente e com cuidado. De fato, esse é o comportamento padrão porque permite que a Direct Line descubra se o cliente é legítimo. De um modo geral, porém, a segurança é uma preocupação se você estiver tentando persistir os dados do usuário. Para obter mais informações, consulte a seção Considerações de segurança.

Se você estiver criando um aplicativo de serviço a serviço, especificar o Authorization segredo no cabeçalho das solicitações de API de Linha Direta pode ser uma abordagem mais simples. Se você estiver escrevendo um aplicativo em que o cliente é executado em um navegador da Web ou aplicativo móvel, convém trocar seu segredo por um token (que só funciona para uma única conversa e expirará a menos que seja atualizado) e especifique o Authorization token no cabeçalho das solicitações de API de Linha Direta. Escolha o modelo de segurança que melhor se adapta a si.

Nota

As credenciais do cliente Direct Line são diferentes das credenciais do bot. Isso permite que você revise suas chaves de forma independente e permite que você compartilhe tokens de cliente sem divulgar a senha do seu bot.

Obtenha um segredo da Linha Direta

Você pode obter um segredo de Linha Direta por meio da página de configuração do canal de Linha Direta para seu bot no portal do Azure:

Direct Line configuration

Gerar um token de Linha Direta

Para gerar um token de Linha Direta que possa ser usado para acessar uma única conversa, primeiro obtenha o segredo da Linha Direta na página de configuração do canal da Linha Direta no portal do Azure. Em seguida, faça esta solicitação para trocar seu segredo de Linha Direta por um token de Linha Direta:

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

Authorization No cabeçalho desta solicitação, substitua SECRET pelo valor do seu segredo de Linha Direta.

Os trechos a seguir fornecem um exemplo da solicitação e resposta Gerar token.

Pedido

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

A carga útil da solicitação, que contém os parâmetros do token, é opcional, mas recomendada. Ao gerar um token que pode ser enviado de volta para o serviço de Linha Direta, forneça a seguinte carga útil para tornar a conexão mais segura. Ao incluir esses valores, a Direct Line pode executar uma validação de segurança adicional do ID e nome do usuário, inibindo a adulteração desses valores por clientes mal-intencionados. A inclusão desses valores também melhora a capacidade do Direct Line de enviar a atividade de atualização da conversa, permitindo que ela gere a atualização da conversa imediatamente após o usuário ingressar na conversa. Quando essas informações não são fornecidas, o usuário deve enviar conteúdo antes que a Direct Line possa enviar a atualização da conversa.

{
  "user": {
    "id": "string",
    "name": "string"
  },
  "trustedOrigins": [
    "string"
  ]
}
Parâmetro Tipo Descrição
user.id string Opcional. ID específico do canal do usuário para codificar dentro do token. Para um usuário de Linha Direta, isso deve começar com dl_. Você pode criar um ID de usuário exclusivo para cada conversa e, para melhor segurança, você deve tornar esse ID imprevisível.
user.name string Opcional. O nome de exibição amigável do usuário para codificar dentro do token.
trustedOrigins matriz de cadeia de caracteres Opcional. Uma lista de domínios confiáveis para incorporar no token. Esses são os domínios que podem hospedar o cliente de Web Chat do bot. Isso deve corresponder à lista na página de configuração de Linha Direta do seu bot.

Response

Se a solicitação for bem-sucedida, a resposta conterá um valor válido para uma conversa e um tokenexpires_in valor que indica o número de segundos até que o token expire. Para que o token permaneça útil, você deve atualizá-lo antes que ele expire.

HTTP/1.1 200 OK
[other headers]

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

Gerar token versus iniciar conversa

A operação Gerar Token () é semelhante à operação Iniciar Conversação (POST /v3/directline/tokens/generatePOST /v3/directline/conversations), na medida em que ambas as operações retornam um token que pode ser usado para acessar uma única conversa. No entanto, ao contrário da operação Iniciar conversa, a operação Gerar token não inicia a conversa, não entra em contato com o bot e não cria uma URL WebSocket de streaming.

Se você planeja distribuir o token para os clientes e deseja que eles iniciem a conversa, use a operação Gerar token. Se você pretende iniciar a conversa imediatamente, use a operação Iniciar conversa .

Atualizar um token de Linha Direta

Um token de Linha Direta pode ser atualizado um número ilimitado de vezes, desde que não tenha expirado. Um token expirado não pode ser atualizado. Para atualizar um token de Linha Direta, emita esta solicitação:

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

Authorization No cabeçalho desta solicitação, substitua TOKEN_TO_BE_REFRESHED pelo token de Linha Direta que você deseja atualizar.

Os trechos a seguir fornecem um exemplo da solicitação e resposta do Token de Atualização.

Pedido

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

Response

Se a solicitação for bem-sucedida, a resposta conterá um novo que é válido para a mesma conversa que o token anterior e um expires_in valor que indica o número de segundos até que o novo token token expire. Para que o novo token permaneça útil, você deve atualizá-lo antes que ele expire.

HTTP/1.1 200 OK
[other headers]

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

Autenticação do Serviço de Bot do Azure AI

As informações apresentadas nesta seção são baseadas no artigo Adicionar autenticação ao seu bot por meio do Serviço de Bot do Azure AI.

A autenticação do Serviço de Bot do Azure AI permite que você autentique usuários e obtenha tokens de acesso de vários provedores de identidade, como Microsoft Entra ID, GitHub, Uber e assim por diante. Você também pode configurar a autenticação para um provedor de identidade OAuth2 personalizado. Tudo isso permite que você escreva um pedaço de código de autenticação que funciona em todos os provedores e canais de identidade suportados. Para usar esses recursos:

  1. Configure settings estaticamente em seu bot que contém os detalhes do registro do seu aplicativo com um provedor de identidade.
  2. Use um , apoiado pelas informações do aplicativo fornecidas na etapa anterior, para entrar em um OAuthCardusuário.
  3. Recupere tokens de acesso por meio da API do Serviço de Bot do Azure AI.

Considerações de segurança

Quando você usa a autenticação do Serviço de Bot do Azure AI com o Chat da Web, há algumas considerações de segurança importantes que você deve ter em mente.

  1. Falsificação de identidade. Representação é quando um invasor convence o bot de que o invasor é outra pessoa. No Chat da Web, um invasor pode se passar por outra pessoa alterando a ID de usuário de sua instância do Web Chat. Para evitar a falsificação de identidade, recomendamos que os desenvolvedores de bots tornem o ID do usuário imprevisível.

    Se você habilitar as opções de autenticação aprimoradas, o Serviço de Bot do Azure AI poderá detetar e rejeitar ainda mais qualquer alteração de ID do usuário. Isso significa que o ID de usuário (Activity.From.Id) nas mensagens da Linha Direta para o bot será sempre o mesmo com o qual você inicializou o Web Chat. Este recurso requer o ID do usuário para começar com dl_.

    Nota

    Quando um User.Id é fornecido durante a troca de um segredo por um token, esse User.Id é incorporado no token. A Linha Direta garante que as mensagens enviadas para o bot tenham esse ID como From.Id da atividade. Se um cliente enviar uma mensagem para a Linha Direta com um From.Id diferente, ela será alterada para o ID no token antes de encaminhar a mensagem para o bot. Portanto, você não pode usar outro ID de usuário depois que um segredo de canal é inicializado com um ID de usuário

  2. Identidades de usuário. Cada usuário tem várias identidades de usuário:

    1. A identidade do usuário em um canal.
    2. A identidade do usuário em um provedor de identidade no qual o bot está interessado.

Quando um bot pede ao usuário A em um canal para entrar em um provedor de identidade P, o processo de entrada deve garantir que o usuário A seja aquele que entra em P. Se outro usuário B tiver permissão para entrar, o usuário A terá acesso ao recurso do usuário B por meio do bot. No Web Chat, temos dois mecanismos para garantir que o usuário certo tenha entrado, conforme descrito a seguir.

  1. No final do login, no passado, o usuário recebia um código de 6 dígitos gerado aleatoriamente (código mágico). O utilizador tem de escrever este código na conversação que iniciou o início de sessão para concluir o processo de início de sessão. Esse mecanismo tende a resultar em uma má experiência do usuário. Além disso, ainda é suscetível a ataques de phishing. Um utilizador mal-intencionado pode enganar outro utilizador para iniciar sessão e obter o código mágico através de phishing.

  2. Devido aos problemas com a abordagem anterior, o Serviço de Bot do Azure AI removeu a necessidade do código mágico. O Serviço de Bot do Azure AI garante que o processo de entrada só pode ser concluído na mesma sessão do navegador que o próprio Bate-papo da Web. Para habilitar essa proteção, como desenvolvedor de bot, você deve iniciar o Web Chat com um token de Linha Direta que contenha uma lista de domínios confiáveis que podem hospedar o cliente de Web Chat do bot. Antes, você só podia obter esse token passando um parâmetro opcional não documentado para a API de token de Linha Direta. Agora, com as opções de autenticação aprimoradas, você pode especificar estaticamente a lista de domínios confiáveis (origem) na página de configuração da Linha Direta.

Para obter mais informações, consulte Adicionar autenticação ao seu bot por meio do Serviço de Bot do Azure AI.

Exemplos de código

O controlador .NET a seguir funciona com opções de autenticação aprimoradas habilitadas e retorna um Token de Linha Direta e ID de usuário.

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

O controlador JavaScript a seguir funciona com opções de autenticação aprimoradas habilitadas e retorna um token de linha direta e um ID de usuário.

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

Informações adicionais