Adicionar autenticação ao seu bot do Teams

Você pode criar bots no Microsoft Teams que acessam recursos em nome do usuário, como um serviço de email. Você pode usar a autenticação do SDK do Azure Serviço de Bot v4, com base no OAuth 2.0. Esse método facilita o desenvolvimento de um bot que pode usar tokens de autenticação com base nas credenciais do usuário. A chave é o uso de provedores de identidade.

O OAuth 2.0 é um padrão aberto para autenticação e autorização usado por Microsoft Entra ID e muitos outros provedores de identidade. Uma compreensão básica do OAuth 2.0 é pré-requisito para trabalhar com autenticação no Teams.

Confira o artigo OAuth 2 Simplificado para uma compreensão básica e OAuth 2.0 para obter a especificação completa.

Para obter mais informações sobre como o Serviço de Bots do Azure lida com a autenticação, confira o artigo Autenticação de usuário dentro de uma conversa.

Neste artigo, você aprenderá:

• Como criar um bot habilitado para autenticação. Você usará o recurso cs-auth-sample para lidar com as credenciais de login do usuário e gerar o token de autenticação.
• Como implantar o bot no Azure e associá-lo a um provedor de identidade. O provedor emite um token com base nas credenciais de login do usuário. O bot pode usar o token para acessar recursos que exigem autenticação, como um serviço de e-mail. Para obter mais informações, confira Fluxo de autenticação do Microsoft Teams para bots.
• Como integrar o bot dentro do Microsoft Teams. Depois que o bot for integrado, você poderá entrar e trocar mensagens com ele em um chat.

Pré-requisitos

• Conhecimento de noções básicas de bots, status de gerenciamento, biblioteca de diálogos e de como implementar um fluxo de conversa sequencial.

• Conhecimento do Azure e do desenvolvimento do OAuth 2.0.

• Versões atuais do Microsoft Visual Studio e do Git.

• Uma conta do Azure. Se necessário, você pode criar uma conta gratuita do Azure.

• O exemplo a seguir,

  uma amostra de	versão do BotBuilder,	demonstra
  uma autenticação de bot no cs-auth-sample	v4	com suporte a OAuthCard
  uma autenticação de bot no js-auth-sample	v4	com suporte a OAuthCard
  uma autenticação de bot no py-auth-sample	v4	com suporte a OAuthCard

Criar o grupo de recursos

O grupo de recursos e o plano de serviços não são estritamente necessários, mas permitem que você lance convenientemente os recursos que criar. É recomendável manter seus recursos organizados e gerenciáveis.

Você usa um grupo de recursos para criar recursos individuais para o Bot Framework. Para garantir o desempenho, certifique-se de que esses recursos esteiam localizados na mesma região do Azure.

1. No seu navegador, entre no portal do Microsoft Azure.
2. No painel de navegação esquerdo, selecione Grupos de recursos.
3. No canto superior esquerdo da janela exibida, selecione a guia Adicionar para criar um novo grupo de recursos. Forneça os seguintes detalhes:
   1. Assinatura. Use sua assinatura existente.
   2. Grupo de recursos. Digite o nome do grupo de recursos. Um exemplo pode ser TeamsResourceGroup. Lembre-se de que o nome deve ser único.
   3. No menu suspenso Região , selecione Oeste dos EUA ou uma região próxima aos seus aplicativos.
   4. Selecione o botão Rever e criar. Você deverá ver uma faixa com o texto Validação aprovada.
   5. Selecione o botão Criar. Poderá levar alguns minutos para criar o grupo de recursos.

Dica

Assim como ocorre com os recursos que você criará mais adiante neste tutorial, é uma boa ideia fixar esse grupo de recursos no seu painel de controle para facilitar o acesso. Se você quiser fazer isso, selecione o ícone 📌 de fixação no canto superior direito do dashboard.

Criar o plano de serviço

1. No Portal do Azure, no painel de navegação esquerdo, selecione Criar um recurso.
2. Na caixa de pesquisa, digite Plano de Serviço do Aplicativo (em inglês: App Service Plan). Selecione o cartão do Plano de Serviço do Aplicativo nos resultados da pesquisa.
3. Selecione Criar.
4. Forneça as seguintes informações:
   1. Assinatura. Você pode usar uma assinatura existente.
   2. Grupo de Recursos. Selecione o grupo que você criou anteriormente.
   3. Nome. Digite o nome do plano de serviço. Um exemplo pode ser TeamsServicePlan. Lembre-se de que o nome deve ser único dentro do grupo.
   4. Sistema Operacional. Selecione Windows ou seu sistema operacional aplicável.
   5. Região. Selecione Oeste dos EUA ou uma região próxima dos seus aplicativos.
   6. Nível de preço. Selecione Standard S1, que é o valor padrão.
   7. Selecione o botão Rever e criar. Você deverá ver uma faixa com o texto Validação aprovada.
   8. Selecione Criar. Poderá levar alguns minutos para criar o plano de serviço do aplicativo. O plano está listado no grupo de recursos.

