Adicionar autenticação ao seu bot do Teams

Pode criar bots no Microsoft Teams que acedam a recursos em nome do utilizador, como um serviço de correio. Pode utilizar a autenticação do SDK V4 do Azure Bot Service, com base no OAuth 2.0. Este método facilita o desenvolvimento de um bot que pode utilizar tokens de autenticação com base nas credenciais do utilizador. A chave é a utilização de fornecedores de identidade.

O OAuth 2.0 é um padrão aberto para autenticação e autorização utilizado pelo Microsoft Entra ID e por muitos outros fornecedores 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. Utilize cs-auth-sample para processar credenciais de início de sessão do utilizador 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, veja Fluxo de autenticação do Microsoft Teams para bots.
• Como integrar o bot dentro do Microsoft Teams. Assim que o bot estiver integrado, pode iniciar sessão e trocar mensagens com o mesmo numa conversa.

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.

• As versões mais recentes do Microsoft Visual Studio e 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. Recomendamos que mantenha os seus recursos organizados e gerí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 pendente Região , selecione E.U.A. Oeste ou uma região próxima das suas aplicações.
   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á demorar alguns minutos a 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 quiser fazê-lo, selecione o ícone 📌 afixar 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 predefinido.
   7. Selecione o botão Rever e criar. Você deverá ver uma faixa com o texto Validação aprovada.
   8. Selecione Criar. Poderá demorar alguns minutos a criar o plano do serviço de aplicações. O plano está listado no grupo de recursos.

Criar um registro de recursos do Bot do Azure

O registo de recursos do Azure Bot regista o seu serviço Web como um bot com o Bot Framework, que lhe fornece um ID da Aplicação Microsoft e uma Palavra-passe da Aplicação (segredo do cliente).

Importante

Só tem de registar o bot se este não estiver alojado no Azure. Se criou um bot através do portal do Azure, este já está registado 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 aprovisiona o bot dentro de momentos.

   

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

   

   O 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. Junto a ID da Aplicação Microsoft, selecione Gerir.

   

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 a partir da secção Recursos recentes .

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

   

4. Selecione a caixa de verificaçã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

Precisa de um fornecedor de identidade para autenticação. Neste procedimento, vai utilizar um fornecedor do Microsoft Entra. Em alternativa, também pode utilizar outros fornecedores de identidade suportados pelo Microsoft Entra ID.

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

   Dica

   Tem de criar e registar este recurso do Microsoft Entra num inquilino no qual pode dar consentimento para delegar as permissões pedidas por uma aplicação. Para obter instruções sobre como criar um inquilino, veja Aceder ao portal e criar um inquilino.

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 inquilino do Microsoft Entra ID - Multi-inquilino) e contas Microsoft pessoais (por exemplo, Skype, Xbox).
   3. Para o URI de redirecionamento:
      ✓Selecione Web.
      ✓ Defina o URL como https://token.botframework.com/.auth/web/redirect.
   4. Selecione Registrar.

5. Depois de o Azure criar a aplicação, apresenta a página Descrição geral da aplicação. Copie e salve as seguintes informações em um arquivo:

   1. O valor ID do aplicativo (cliente). Utilize este valor mais tarde como O ID de Cliente quando registar esta aplicação de identidade do Azure no bot.
   2. O valor ID do diretório (locatário). Utilize este valor mais tarde como O ID do Inquilino quando registar esta aplicação de identidade do Azure no 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. Utilize este valor mais tarde como segredo do cliente quando registar a sua aplicação Microsoft Entra no bot.

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

Observação

