Adicionar autenticação ao seu bot do Teams

Você pode criar bots no Microsoft Teams que acessam recursos em nome dos usuários (como um serviço de email) usando a autenticação do SDK do Teams baseada 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 pelo 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.

Neste artigo, você aprenderá:

• Como criar um bot habilitado para autenticação: Use cs-auth-sample para lidar com as credenciais de entrada 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 entrada do usuário. O bot pode usar o token para acessar recursos, como um serviço de email, que requer autenticação.
• Como integrar o bot no Microsoft Teams: Depois que o bot estiver integrado, você poderá entrar e trocar mensagens com ele em um chat.

Pré-requisitos

• Conhecimento dos conceitos básicos de bots e do SDK do Teams.

• 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
  Início Rápido de Autenticação de Bot em cs-auth-sample
  Início Rápido de Autenticação de Bot em js-auth-sample
  Início Rápido de Autenticação de Bot em py-auth-sample

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 você mantenha seus recursos organizados e gerenciáveis.

Você usa um grupo de recursos para criar recursos individuais para o bot. 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 poderia 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. Pode levar alguns minutos para criar o grupo de recursos.

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 poderia 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. Pode levar alguns minutos para criar o plano do serviço de aplicativo. O plano é listado no grupo de recursos.

Criar um registro de recursos do Bot do Azure

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

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 aplicativo como identidade gerenciada atribuída pelo usuário ou locatário único para a ID do aplicativo da Microsoft.

   Importante

   • O tipo de bot Multilocatário no Azure Serviço de Bot está preterido. Os bots multilocatários existentes continuam funcionando por enquanto.
   • Todos os novos registros de bot devem usar o tipo de bot de Locatário Único ou o tipo de Identidade Gerenciada Atribuída pelo Usuário .
   • Ao registrar seu aplicativo Entra no portal do Azure, você ainda pode selecionar a opção Contas em qualquer diretório organizacional (Multilocatário). Isso permite que o bot trabalhe em vários locatários, mesmo fora do locatário em que o aplicativo está registrado, ao usar um dos tipos de bot com suporte.
   • Em todos os casos, o TENANT_ID deve ser definido como a ID de locatário do locatário Azure onde o aplicativo Microsoft Entra ID está registrado.

   

7. Selecione Rever + criar.

   

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

   O Azure provisiona seu bot.

   

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. Ao lado de 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 é exibida.

   

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 seu bot na seção Recursos recentes .

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

   

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

   

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, use um provedor do Microsoft Entra. Como alternativa, você também pode usar outros provedores de identidade com suporte do Microsoft Entra ID.

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

   Dica

   Você deve criar e registrar esse recurso do Microsoft Entra em um locatário no qual você possa consentir em delegar permissões solicitadas por um aplicativo. Para obter instruções sobre como criar um locatário, consulte 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 poderia 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 do Microsoft Entra ID - multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox).
   3. Para o URI de redirecionamento:
      ✓Selecione Web.
      ✓ Defina o URL para https://token.botframework.com/.auth/web/redirect.
   4. Selecione Registrar.

5. Depois que o Azure cria o aplicativo, ele 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). Use esse valor posteriormente como a ID do Cliente ao registrar esse aplicativo de identidade do Azure com seu bot.
   2. O valor ID do diretório (locatário). Use esse valor posteriormente como a ID do locatário ao registrar esse 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. Use esse valor posteriormente como o segredo do cliente ao registrar seu aplicativo Microsoft Entra com seu bot.

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

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ê registrou para seu aplicativo de provedor de identidade do Azure.

   4. Segredo do cliente. Insira o segredo que você registrou para seu aplicativo de 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 somente neste diretório organizacional (somente Microsoft - locatário único) ou Contas em qualquer diretório organizacional (qualquer locatário do Microsoft Entra ID - Multilocatário), insira a ID de locatário registrada 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 do Microsoft Entra ID - multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox), insira a palavra comum em vez de uma ID de locatário. Caso contrário, o aplicativo Microsoft Entra verificará por meio do locatário cuja ID foi selecionada e excluirá contas pessoais da Microsoft.

   h. Para o URL do recurso, digite https://graph.microsoft.com/. Essa URL não é usada na amostra 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. Use esse nome no bot no appsettings.json arquivo. Por exemplo, BotTeamsAuthADv2.

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

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

   4. Segredo do cliente. Insira o segredo que você registrou para seu aplicativo de 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 somente neste diretório organizacional (somente Microsoft - locatário único) ou Contas em qualquer diretório organizacional (qualquer locatário do Microsoft Entra ID - Multilocatário), insira a ID de locatário registrada 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 do Microsoft Entra ID - multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox), insira a palavra comum em vez de uma ID de locatário. Caso contrário, o aplicativo Microsoft Entra verificará por meio do locatário cuja ID foi selecionada e excluirá contas pessoais da Microsoft.

   7. Em Escopos, insira uma lista limitada 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 para 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.