Criar um registro de recursos do Bot do Azure

O registro de recursos do Azure Bot registra seu serviço Web como um bot com o Bot Framework, que fornece uma ID do Aplicativo Microsoft e senha do aplicativo (segredo do cliente).

Importante

Você só precisa registrar seu bot se ele não estiver hospedado no Azure. Se você criou um bot por meio do portal do Azure, ele já está registrado no serviço. Se você criou seu bot por meio do Bot Framework ou do Portal do Desenvolvedor, seu bot não estará registrado no Azure.

1. Visite o Portal do Azure e pesquise Bot do Azure na seção Criar um recurso.

2. Abra o Bot do Azure e selecione Criar.

3. Digite o nome do identificador do bot no campo Identificador do bot.

4. Selecione sua Assinatura na lista suspensa.

5. Selecione seu Grupo de recursos na lista suspensa.

6. Selecione o Tipo de AplicativoMultilocatário para a ID de Aplicativo da Microsoft.

   

7. Selecione Rever + criar.

   

8. Se a validação for aprovada, selecione Criar.

   O Azure provisiona seu bot em alguns momentos.

   

9. Selecione Vá para o recurso. O bot e os respectivos recursos estão listados no grupo de recursos.

   

   Seu bot do Azure é criado.

   

Para criar um segredo do cliente:

1. Em Configurações, selecione Configurar. Salve a ID de Aplicativo da Microsoft (ID do cliente) para referência futura.

   

2. Ao lado da ID do Aplicativo da Microsoft, selecione Gerenciar.

   

3. Na seção Segredos do cliente, selecione Novo segredo do cliente. A janela Adicionar um segredo do cliente irá aparecer.

   

4. Digite uma Descrição e selecione Adicionar.

   

5. Na coluna Valor, selecione Copiar para a área de transferência e salve a ID do segredo do cliente para referência futura.

   

Para adicionar o canal do Microsoft Teams:

1. Vá para a Página Inicial.

   

2. Abra o bot na seção Recursos recentes .

3. Selecione Canais no painel esquerdo e selecione Microsoft Teams .

   

4. Selecione a caixa de seleção para aceitar os termos de serviço e selecione Concordar.
   

   

5. Selecione Salvar.

   

Para obter mais informações, confira Criar um bot para o Teams.

Criar o provedor de identidade

Você precisa de um provedor de identidade para autenticação. Neste procedimento, você usa um provedor de Microsoft Entra. Como alternativa, você também pode usar outros provedores de identidade com suporte para ID Microsoft Entra.

1. No portal do Azure, no painel de navegação esquerdo, selecione Microsoft Entra ID.

   Dica

   Você precisará criar e registrar esse recurso Microsoft Entra em um locatário no qual você pode consentir em delegar permissões solicitadas por um aplicativo. Para obter instruções sobre como criar um locatário, confira o artigo Acessar o portal e criar um locatário.

2. No painel esquerdo, selecione Registros de aplicativos.

3. No painel direito, selecione a guia Novo registro, no canto superior esquerdo.

4. Forneça as seguintes informações:

   1. Nome. Digite o nome para o aplicativo. Um exemplo pode ser BotTeamsIdentity. Lembre-se de que o nome deve ser único.
   2. Selecione Tipos de conta com suporte para seu aplicativo. Selecione Contas em qualquer diretório organizacional (Qualquer locatário de ID Microsoft Entra – Multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox).
   3. Para o URI de redirecionamento:
      ✓Selecione Web.
      ✓ Defina a URL como https://token.botframework.com/.auth/web/redirect.
   4. Selecione Registrar.

5. Depois de criado, o Azure exibe a página Visão geral do aplicativo. Copie e salve as seguintes informações em um arquivo:

   1. O valor ID do aplicativo (cliente). Você usará esse valor mais tarde como a ID do cliente ao registrar esse aplicativo de identidade do Azure junto ao seu bot.
   2. O valor ID do diretório (locatário). Você usará esse valor mais tarde como a ID do Locatário para registrar este aplicativo de identidade do Azure com seu bot.

6. No painel esquerdo, selecione Certificados e segredos para criar um segredo do cliente para seu aplicativo.

   1. Em Segredos do cliente, selecione ➕ Novo segredo do cliente.
   2. Adicione uma descrição para identificar esse segredo e diferenciá-lo de outros que você talvez precise criar para esse aplicativo, como, por exemplo, Identidade do aplicativo de bot no Teams.
   3. Configure Expira em para a sua seleção.
   4. Selecione Adicionar.
   5. Antes de sair desta página, grave o segredo. Você usará esse valor posteriormente como o segredo do Cliente ao registrar seu aplicativo Microsoft Entra com o bot.

Configurar a conexão do provedor de identidade e registrá-la junto ao bot

Observação

