Autenticação de usuário

APLICA-SE A: SDK v4

Às vezes, um bot deve acessar recursos online de forma segura em nome do usuário, como verificar e-mails, verificar o status de voo ou fazer um pedido. O usuário deve autorizar o bot a fazer isso em seu nome e, para autorizar o bot, o usuário precisa autenticar a identidade. O OAuth é usado para autenticar o usuário e autorizar o bot. Confira também Tipos de autenticação.

Se você quiser atualizar seu conhecimento sobre o OAuth, confira o seguinte:

• Boa visão geral do OAuth mais fácil de seguir do que a especificação formal
• Especificação OAuth

Autenticação do usuário na conversa

Para executar determinadas operações em nome de um usuário, como verificação de email, nova referência a um calendário, verificação de status de voo ou realização de pedidos, o bot precisará chamar um serviço externo, como o Microsoft Graph, o GitHub ou o serviço REST de uma empresa. Cada serviço externo tem um modo de proteger essas chamadas. Um modo comum de emitir essas solicitações é usar um token de usuário que identifique exclusivamente o usuário nesse serviço externo (às vezes chamado de JWT (Token Web JSON)).

Para proteger a chamada para um serviço externo, o bot precisa solicitar que o usuário entre, para que ele possa adquirir o token do usuário desse serviço. Muitos serviços dão suporte à recuperação de token por meio do protocolo OAuth ou OAuth2.

O Serviço de Bot de IA do Azure fornece cartões e serviços de início de sessão especializados que funcionam com o protocolo do OAuth e gerenciam o ciclo de vida do token. Um bot pode usar esses recursos para adquirir um token de usuário.

• Como parte da configuração do bot, uma conexão do OAuth é registrada no recurso Serviço de Bot de IA do Azure no Azure.

  A conexão contém informações sobre o provedor de identidade a ser usado, juntamente com uma ID e um segredo do cliente OAuth válidos, os escopos do OAuth a serem habilitados e outros metadados de conexão exigidos por esse provedor de identidade.

• No código do bot, a conexão OAuth é usada para ajudar a conectar o usuário e obter o token dele.

A imagem a seguir mostra os elementos envolvidos no processo de autenticação.

Sobre o serviço de token do Bot Framework

O serviço de token do Bot Framework é responsável por:

• Facilitar o uso do protocolo OAuth com uma ampla variedade de serviços externos.
• Armazenar os tokens com segurança para um bot, um canal, uma conversa e um usuário específicos.
• Adquirindo tokens de usuário.

  Dica

  Se o bot tiver um token de usuário expirado, o bot deverá:

  • Desconecte o usuário
  • Iniciar o fluxo de início de sessão novamente

Por exemplo, um bot que pode verificar os emails recentes de um usuário, usando a API do Microsoft Graph, requer um token de usuário de um Provedor de Identidade que, neste caso, é o Microsoft Entra ID. Em tempo de design, o desenvolvedor do bot executa estas duas etapas importantes:

1. Registra um aplicativo do Microsoft Entra ID, um Provedor de Identidade, com o Serviço de Token do Bot Framework, usando o portal do Azure.
2. Configura uma conexão OAuth (chamada, por exemplo, de GraphConnection) para o bot.

A imagem a seguir mostra a sequência de tempo da interação do usuário com um bot quando uma solicitação de email é feita usando o serviço do Microsoft Graph.

1. O usuário faz uma solicitação de email para o bot.

2. Uma atividade com essa mensagem é enviada do usuário para o serviço de canal do Bot Framework. O canal de serviço garante que o campo userid dentro da atividade tenha sido definido e que a mensagem seja enviada para o bot.

   Observação

   As IDs de usuário são específicas do canal, como a ID do Facebook ou o número de telefone de SMS do usuário.

3. O bot faz uma solicitação para o serviço de token do Bot Framework perguntando se ele já tem um token para a UserId da conexão OAuth GraphConnection.

4. Como essa é a primeira vez que esse usuário interage com o bot, o Serviço de Token do Bot Framework ainda não tem um token para esse usuário e retorna um resultado NotFound para o bot.

   Observação

   Se o token for encontrado, as etapas de autenticação serão ignoradas e o bot poderá fazer a solicitação de email usando o token armazenado.

5. O bot cria um OAuthCard com um nome de conexão GraphConnection e responde ao usuário solicitando que ele entre usando esse cartão.

6. A atividade passa pelo serviço de canal do Bot Framework, que chama o serviço de token do Bot Framework para criar uma URL de entrada do OAuth válida para esta solicitação. Essa URL de entrada é adicionada ao OAuthCard e o cartão é retornado ao usuário.

7. Uma mensagem é apresentada ao usuário solicitando que ele entre clicando no botão de entrada do OAuthCard.

8. Quando o usuário clica no botão de entrada, o serviço de canal abre um navegador da Web e chama o serviço externo para carregar sua página de entrada.

9. O usuário entra nesta página para o serviço externo. Em seguida, o serviço externo conclui a troca de protocolo OAuth com o serviço de token do Bot Framework, fazendo com que o serviço externo envie o token de usuário ao serviço de token do Bot Framework. O serviço de token do Bot Framework armazena esse token com segurança e envia uma atividade ao bot com esse token.

10. O bot recebe a atividade com o token e pode usá-lo para fazer chamadas à API do MS Graph.

Protegendo a URL de entrada

Uma consideração importante quando o Bot Framework facilita um logon de usuário é como proteger a URL de entrada. Quando uma URL de entrada é apresentada ao usuário, essa URL é associada a uma ID de conversa e a uma ID de usuário específicas desse bot. Não compartilhe esse URL. Isso faria com que ocorresse um início de sessão incorreto para uma conversa de bot específica. Para a mitigação de ataques de segurança relacionados ao uso de um URL de início de sessão compartilhado, certifique-se de que o computador e a pessoa que clica no URL de início de sessão sejam proprietários da janela de conversa.

Alguns canais, como o Microsoft Teams, o Direct Line e o Webchat, podem fazer isso sem que o usuário perceba. Por exemplo, o WebChat usa cookies de sessão para garantir que o fluxo de entrada ocorra no mesmo navegador que a conversa do WebChat. No entanto, para outros canais, geralmente é apresentado um código mágico de seis dígitos ao usuário. Isso tem similaridade com uma autenticação multifator interna, pois o Serviço de Token do Bot Framework não liberará o token para o bot, a menos que o usuário conclua a autenticação final, comprovando que a pessoa que iniciou a sessão tem acesso à experiência de chat ao inserir o código de seis dígitos.

Próximas etapas

Agora que você já sabe sobre a autenticação do usuário, vamos conferir como aplicá-la ao seu bot.

Confira também

• Provedores de Identidade
• Autenticação do Conector REST
• Autenticação de REST para o canal Direct Line