Solucionar problemas de autenticação do Bot Framework

aplica-se a: SDK v4

Este guia pode ajudar você a solucionar problemas de autenticação com seu bot por meio da avaliação uma série de cenários para determinar onde há o problema.

Observação

para concluir todas as etapas deste guia, você precisará baixar e usar o Bot Framework Emulator e deve ter acesso às configurações de registro do Bot no portal do Azure.

ID de aplicativo e senha

A segurança do bot é configurada pela ID do aplicativo Microsoft e pela Senha do aplicativo Microsoft que você obtém quando registra seu bot com o Bot Framework. Normalmente, esses valores são especificados no arquivo de configuração do bot e usados para recuperar tokens de acesso do serviço Microsoft Account.

Se você ainda não tiver feito isso, implante seu bot no Azure para obter uma ID do aplicativo da Microsoft e uma senha de aplicativo da Microsoft que ele possa usar para autenticação.

Observação

Para localizar o AppID e AppPassword de um bot já implantado, consulte MicrosoftAppID e MicrosoftAppPassword.

Etapa 1: desabilitar a segurança e testar no localhost

Nesta etapa, você verificará se seu bot fica acessível e funcional no localhost quando a segurança estiver desabilitada.

Aviso

Desabilitar a segurança do seu bot pode permitir que invasores desconhecidos se passem pelos usuários. Só implemente o procedimento a seguir se estiver operando em um ambiente de depuração protegido.

Desabilitar a segurança

Para desabilitar a segurança do bot, edite suas definições de configuração para remover os valores da ID e da senha do aplicativo.

Se você estiver usando o SDK do bot Framework para .NET, adicione ou edite as configurações em seu appsettings.jsno arquivo:

  "MicrosoftAppId": "",
  "MicrosoftAppPassword": ""

Testar o bot no localhost

Em seguida, teste o bot usando o localhost usando o Emulador do Bot Framework.

  1. Inicie o bot no localhost.
  2. Instale o Emulador do Bot Framework.
  3. Conexão ao bot usando o Emulator.
    • digite http://localhost:port-number/api/messages na barra de endereços do Emulator, em que port-number corresponde ao número da porta mostrado no navegador em que seu aplicativo está em execução.
    • Verifique se os campos ID do aplicativo da Microsoft e Senha do aplicativo da Microsoft estão em branco.
    • Clique em Conectar.
  4. para testar a conectividade com o bot, digite um texto na Emulator e pressione Enter.

Se o bot responder à entrada e não houver erros na janela do chat, você acabou de verificar que o bot fica acessível e funcional no localhost quando a segurança está desabilitada. Vá para a Etapa 2.

Se um ou mais erros forem indicados na janela de chat, clique nos erros para obter detalhes. Entre os problemas comuns, há:

  • as configurações de Emulator especificam um ponto de extremidade incorreto para o bot. Verifique se foram incluídos o número da porta apropriada na URL e o caminho apropriado no final da URL (por exemplo, /api/messages).
  • as configurações de Emulator especificam um ponto de extremidade de bot que começa com https . No localhost, o ponto de extremidade deve começar com http.
  • as configurações de Emulator especificam um valor para o campo ID do aplicativo da microsoft e/ou o campo senha do aplicativo microsoft . Ambos os campos devem ficar vazios.
  • A segurança não foi desabilitada para o bot. Verifique se o bot não especifica um valor para a ID ou a senha do aplicativo.

Etapa 2: verificar a ID e a senha do aplicativo do bot

Nesta etapa, você verificará se a ID e a senha do aplicativo e que seu bot usará para autenticação são válidas. (Caso não saiba quais são esses valores, obtenha-os agora.)

Aviso

As instruções a seguir desabilitam a verificação de SSL para login.microsoftonline.com. Só execute esse procedimento em uma rede segura e cogite alterar a senha do aplicativo depois disso.

Emitir uma solicitação HTTP para o serviço de logon da Microsoft

Essas instruções descrevem como usar a cURL para emitir uma solicitação HTTP ao serviço de logon da Microsoft. É possível usar uma ferramenta alternativa, como o Postman; apenas verifique se a solicitação está em conformidade com o protocolo de autenticação do Bot Framework.