Há duas opções para Provedores de Serviços aqui, Azure Active Directory v1 e Azure Active Directory v2. As diferenças entre os dois provedores são resumidas aqui, mas, em geral, o v2 fornece mais flexibilidade em relação à alteração das permissões do bot. As permissões de Graph API estão listadas no campo de escopos e, à medida que novas forem adicionadas, os bots permitirão que os usuários deem seu consentimento às novas permissões no próximo login. Para v1, o consentimento do bot deve ser excluído pelo usuário para que novas permissões sejam solicitadas na caixa de diálogo OAuth.

Microsoft Azure Active Directory (Azure AD) v1

1. No Portal do Azure, selecione seu grupo de recursos no painel de controle.

2. Selecione o link de registro do bot.

3. Abra a página de recursos e selecione Configurar, na guia Configurações.

4. Selecione Adicionar configurações de conexão OAuth. A imagem a seguir exibe a seleção correspondente na página de recursos:

   

5. Preencha o formulário de acordo com as instruções a seguir:

   1. Nome. Digite um nome para a conexão. Você usa esse nome no bot no appsettings.json arquivo. Por exemplo, BotTeamsAuthADv1.

   2. Provedor de serviços. Selecione Azure Active Directory. Depois de selecionar essa opção, os campos específicos do Azure Active Directory serão exibidos.

   3. ID do cliente. Insira a ID do aplicativo (cliente) que você gravou para o aplicativo do provedor de identidade do Azure.

   4. Segredo do cliente. Insira o segredo que você gravou para seu aplicativo do provedor de identidade do Azure.

   5. Tipo de Concessão. Digite authorization_code.

   6. URL de login. Digite https://login.microsoftonline.com.

   7. ID do locatário: digite a ID do diretório (locatário) que você gravou anteriormente para o seu aplicativo de identidade do Azure ou comum, dependendo do tipo de conta com suporte selecionado quando você criou o aplicativo do provedor de identidade. Para decidir qual valor atribuir, siga estes critérios:

      • Se você selecionou contas neste diretório organizacional somente (somente Microsoft – locatário único) ou Contas em qualquer diretório organizacional (Qualquer locatário de ID Microsoft Entra – Multilocatário), insira a ID do locatário que você registrou anteriormente para o aplicativo Microsoft Entra. Esse será o locatário associado aos usuários que podem ser autenticados.

      • Se você selecionou Contas em qualquer diretório organizacional (Qualquer locatário de ID Microsoft Entra – Multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox) inserirá a palavra comum em vez de uma ID de locatário. Caso contrário, o aplicativo Microsoft Entra verifica por meio do locatário cuja ID foi selecionada e exclui contas pessoais da Microsoft.

   h. Para o URL do recurso, digite https://graph.microsoft.com/. Essa URL não é usada no exemplo de código atual.
   i. Deixe Escopos em branco. A imagem a seguir é um exemplo:

   

6. Selecione Salvar.

Microsoft Azure Active Directory (Azure AD) v2

1. No Portal do Azure, selecione seu Bot do Azure no painel de controle.

2. Na página de recursos, selecione Configurar, na guia Configurações.

3. Selecione Adicionar configurações de conexão OAuth.
   A imagem a seguir exibe a seleção correspondente na página de recursos:

   

4. Preencha o formulário de acordo com as instruções a seguir:

   1. Nome. Digite um nome para a conexão. Você usará esse nome no seu bot no arquivo appsettings.json. Por exemplo, BotTeamsAuthADv2.

   2. Provedor de serviços. Selecione Azure Active Directory v2. Depois de selecionar essa opção, os campos específicos Azure AD v2 serão exibidos.

   3. ID do cliente. Insira a ID do aplicativo (cliente) que você gravou para o aplicativo do provedor de identidade do Azure.

   4. Segredo do cliente. Insira o segredo que você gravou para seu aplicativo do provedor de identidade do Azure.

   5. URL da troca de tokens. Deixe em branco.

   6. ID do locatário: digite a ID do diretório (locatário) que você gravou anteriormente para o seu aplicativo de identidade do Azure ou comum, dependendo do tipo de conta com suporte selecionado quando você criou o aplicativo do provedor de identidade. Para decidir qual valor atribuir, siga estes critérios:

      • Se você selecionou contas neste diretório organizacional somente (somente Microsoft – locatário único) ou Contas em qualquer diretório organizacional (Qualquer locatário de ID Microsoft Entra – Multilocatário), insira a ID do locatário que você registrou anteriormente para o aplicativo Microsoft Entra. Esse será o locatário associado aos usuários que podem ser autenticados.

      • Se você selecionou Contas em qualquer diretório organizacional (Qualquer locatário de ID Microsoft Entra – Multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox) inserirá a palavra comum em vez de uma ID de locatário. Caso contrário, o aplicativo Microsoft Entra verifica por meio do locatário cuja ID foi selecionada e exclui contas pessoais da Microsoft.

   7. Para Escopos, insira uma lista delimitada por espaço de permissões de grafo que este aplicativo exige, como User.Read, User.ReadBasic.All ou Mail.Read.