Existem duas opções para Fornecedores de Serviços aqui: Azure Active Directory v1 e Azure Active Directory v2. As diferenças entre os dois fornecedores são resumidas aqui, mas, em geral, a v2 proporciona mais flexibilidade relativamente à 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 a v1, o consentimento do bot tem de ser eliminado pelo utilizador para que sejam pedidas novas permissões 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. Utilize este nome no bot no appsettings.json ficheiro. Por exemplo, BotTeamsAuthADv1.

   2. Provedor de serviços. Selecione Azure Active Directory. Depois de selecionar esta opção, os campos específicos do Azure Active Directory são apresentados.

   3. ID de cliente. Introduza o ID da Aplicação (cliente) que registou para a sua aplicação de fornecedor de identidade do Azure.

   4. Segredo do cliente. Introduza o segredo que registou para a sua aplicação de fornecedor 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 o valor a atribuir, siga estes critérios:

      • Se tiver selecionado Contas apenas neste diretório organizacional (apenas Microsoft - Inquilino único) ou Contas em qualquer diretório organizacional (Qualquer inquilino do Microsoft Entra ID - Multi-inquilino), introduza o ID de inquilino que registou anteriormente para a aplicação Microsoft Entra. Esse será o locatário associado aos usuários que podem ser autenticados.

      • Se selecionou Contas em qualquer diretório organizacional (Qualquer inquilino do Microsoft Entra ID - Multi-inquilino) e contas Microsoft pessoais (por exemplo, Skype, Xbox) introduza a palavra comum em vez de um ID de inquilino. Caso contrário, a aplicação Microsoft Entra verifica através do inquilino cujo ID foi selecionado e exclui contas Microsoft pessoais.

   h. Para o URL do recurso, digite https://graph.microsoft.com/. Este URL não é utilizado no exemplo de código.
   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. Utilize este nome no bot no appsettings.json ficheiro. Por exemplo, BotTeamsAuthADv2.

   2. Provedor de serviços. Selecione Azure Active Directory v2. Depois de selecionar esta opção, os campos específicos do Azure AD v2 são apresentados.

   3. ID de cliente. Introduza o ID da Aplicação (cliente) que registou para a sua aplicação de fornecedor de identidade do Azure.

   4. Segredo do cliente. Introduza o segredo que registou para a sua aplicação de fornecedor 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 o valor a atribuir, siga estes critérios:

      • Se tiver selecionado Contas apenas neste diretório organizacional (apenas Microsoft - Inquilino único) ou Contas em qualquer diretório organizacional (Qualquer inquilino do Microsoft Entra ID - Multi-inquilino), introduza o ID de inquilino que registou anteriormente para a aplicação Microsoft Entra. Esse será o locatário associado aos usuários que podem ser autenticados.

      • Se selecionou Contas em qualquer diretório organizacional (Qualquer inquilino do Microsoft Entra ID - Multi-inquilino) e contas Microsoft pessoais (por exemplo, Skype, Xbox) introduza a palavra comum em vez de um ID de inquilino. Caso contrário, a aplicação Microsoft Entra verifica através do inquilino cujo ID foi selecionado e exclui contas Microsoft pessoais.

   7. Para Âmbitos, introduza uma lista delimitada por espaço de permissões de grafos necessárias para esta aplicação, como User.Read, User.ReadBasic.All ou Mail.Read.

5. Selecione Salvar.

Testar a conexão

1. Selecione a entrada de ligação para abrir a ligação que 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, abre uma nova janela do browser a pedir-lhe para selecionar uma conta. Selecione a que você quer usar.

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

   

5. Selecione Aceitar.

6. É aberta uma página Testar Ligação ao <nome> da ligação com êxito . Atualize a página caso receba uma mensagem de erro. A imagem a seguir é um exemplo:

   

O código do bot utiliza o nome da ligação para obter tokens de autenticação de utilizador.

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 Abrir > Ficheiro > Projeto/Solução e abra o projeto de bot.

4. Em C#, Atualizar appsettings.json da seguinte forma:

   • 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.

   Consoante os carateres no segredo do bot, poderá ter de efetuar a fuga de XML da palavra-passe. Por exemplo, todos os e comercial (&) têm de ser codificados como &.

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

5. No Explorador de Soluções, aceda à TeamsAppManifest pasta, abra manifest.json e defina id e botId para o ID da Aplicação do bot que guardou no momento do registo do bot. Para obter mais informações, consulte o manifesto do aplicativo.

JavaScript

1. Clonar a node-auth-sample.

2. Numa consola, aceda ao 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. Consoante os carateres no segredo do bot, poderá ter de efetuar a fuga de XML da palavra-passe. Por exemplo, todos os e comercial (&) têm de 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. Na pasta, abra manifest.json e defina id para o teamsAppManifestID da Aplicação Microsoft e botId para o ID da Aplicação do bot que guardou no momento do registo do bot.

Python

1. Clone py-auth-sample do repositório do 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.

     Consoante os carateres no segredo do bot, poderá ter de efetuar a fuga de XML da palavra-passe. Por exemplo, todos os e comercial (&) têm de 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 implementar o bot, siga os passos em Como Implementar o bot no Azure.

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

1. No Explorador de Soluções do Visual Studio, selecione sem soltar (ou clique com o botão direito do rato) o nome do projeto.

2. No menu pendente, selecione Publicar.

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