Para verificar se a ID e senha do aplicativo do seu bot são válidas, emita a solicitação a seguir usando cURL e substituindo APP_ID e APP_PASSWORD pela ID e senha do aplicativo do seu bot.

Dica

Sua senha pode conter caracteres especiais que tornam inválida a chamada a seguir. Nesse caso, tente converter sua senha para a codificação de URL.

curl -k -X POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token -d "grant_type=client_credentials&client_id=APP_ID&client_secret=APP_PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default"

Essa solicitação tenta trocar a ID e senha do aplicativo do seu bot senha por um token de acesso. Se a solicitação for bem-sucedida, você receberá um payload JSON que contém uma propriedade access_token, entre outras.

{"token_type":"Bearer","expires_in":3599,"ext_expires_in":0,"access_token":"eyJ0eXAJKV1Q..."}

Se a solicitação for bem-sucedida, você verificou que a ID e a senha do aplicativo especificadas na solicitação são válidas. Vá para a Etapa 3.

Se você receber um erro em resposta à solicitação, examine a resposta para identificar a causa do erro. Se a resposta indicar que a ID ou a senha do aplicativo é inválida, obtenha os valores corretos no Portal do Bot Framework e emita novamente a solicitação com os novos valores para confirmar se eles são válidos.

Etapa 3: habilitar a segurança e testar em localhost

Neste ponto, você verificou que seu bot fica acessível e funcional no localhost quando a segurança é desabilitada e confirmou que a ID e a senha do aplicativo que o bot usará para autenticação são válidas. Nesta etapa, você verificará se seu bot fica acessível e funcional no localhost quando a segurança estiver habilitada.

Habilitar segurança

A segurança do seu bot se baseia em serviços da Microsoft, mesmo quando seu bot é executado somente no localhost. Para habilitar a segurança do bot, edite as definições de configuração para preencher a ID e senha do aplicativo com os valores que você verificou na Etapa 2. Além disso, verifique se os pacotes estão atualizados, especificamente System.IdentityModel.Tokens.Jwt e Microsoft.IdentityModel.Tokens.

Se estiver usando o SDK do Bot Framework para .NET, preencha essas configurações em seu appsettings.config ou os valores correspondentes no arquivo appsettings.json:

<appSettings>
  <add key="MicrosoftAppId" value="APP_ID" />
  <add key="MicrosoftAppPassword" value="PASSWORD" />
</appSettings>

Se você estiver usando o SDK do Bot Framework para Node.js, preencha estas configurações (ou atualize as variáveis de ambiente correspondentes):

var connector = new builder.ChatConnector({
  appId: 'APP_ID',
  appPassword: 'PASSWORD'
});

Observação

Para localizar o AppID e AppPassword do seu bot, consulte MicrosoftAppID e MicrosoftAppPassword.

Testar o bot no localhost

Em seguida, teste o bot usando o localhost usando o Emulador do Bot Framework.

  1. Inicie o bot no localhost.
  2. Instale o Emulador do Bot Framework.
  3. Conexão ao bot usando o Emulator.
    • digite http://localhost:port-number/api/messages na barra de endereços do Emulator, em que port-number corresponde ao número da porta mostrado no navegador em que seu aplicativo está em execução.
    • Insira a ID do aplicativo do seu bot no campo ID do aplicativo Microsoft.
    • Insira a senha do aplicativo do seu bot no campo Senha do aplicativo Microsoft.
    • Clique em Conectar.
  4. para testar a conectividade com o bot, digite um texto na Emulator e pressione Enter.

Se o bot responder à entrada e não houver erros na janela do chat, você acabou de verificar que o bot fica acessível e funcional no localhost quando a segurança está habilitada. Vá para a Etapa 4.