5. Selecione Salvar.

Testar a conexão

1. Selecione a entrada de conexão para abrir a conexão que você criou.

2. Selecione Testar Conexão na parte superior do painel de controle da Configuração de Conexão do Provedor de Serviços.

3. Pela primeira vez, ele abre uma nova janela do navegador solicitando que você selecione uma conta. Selecione a que você quer usar.

4. Em seguida, permita que o provedor de identidade use seus dados (credenciais). A imagem a seguir é um exemplo:

   

5. Selecione Aceitar.

6. Uma página Conexão de Teste com <seu nome> de conexão bem-sucedida é aberta. Atualize a página caso receba uma mensagem de erro. A imagem a seguir é um exemplo:

   

O código do bot usa o nome da conexão para recuperar tokens de autenticação do usuário.

Preparar a amostra de código do bot

Com as configurações preliminares concluídas, vamos nos concentrar na criação do bot a ser usado neste artigo.

C#/.NET

1. Clonar a cs-auth-sample.

2. Abra o Visual Studio.

3. Na barra de ferramentas, selecione Arquivo > Abrir > Projeto/Solução e abra o projeto do bot.

4. Em C#, atualize appsettings.json da seguinte maneira:

   • Defina ConnectionName como o nome da conexão do provedor de identidade que você adicionou ao registro do bot. O nome que usamos nesse exemplo foi BotTeamsAuthADv1.
   • Defina MicrosoftAppId como a ID do aplicativo de bot que você salvou no momento do registro do bot.
   • Defina MicrosoftAppPassword como o segredo do cliente que você salvou no momento do registro do bot.

   Dependendo dos caracteres do segredo do seu bot, talvez seja necessário que o XML escape da senha. Por exemplo, todos os caracteres E comerciais (&) precisarão ser codificados como &.

   {
     "MicrosoftAppType": "",
     "MicrosoftAppId": "",
     "MicrosoftAppPassword": "",
     "ConnectionName": "",
   

5. No Gerenciador de Soluções, vá para a TeamsAppManifest pasta, abra manifest.json e defina id e botId para a ID do aplicativo bot que você salvou no momento do registro do bot. Para obter mais informações, consulte o manifesto do aplicativo.

JavaScript

1. Clonar a node-auth-sample.

2. Em um console, acesse o projeto:
   
   cd samples/bot-teams-authentication/nodejs

3. Instalar módulos
   
   npm install

4. Atualize a configuração .env conforme se segue:

   • Defina MicrosoftAppId como a ID do aplicativo de bot que você salvou no momento do registro do bot.
   • Defina MicrosoftAppPassword como o segredo do cliente que você salvou no momento do registro do bot.
   • Configure o connectionName como o nome da conexão do provedor de identidade. Dependendo dos caracteres do segredo do seu bot, talvez seja necessário que o XML escape da senha. Por exemplo, todos os caracteres E comerciais (&) precisarão ser codificados como &.

   MicrosoftAppId=
   MicrosoftAppPassword=
   connectionName=
   MicrosoftAppType= MultiTenant # Set this to SingleTenant if you are using a single tenant app registration
   MicrosoftAppTenantId= common # Set your tenantId here if you are using single tenant app registration.
   

5. teamsAppManifest Na pasta, abra manifest.json e defina id para sua ID do Aplicativo Microsoft e botId para a ID do aplicativo bot que você salvou no momento do registro do bot.

Python

1. Clone py-auth-sample do repositório GitHub.

2. Atualize o config.py:

   • Defina ConnectionName como o nome da configuração de conexão OAuth que você adicionou ao seu bot.

   • Defina MicrosoftAppId e MicrosoftAppPassword como a ID do aplicativo e o segredo do aplicativo do seu bot.

     Dependendo dos caracteres do segredo do seu bot, talvez seja necessário que o XML escape da senha. Por exemplo, todos os caracteres E comerciais (&) precisarão ser codificados como &.

     APP_ID = os.environ.get("MicrosoftAppId", "")
     APP_PASSWORD = os.environ.get("MicrosoftAppPassword", "")
     CONNECTION_NAME = os.environ.get("ConnectionName", "")
     

Implantar o bot no Azure

Para implantar o bot, siga as etapas no Como Implantar seu bot no Azure.

Alternativamente, enquanto estiver no Visual Studio você pode seguir as etapas abaixo:

1. No Visual Studio Gerenciador de Soluções, selecione e segure (ou clique com o botão direito do mouse) no nome do projeto.

2. No menu suspenso, selecione Publicar.

3. Na janela que aparece, selecione o Novo link.

4. Na janela de diálogo, selecione Serviço de Aplicativo e Criar Novo.

5. Selecione o botão Publicar.

6. Na próxima janela de diálogo, insira as informações solicitadas.

   

7. Selecionar Criar.

8. Se a implantação for concluída com sucesso, você deverá vê-la refletida no Visual Studio. Uma página é aberta no navegador padrão com a mensagem Seu bot está pronto!. A URL é semelhante a https://botteamsauth.azurewebsites.net/. Salve-o em um arquivo.

9. No navegador, vá para o portal do Azure.

10. Verifique seu grupo de recursos, o bot está listado junto com os outros recursos. A imagem a seguir é um exemplo:

    

11. No grupo de recursos, selecione o nome de registro do bot (link).

12. No painel esquerdo, selecione Configurações.

13. Na caixa Ponto de extremidade mensagens , insira a URL que você acabou de obter seguida por api/messages. Por exemplo, https://botteamsauth.azurewebsites.net/api/messages.

    Observação

    Somente um ponto de extremidade de mensagens é permitido para um bot.

14. Selecione o botão Salvar no canto superior esquerdo.

Testar o bot usando o Emulador

Se ainda não o tiver feito, instale o Emulador de Bot Framework da Microsoft. Confira também Depurar com o Emulador.

Para que a entrada de exemplo do bot funcione, você deve configurar o Emulador.

Configurar o Emulador para a autenticação

Se um bot exigir autenticação, você precisará configurar o Emulador. Para configurar:

1. Inicie o Emulador.
2. No Emulador, selecione o ícone ⚙ de engrenagem na parte inferior esquerda ou a guia Configurações do Emulador no canto superior direito.
3. Marque a caixa próxima a Usar tokens de autenticação versão 1.0.
4. Digite o caminho local para a ferramenta ngrok. Confira o wiki de integração entre o Emulador de Bot Framework e a criação de túneis do ngrok. Para obter mais informações sobre a ferramenta, confira o ngrok.
5. Marque a caixa próxima a Executar o ngrok ao iniciar o Emulador.
6. Selecione o botão Salvar.

Quando o bot exibe um cartão de login e o usuário seleciona o botão de login, o Emulador abre uma página que o usuário pode usar para entrar com o provedor de autenticação. Após o usuário ter feito isso, o provedor gera um token de usuário e o envia para o bot. A partir daí o bot pode agir em nome do usuário.

Testar o bot localmente

Depois de configurar o mecanismo de autenticação, você poderá executar o teste de bot real.

1. Por exemplo, execute a amostra do bot localmente no seu computador por meio do Visual Studio.

2. Inicie o Emulador.

3. Selecione o botão Abrir bot.

4. No URL do bot, digite o URL local do bot. Normalmente, http://localhost:3978/api/messages.

5. Na ID do Aplicativo Microsoft, insira a ID do aplicativo do bot de appsettings.json.

6. Na senha do Aplicativo Microsoft, insira a senha do aplicativo do bot a appsettings.jsonpartir do .

7. Selecione Conectar.

8. Quando o bot estiver ativado e funcionando, digite um texto qualquer para exibir o cartão de login.

9. Selecione o botão Entrar.

10. Uma caixa de diálogo pop-up aparece para confirmar a URL Aberta para autenticar o usuário do bot (você).

11. Selecione Confirmar.

12. Se solicitado, selecione a conta de usuário aplicável.

13. Dependendo de qual configuração você usou para o Emulador, você obtém uma das seguintes opções:

    1. Usar um código de verificação de login
       ✓ Uma janela é aberta exibindo o código de validação.
       ✓ Copie e insira o código de validação na caixa de chat para concluir a entrada.
    2. Usar tokens de autenticação.
       ✓ Você está conectado com base em suas credenciais.

    A imagem a seguir é um exemplo da interface de usuário do bot após você ter entrado:

    

14. Se você selecionar Sim quando o bot perguntar Gostaria de exibir seu token?, você receberá a seguinte resposta:

    

15. Insira logon na caixa de chat de entrada para sair. Ele libera o token de usuário e o bot não poderá agir em seu nome até que você entre novamente.

Observação

A autenticação do bot requer o uso do Serviço de Conector do Bot. O serviço acessa as informações de registro de bots do seu bot.

Testar o bot implantado

1. No navegador, vá para o portal do Azure.

2. Localize seu grupo de recursos.

3. Selecione o link do recurso. A página de recursos é exibida.

4. Na página de recursos, selecione Testar no web chat. O bot é iniciado e mostra as saudações predefinidas.

5. Digite qualquer coisa na caixa de chat.

6. Selecione a caixa Login.

7. Uma caixa de diálogo pop-up aparece para confirmar a URL Aberta para autenticar o usuário do bot (você).

8. Selecione Confirmar.

9. Se solicitado, selecione a conta de usuário aplicável. A imagem a seguir é um exemplo da interface de usuário do bot após você ter entrado:

   

10. Selecione o botão Sim para exibir seu token de autenticação. A imagem a seguir é um exemplo:

    

11. Insira logon na caixa de chat de entrada para sair.

    

Observação

Se estiver tendo problemas para entrar, tente testar a conexão novamente conforme descrito nas etapas anteriores. É possível que isso recrie o token de autenticação. Com o cliente de Chat na Web do Bot Framework no Azure talvez seja necessário entrar várias vezes antes de a autenticação ser estabelecida corretamente.

Instalar e testar o bot no Teams

1. No seu projeto de bot, verifique se a pasta TeamsAppManifest contém manifest.json juntamente com os arquivos outline.png e color.png.

2. Em Gerenciador de Soluções, vá para a TeamsAppManifest pasta. Edite manifest.json atribuindo os seguintes valores:

   1. Certifique-se de que a ID do aplicativo de bot recebida no momento do registro do bot foi atribuída a id e botId.
   2. Atribua o valor: validDomains: [ "token.botframework.com" ].

3. Selecione e zipe os arquivos manifest.json, outline.png e color.png.

4. Abra o Microsoft Teams.

5. No painel esquerdo, na parte de baixo, selecione o Ícone de aplicativos.

6. No painel direito, na parte de baixo, selecione Carregar um aplicativo personalizado.

7. Vá para a TeamsAppManifest pasta e carregue o manifesto com zíper. A seguinte janela é exibida:

   

8. Selecione o botão Adicionar a uma equipe.

9. Na próxima janela, selecione a equipe na qual você deseja usar o bot.

10. Selecione o botão Configurar um bot.

11. Selecione os três pontos (●●●) no painel esquerdo. Em seguida, selecione o ícone Portal do Desenvolvedor .

12. Selecione a guia Editor do manifesto. Você deverá ver o ícone do bot que você carregou.

13. Além disso, você deve conseguir ver o bot listado como um contato na lista de chats que você pode usar para trocar mensagens com o bot.

Testar o bot localmente no Teams

O Teams é um produto totalmente baseado em nuvem, exige que todos os serviços acessados estejam disponíveis na nuvem usando pontos de extremidade HTTPS. Portanto, para habilitar o bot (nossa amostra) e permitir que funcione no Teams, você precisa publicar o código na nuvem de sua escolha ou tornar uma instância em execução local acessível externamente por meio de uma ferramenta de criação de túnel. Recomendamos o ngrok, que cria uma URL endereçável externamente para uma porta aberta localmente em seu computador. Para configurar o ngrok em preparação para executar seu aplicativo do Teams localmente, siga estas etapas:

1. Em uma janela do terminal, vá para o diretório onde você instalou o ngrok.exe. Sugerimos que você configure o caminho da variável de ambiente apontando para ele.

2. Execute, por exemplo, ngrok http 3978 --host-header=localhost:3978. Substitua o número da porta conforme necessário. Ele inicia o ngrok para ouvir na porta especificada. Em troca, ele irá lhe fornecer um URL endereçável externamente e válido enquanto o ngrok estiver em execução. A imagem a seguir é um exemplo:

   

3. Copie o endereço HTTPS de encaminhamento semelhante a: https://dea822bf.ngrok.io/.

4. Anexe /api/messages para obter https://dea822bf.ngrok.io/api/messages, que é o ponto de extremidade de mensagens para o bot em execução localmente em seu computador e acessível pela Web em um chat no Teams.

5. Uma etapa final a ser executada é atualizar o ponto de extremidade de mensagens do bot implantado. No exemplo, implantamos o bot no Azure. Portanto, vamos executar as seguintes etapas:

   1. No navegador, vá para o portal do Azure.
   2. Selecione seu Registro de Bots.
   3. No painel esquerdo, selecione Configurações.
   4. No painel direito, na caixa Ponto de extremidade de mensagens, digite o URL do ngrok: no nosso exemplo, https://dea822bf.ngrok.io/api/messages.

6. Inicie seu bot localmente, por exemplo, no modo de depuração do Visual Studio.

7. Teste o bot durante a execução local usando o Web chat de teste do portal do Bot Framework. Como ocorre com o Emulador, esse teste não permite que você acesse uma funcionalidade específica do Teams.

8. Na janela do terminal onde o ngrok está em execução, você pode ver o tráfego HTTP entre o bot e o cliente de web chat. Se quiser uma visualização mais detalhada, digite em uma janela do navegador o http://127.0.0.1:4040 que você obteve na janela anterior do terminal. A imagem a seguir é um exemplo:

   

Observação

Se você parar e reiniciar o ngrok, o URL será alterado. Para usar o ngrok no seu projeto e dependendo dos recursos que estiver usando, você precisará atualizar todas as referências de URL.

Informações adicionais

TeamsAppManifest/manifest.json

Este manifesto contém informações necessárias pelo Teams para se conectar com o bot:

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0.0",
  "id": "",
  "developer": {
    "name": "TeamsBotAuth",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.teams.com/privacy",
    "termsOfUseUrl": "https://www.teams.com/termsofuse"
  },
  "icons": {
    "color": "color.png",
    "outline": "outline.png"
  },
  "name": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "description": {
    "short": "TeamsBotAuth",
    "full": "Teams Bot Authentication"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "",
      "scopes": [
        "groupchat",
        "team"
      ],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [ "token.botframework.com" ]
}

Com a autenticação, o Teams se comporta um pouco diferente de outros canais.

Como lidar com a Atividade de Invocação

Uma Atividade de Invocação é enviada para o bot em vez da Atividade de Evento usada por outros canais, que é feita subclasse do ActivityHandler.

C#/.NET

Bots/DialogBot.cs

    public class DialogBot<T> : TeamsActivityHandler where T : Dialog
    {
        protected readonly BotState ConversationState;
        protected readonly Dialog Dialog;
        protected readonly ILogger Logger;
        protected readonly BotState UserState;

        public DialogBot(ConversationState conversationState, UserState userState, T dialog, ILogger<DialogBot<T>> logger)
        {
            ConversationState = conversationState;
            UserState = userState;
            Dialog = dialog;
            Logger = logger;
        }

        public override async Task OnTurnAsync(ITurnContext turnContext, CancellationToken cancellationToken = default(CancellationToken))
        {
            await base.OnTurnAsync(turnContext, cancellationToken);

            // Save any state changes that might have occurred during the turn.
            await ConversationState.SaveChangesAsync(turnContext, false, cancellationToken);
            await UserState.SaveChangesAsync(turnContext, false, cancellationToken);
        }

        protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
        {
            Logger.LogInformation("Running dialog with Message Activity.");

            // Run the Dialog with the new message Activity.
            await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
        }
    }
}