4. Na janela da caixa de diálogo, selecione Serviço de Aplicações 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. É aberta uma página no seu browser predefinido com a mensagem O bot está pronto!. O URL é semelhante a https://botteamsauth.azurewebsites.net/. Salve-o em um arquivo.

9. No browser, aceda ao portal do Azure.

10. Verifique o grupo de recursos, o bot está listado juntamente 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 final de mensagens , introduza o URL que acabou de obter seguido de api/messages. Por exemplo, https://botteamsauth.azurewebsites.net/api/messages.

    Observação

    Só é permitido um ponto final de mensagens para um bot.

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

Testar o bot usando o Emulador

Instale o Microsoft Bot Framework Emulator. Para obter mais informações, veja Testar e depurar com o Emulador.

Para que o início de sessão de exemplo do bot funcione, tem de 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 o separador Definiçõ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, pode efetuar 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. No ID da Aplicação Microsoft, introduza o ID da aplicação do bot a partir de appsettings.json.

6. Na palavra-passe da Aplicação Microsoft, introduza a palavra-passe da aplicação do bot a appsettings.jsonpartir de .

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. É apresentada uma caixa de diálogo de pop-up para Confirmar URL aberto para autenticar o utilizador do bot (o utilizador).

11. Selecione Confirmar.

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

13. Consoante a configuração que utilizou para o Emulador, obtém uma das seguintes opções:

    1. Usar um código de verificação de login
       ✓ É aberta uma janela que apresenta o código de validação.
       ✓ Copie e introduza o código de validação na caixa de chat para concluir o início de sessão.
    2. Usar tokens de autenticação.
       ✓ Tem sessão iniciada com base nas suas credenciais.

    A imagem seguinte é um exemplo da IU do bot depois de iniciar sessão:

    

14. Se selecionar Sim quando o bot perguntar Gostaria de ver o token?, obtém a seguinte resposta:

    

15. Introduza logout na caixa de chat de entrada para terminar sessão. Liberta o token de utilizador e o bot não poderá agir em seu nome até iniciar sessão 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 browser, aceda ao 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. É apresentada uma caixa de diálogo de pop-up para Confirmar URL aberto para autenticar o utilizador do bot (o utilizador).

8. Selecione Confirmar.

9. Se solicitado, selecione a conta de usuário aplicável. A imagem seguinte é um exemplo da IU do bot depois de iniciar sessão:

   

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

    

11. Introduza logout na caixa de chat de entrada para terminar sessão.

    

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. No Explorador de Soluções, aceda à 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. Aceda à TeamsAppManifest pasta e carregue o manifesto zipado. É apresentada a seguinte janela:

   

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 Programador .

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 na cloud. Requer que todos os serviços a que acede estejam disponíveis a partir da cloud através de pontos finais 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 um URL endereçável externamente para uma porta que abre localmente no seu computador. Para configurar o ngrok em preparação para executar a sua aplicação Teams localmente, siga estes passos:

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. Inicia o ngrok para escutar na porta que especificar. 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 reencaminhamento semelhante a: https://dea822bf.ngrok.io/.

4. Acrescente /api/messages para obter https://dea822bf.ngrok.io/api/messages, que é o ponto final de mensagens para o bot em execução localmente no seu computador e acessível através da Web numa conversa 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 browser, aceda ao 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 para o Teams se ligar ao 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 comporta-se de forma diferente dos outros canais.

Como lidar com a Atividade de Invocação

Uma Atividade de Invocação é enviada para o bot em vez da Atividade de Eventos utilizada por outros canais, o que é feito ao subclassificar o 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 utilizador já tiver sessão iniciada, gera um evento de resposta de token, sem pedir ao utilizador.
• Caso contrário, pede ao utilizador para iniciar sessão. 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 utilizador iniciou sessão 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 utilizador já tiver sessão iniciada, gera um evento de resposta de token, sem pedir ao utilizador. Caso contrário, pede ao utilizador para iniciar sessão. 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 utilizador iniciou sessão 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 secção fornece o exemplo do SDK V3 de autenticação do bot.

Nome de exemplo	Descrição	.NET	Node.js	Python	Manifesto
Autenticação de bot	Este exemplo mostra como começar a utilizar a autenticação num bot para o Teams.	View	View	View	View
SSO de Tecla de Tabulação, Bot e Extensão de Mensagens (ME)	Este exemplo mostra o SSO do Microsoft Entra para Tab, Bot e ME – pesquisa, ação, desfraldamento de ligações.	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