Se um ou mais erros forem indicados na janela de chat, clique nos erros para obter detalhes. Entre os problemas comuns, há:

  • as configurações de Emulator especificam um ponto de extremidade incorreto para o bot. Verifique se foram incluídos o número da porta apropriada na URL e o caminho apropriado no final da URL (por exemplo, /api/messages).
  • as configurações de Emulator especificam um ponto de extremidade de bot que começa com https . No localhost, o ponto de extremidade deve começar com http.
  • nas configurações de Emulator, o campo ID do aplicativo da microsoft e/ou a senha do aplicativo microsoft não contêm valores válidos. Ambos os campos devem ser preenchidos, e cada um deve conter o valor correspondente que você verificou ao Etapa 2.
  • A segurança não foi habilitada para o bot. Verifique se as definições de configuração do bot especificam valores para a ID e para a senha do aplicativo.

Etapa 4: testar seu bot na nuvem

Neste ponto, você verificou que seu bot fica acessível e funcional no localhost quando a segurança é desabilitada, confirmou que a ID e senha do aplicativo do seu bot são válidas e verificou que seu bot fica acessível e funcional no localhost, quando a segurança é habilitada. Nesta etapa, você implantará seu bot na nuvem e verificará se ele fica acessível e funcional nesse ambiente com a segurança habilitada.

Implantar seu bot na nuvem

O Bot Framework exige que bots sejam acessíveis pela Internet, portanto, você deve implantar seu bot em uma plataforma de hospedagem de nuvem, como o Azure. Não se esqueça de habilitar a segurança do bot antes da implantação, conforme descrito em Etapa 3.

Observação

Se você ainda não tiver um provedor de hospedagem na nuvem, poderá registrar-se para uma conta gratuita.

Caso implante o bot no Azure, o SSL será configurado automaticamente para o aplicativo, habilitando o ponto de extremidade HTTPS que o Bot Framework exige. Se você implantar em outro provedor de hospedagem de nuvem, verifique se o aplicativo está configurado para SSL para que o bot tenha um ponto de extremidade HTTPS.

Testar seu bot

Para testar seu bot na nuvem com a segurança habilitada, conclua as etapas a seguir.

  1. Verifique se seu bot foi implantado com êxito e está em execução.
  2. Entre no portal do Azure.
  3. Navegue até o Registro de Canais do Bot para o bot no portal.
  4. Clique em Testar no Webchat no painel Gerenciamento de bot à esquerda.
  5. Para testar a conectividade ao seu bot, digite algum texto no controle de chat da Web e pressione Enter.

Se for indicado um erro na janela de bate-papo, use a mensagem de erro para determinar sua causa. Entre os problemas comuns, há:

  • O Ponto de extremidade de mensagens especificado na página Configurações de seu bot no Portal do Bot Framework está incorreto. Verifique se foi incluído o caminho apropriado no final da URL (por exemplo, /api/messages).
  • O Ponto de extremidade de mensagens especificado na página Configurações de seu bot no Portal do Bot Framework não começa com https ou não é confiável de acordo com o Bot Framework. Seu bot deve ter um certificado válido e de cadeia confiável.
  • O bot é configurado com valores ausentes ou incorretos para a ID ou senha do aplicativo. Verifique se as definições de configuração do bot especificam valores válidos para a ID e senha do aplicativo.

Se o bot responder apropriadamente à entrada, você verificou que ele fica acessível e funcional na nuvem com a segurança habilitada. Neste ponto, seu bot está pronto para se conectar a um canal com segurança, como Facebook Messenger, Direct Line e outros.

Recursos adicionais

Caso ainda esteja enfrentando problemas depois de concluir as etapas acima, você pode:

  • Examine as instruções sobre como depurar um bot e outros artigos sobre depuração nesta seção.
  • depure o bot na nuvem usando o software de encapsulamento Bot Framework Emulator e ngrok . O ngrok não é um produto da Microsoft.
  • Usar uma ferramenta de criação de proxies como o Fiddler para inspecionar o tráfego HTTPS de entrada e saída do seu bot. O Fiddler não é um produto da Microsoft.
  • Examine o Guia de autenticação do Bot Connector para saber mais sobre as tecnologias de autenticação utilizadas pelo Bot Framework.
  • Solicite ajuda de outras pessoas usando os recursos de suporte do Bot Framework.