Bots/TeamsBot.cs

A Atividade de Invocaçãoprecisará ser encaminhada para a caixa de diálogo se o OAuthPrompt estiver sendo usado.

protected override async Task OnTeamsSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with signin/verifystate from an Invoke Activity.");

    // The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.

    // Run the Dialog with the new Invoke Activity.
    await Dialog.RunAsync(turnContext, ConversationState.CreateProperty<DialogState>(nameof(DialogState)), cancellationToken);
}

TeamsActivityHandler.cs

protected virtual Task OnInvokeActivityAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    switch (turnContext.Activity.Name)
    {
        case "signin/verifyState":
            return OnSigninVerifyStateAsync(turnContext, cancellationToken);

        default:
            return Task.CompletedTask;
    }
}

protected virtual Task OnSigninVerifyStateAsync(ITurnContext<IInvokeActivity> turnContext, CancellationToken cancellationToken)
{
    return Task.CompletedTask;
}

JavaScript

bots/dialogBot.js

const { TeamsActivityHandler } = require('botbuilder');
class DialogBot extends TeamsActivityHandler {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super();
        if (!conversationState) {
            throw new Error('[DialogBot]: Missing parameter. conversationState is required');
        }
        if (!userState) {
            throw new Error('[DialogBot]: Missing parameter. userState is required');
        }
        if (!dialog) {
            throw new Error('[DialogBot]: Missing parameter. dialog is required');
        }