Implantar o bot no Azure

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

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

1. No Gerenciador de Soluções do Visual Studio, selecione e segure (ou clique com o botão direito do mouse) o 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 o Serviço de Aplicativo e Criar Novo.

5. Selecionar 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 em seu 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, acesse 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 de 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.

Teste localmente usando o Microsoft 365 Agents Playground

Para testar seu bot localmente, use o Microsoft 365 Agents Playground, que oferece suporte a agentes e bots.
Para obter instruções de configuração e teste, consulte Teste seu agente localmente com o Microsoft 365 Agents Playground.

Testar o bot implantado

1. No navegador, acesse 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 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 do usuário do bot depois de entrar:

   

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

    

11. Digite logout na caixa de chat de entrada para sair.

    

Instalar e testar o bot no Teams

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

2. No Gerenciador de Soluções, vá para a appPackage 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 appPackage pasta e carregue o manifesto compactado.

8. Selecione Adicionar para instalar o aplicativo no Teams.

   

9. Pesquise e selecione o escopo necessário ou selecione um canal ou chat na lista e mova a caixa de diálogo para selecionar Ir.

   

   Observação

   O OAuth não tem suporte diretamente nos escopos de chat ou canal de grupo. Se você habilitar a autenticação e os usuários instalarem seu bot em chats ou canais em grupo, eles deverão se autenticar em seus escopos pessoais antes de poderem usar o bot no chat ou canal em grupo.

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

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

12. 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. Ele 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 no computador. Para configurar o ngrok em preparação para executar seu aplicativo 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 escutar na porta que você 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 encaminhamento semelhante a: https://dea822bf.ngrok.io/.

4. Acrescentar /api/messages a obtain https://dea822bf.ngrok.io/api/messages, que é o ponto de extremidade de mensagens para o bot em execução localmente no 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, acesse 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 Teste no Webchat do portal do Azure.

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:

   

Informações adicionais

appPackage/manifest.json

Este manifesto contém informações necessárias para que o Teams se conecte ao bot:

{ 

  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.22/MicrosoftTeams.schema.json", 

  "manifestVersion": "1.22", 

  "version": "1.0.0", 

  "id": "${{TEAMS_APP_ID}}", 

  "developer": { 

    "name": "Teams App, Inc.", 

    "websiteUrl": "https://example.azurewebsites.net", 

    "privacyUrl": "https://example.azurewebsites.net/privacy", 

    "termsOfUseUrl": "https://example.azurewebsites.net/termsofuse" 

  }, 

  "icons": { 

    "color": "color.png", 

    "outline": "outline.png" 

  }, 

  "name": { 

    "short": "Auth Bot", 

    "full": "Auth Bot" 

  }, 

  "description": { 

    "short": "Teams bot with SSO authentication and Graph API integration.", 

    "full": "This bot demonstrates SSO authentication in Microsoft Teams using Azure AD, and uses Microsoft Graph API to retrieve the user profile." 

  }, 

  "accentColor": "#FFFFFF", 

  "bots": [ 

    { 

      "botId": "${{BOT_ID}}", 

      "scopes": [ 

        "personal", 

        "groupChat", 

        "team" 

      ], 

      "supportsFiles": false, 

      "isNotificationOnly": false 

    } 

  ], 

  "permissions": [ 

    "identity", 

    "messageTeamMembers" 

  ], 

  "validDomains": [ 

    "token.botframework.com", 

    "${{BOT_DOMAIN}}" 

  ], 

  "webApplicationInfo": { 

    "id": "${{BOT_ID}}", 

    "resource": "api://botid-${{BOT_ID}}" 

  } 

} 

Com a autenticação, o Teams se comporta de forma diferente dos outros canais.

Exemplo de código

Este exemplo demonstra como implementar a autenticação de SSO (Sign-On Único) para bots do Microsoft Teams usando o Azure Active Directory.

Confira também

• Obter acesso em nome de um usuário