        this.conversationState = conversationState;
        this.userState = userState;
        this.dialog = dialog;
        this.dialogState = this.conversationState.createProperty('DialogState');

        this.onMessage(async (context, next) => {
            console.log('Running dialog with Message Activity.');

            // Run the Dialog with the new message Activity.
            await this.dialog.run(context, this.dialogState);

            await next();
        });
    }

    /**
     * Override the ActivityHandler.run() method to save state changes after the bot logic completes.
     */
    async run(context) {
        await super.run(context);

        // Save any state changes. The load happened during the execution of the Dialog.
        await this.conversationState.saveChanges(context, false);

bots/teamsBot.js

A Atividade de Invocaçãoprecisará ser encaminhada para a caixa de diálogo se o OAuthPrompt estiver sendo usado.

const { DialogBot } = require('./dialogBot');

class TeamsBot extends DialogBot {
    /**
     *
     * @param {ConversationState} conversationState
     * @param {UserState} userState
     * @param {Dialog} dialog
     */
    constructor(conversationState, userState, dialog) {
        super(conversationState, userState, dialog);

        this.onMembersAdded(async (context, next) => {
            const membersAdded = context.activity.membersAdded;
            for (let cnt = 0; cnt < membersAdded.length; cnt++) {
                if (membersAdded[cnt].id !== context.activity.recipient.id) {
                    await context.sendActivity('Welcome to TeamsBot. Type anything to get logged in. Type \'logout\' to sign-out.');
                }
            }

            await next();
        });
    }
    
    async handleTeamsSigninVerifyState(context, query) {
        console.log('Running dialog with signin/verifystate from an Invoke Activity.');
        await this.dialog.run(context, this.dialogState);
    }

    async handleTeamsSigninTokenExchange(context, query) {

dialogs/mainDialog.js

Em uma etapa de diálogo, use beginDialog para iniciar o prompt OAuth, que solicita o login do usuário.

• Se o usuário já estiver conectado, ele gerará um evento de resposta de token, sem solicitar ao usuário.
• Caso contrário, ele solicita que o usuário entre. O Serviço de Bot do Azure envia o evento de resposta do token após a tentativa de login do usuário.

async promptStep(stepContext) {
    try {

Na etapa de diálogo a seguir, verifique a presença de um token no resultado da etapa anterior. Se não for nulo, o usuário entrará com êxito.

async promptStep(stepContext) {
    try {
        return await stepContext.beginDialog(OAUTH_PROMPT);
    } catch (err) {
        console.error(err);
    }
}

async loginStep(stepContext) {
    // Get the token from the previous step. Note that we could also have gotten the
    // token directly from the prompt itself. There is an example of this in the next method.
    const tokenResponse = stepContext.result;
    if (!tokenResponse || !tokenResponse.token) {
        await stepContext.context.sendActivity('Login was not successful please try again.');

caixas de diálogo/logoutDialog.js

async interrupt(innerDc) {
    if (innerDc.context.activity.type === ActivityTypes.Message) {
        const text = innerDc.context.activity.text.toLowerCase();
        if (text === 'logout') {
            const userTokenClient = innerDc.context.turnState.get(innerDc.context.adapter.UserTokenClientKey);

            const { activity } = innerDc.context;
            await userTokenClient.signOutUser(activity.from.id, this.connectionName, activity.channelId);

            await innerDc.context.sendActivity('You have been signed out.');
            return await innerDc.cancelAllDialogs();
        }

Python

bots/dialog_bot.py

def __init__(
    self,
    conversation_state: ConversationState,
    user_state: UserState,
    dialog: Dialog,
):
    if conversation_state is None:
        raise Exception(
            "[DialogBot]: Missing parameter. conversation_state is required"
        )
    if user_state is None:
        raise Exception("[DialogBot]: Missing parameter. user_state is required")
    if dialog is None:
        raise Exception("[DialogBot]: Missing parameter. dialog is required")

    self.conversation_state = conversation_state
    self.user_state = user_state
    self.dialog = dialog

async def on_turn(self, turn_context: TurnContext):
    await super().on_turn(turn_context)

    # Save any state changes that might have occurred during the turn.
    await self.conversation_state.save_changes(turn_context, False)
    await self.user_state.save_changes(turn_context, False)

async def on_message_activity(self, turn_context: TurnContext):
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

bots/teams_bot.py

A Atividade de Invocaçãoprecisará ser encaminhada para a caixa de diálogo se o OAuthPrompt estiver sendo usado.

async def on_teams_signin_verify_state(self, turn_context: TurnContext):
    # Run the Dialog with the new Token Response Event Activity.
    # The OAuth Prompt needs to see the Invoke Activity in order to complete the login process.
    await DialogHelper.run_dialog(
        self.dialog,
        turn_context,
        self.conversation_state.create_property("DialogState"),
    )

dialogs/main_dialog.py

Em uma etapa de diálogo, use begin_dialog para iniciar o prompt OAuth, que solicita o login do usuário.

• Se o usuário já estiver conectado, ele gerará um evento de resposta de token, sem solicitar ao usuário.
• Caso contrário, ele solicita que o usuário entre. O Serviço de Bot do Azure envia o evento de resposta do token após a tentativa de login do usuário.

async def prompt_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    return await step_context.begin_dialog(OAuthPrompt.__name__)

Na etapa de diálogo a seguir, verifique a presença de um token no resultado da etapa anterior. Se não for nulo, o usuário entrará com êxito.

async def login_step(self, step_context: WaterfallStepContext) -> DialogTurnResult:
    # Get the token from the previous step. Note that we could also have gotten the
    # token directly from the prompt itself. There is an example of this in the next method.
    if step_context.result:
        await step_context.context.send_activity("You are now logged in.")
        return await step_context.prompt(
            ConfirmPrompt.__name__,
            PromptOptions(
                prompt=MessageFactory.text("Would you like to view your token?")
            ),
        )

dialogs/logout_dialog.py

text = inner_dc.context.activity.text.lower()
if text == "logout":
    bot_adapter: BotFrameworkAdapter = inner_dc.context.adapter
    await bot_adapter.sign_out_user(inner_dc.context, self.connection_name)
    await inner_dc.context.send_activity("You have been signed out.")
    return await inner_dc.cancel_all_dialogs()

Exemplo de código

Esta seção fornece o exemplo de SDK do Bot authentication v3.

Nome de exemplo	Descrição	.NET	Node.js	Python	Manifesto
Autenticação de bot	Este exemplo mostra como começar a usar a autenticação em um bot para o Teams.	View	View	View	Exibir
SSO de Guia, Bot e Extensão de Mensagem (ME)	Este exemplo mostra Microsoft Entra SSO para Tab, Bot e ME – pesquisa, ação, desenrolamento de link.	View	View	NA	Exibir

Confira também

• Adicionar autenticação por meio do Serviço de Bot do Azure
• Obter acesso em nome de um usuário