Adicionar autenticação ao bot do Microsoft TeamsAdd authentication to your Teams bot

Há ocasiões em que você pode precisar criar bots no Microsoft Teams que podem acessar recursos em nome do usuário, como um serviço de email.There are times when you may need to create bots in Microsoft Teams that can access resources on behalf of the user, such as a mail service.

Este artigo demonstra como usar a autenticação do SDK do Azure bot Service v4, com base no OAuth 2,0.This article demonstrates how to use Azure Bot Service v4 SDK authentication, based on OAuth 2.0. Isso facilita o desenvolvimento de um bot que pode usar tokens de autenticação com base nas credenciais do usuário.This makes it easier to develop a bot that can use authentication tokens based on the user's credentials. A chave é o uso de provedores de identidade, como veremos mais tarde.Key in all this is the use of identity providers, as we will see later.

O OAuth 2,0 é um padrão aberto para autenticação e autorização usados pelo Azure Active Directory (Azure AD) e muitos outros provedores de identidade.OAuth 2.0 is an open standard for authentication and authorization used by Azure Active Directory (Azure AD) and many other identity providers. Uma compreensão básica do OAuth 2,0 é um pré-requisito para trabalhar com autenticação no Microsoft Teams.A basic understanding of OAuth 2.0 is a prerequisite for working with authentication in Teams.

Consulte OAuth 2 simplificado para obter uma compreensão básica e o OAuth 2,0 para a especificação completa.See OAuth 2 Simplified for a basic understanding, and OAuth 2.0 for the complete specification.

Para obter mais informações sobre como o serviço de bot do Azure trata a autenticação, confira autenticação do usuário em uma conversa.For more information about how the Azure Bot Service handles authentication, see User authentication within a conversation.

Neste artigo, você aprenderá:In this article you'll learn:

  • Como criar um bot habilitado para autenticação.How to create an authentication-enabled bot. Você usará o cs-auth-Sample para lidar com as credenciais de entrada do usuário e a geração do token de autenticação.You'll use cs-auth-sample to handle user sign-in credentials and the generating the authentication token.
  • Como implantar o bot no Azure e associá-lo a um provedor de identidade.How to deploy the bot to Azure and associate it with an identity provider. O provedor emite um token com base nas credenciais de entrada do usuário.The provider issues a token based on user sign-in credentials. O bot pode usar o token para acessar recursos, como um serviço de email, que requer autenticação.The bot can use the token to access resources, such as a mail service, which require authentication. Para obter mais informações, consulte Microsoft Teams Authentication Flow for bots.For more information see Microsoft Teams authentication flow for bots.
  • Como integrar o bot no Microsoft Teams.How to integrate the bot within Microsoft Teams. Após a integração do bot, você poderá entrar e trocar mensagens com ela em um chat.Once the bot has been integrated, you can sign in and exchange messages with it in a chat.

Pré-requisitosPrerequisites

Criar o grupo de recursosCreate the resource group

O grupo de recursos e o plano de serviço não são estritamente necessários, mas permitem que você libere convenientemente os recursos que você criou.The resource group and the service plan aren't strictly necessary, but they allow you to conveniently release the resources you create. Essa é uma boa prática para manter seus recursos organizados e gerenciáveis.This is good practice for keeping your resources organized and manageable.

Você usa um grupo de recursos para criar recursos individuais para a estrutura de bot.You use a resource group to create individual resources for the Bot Framework. Para desempenho, verifique se esses recursos estão localizados na mesma região do Azure.For performance, ensure that these resources are located in the same Azure region.

  1. No seu navegador, entre no portal do Azure.In your browser, sign into the Azure portal.
  2. No painel de navegação esquerdo, selecione grupos de recursos.In the left navigation panel, select Resource groups.
  3. Na parte superior esquerda da janela exibida, selecione a guia Adicionar para criar um novo grupo de recursos.In the upper left of the displayed window, select Add tab to create a new resource group. Você será solicitado a fornecer o seguinte:You'll be prompted to provide the following:
    1. Assinatura.Subscription. Use sua assinatura existente.Use your existing subscription.
    2. Grupo de recursos.Resource group. Insira o nome do grupo de recursos.Enter the name for the resource group. Um exemplo poderia ser TeamsResourceGroup.An example could be TeamsResourceGroup. Lembre-se de que o nome deve ser exclusivo.Remember that the name must be unique.
    3. No menu suspenso região , selecione oeste dos EUAou uma região perto de seus aplicativos.From the Region drop-down menu, select West US, or a region close to your applications.
    4. Selecione o botão revisar e criar .Select the Review and create button. Você verá uma faixa que lê a validação aprovada.You should see a banner that reads Validation passed.
    5. Selecione o botão criar .Select the Create button. Pode levar alguns minutos para criar o grupo de recursos.It may take a few minutes to create the resource group.

Dica

Da mesma forma que os recursos que você criará posteriormente neste tutorial, é uma boa ideia fixar esse grupo de recursos no painel para facilitar o acesso.As with the resources you'll create later in this tutorial, it's a good idea to pin this resource group to your dashboard for easy access. Se quiser fazer isso, selecione o ícone de PIN & # 128204; no canto superior direito do painel.If you'd like to do so, select the pin icon 📌 in the upper right of the dashboard.

Criar o plano de serviçoCreate the service plan

  1. No portal do Azure, no painel de navegação à esquerda, selecione criar um recurso.In the Azure portal, on the left navigation panel, select Create a resource.
  2. Na caixa de pesquisa, digite plano de serviço de aplicativo.In the search box, type App Service Plan. Selecione o cartão de plano do serviço de aplicativo nos resultados da pesquisa.Select the App Service Plan card from the search results.
  3. Selecione Criar.Select Create.
  4. Você será solicitado a fornecer as seguintes informações:You'll be asked to provide the following information:
    1. Assinatura.Subscription. Você pode usar uma assinatura existente.You can use an existing subscription.
    2. Grupo de recursos.Resource Group. Selecione o grupo que você criou anteriormente.Select the group you created earlier.
    3. Nome.Name. Insira o nome do plano de serviço.Enter the name for the service plan. Um exemplo poderia ser TeamsServicePlan.An example could be TeamsServicePlan. Lembre-se de que o nome deve ser exclusivo no grupo.Remember that the name must be unique, within the group.
    4. Sistema operacional.Operating System. Selecione Windows ou seu sistema operacional aplicável.Select Windows or your applicable OS.
    5. Região.Region. Selecione oeste dos EUA ou uma região perto de seus aplicativos.Select West US or a region close to your applications.
    6. Camada de preços.Pricing Tier. Verifique se S1 padrão está selecionado.Make sure that Standard S1 is selected. Este deve ser o valor padrão.This should be the default value.
    7. Selecione o botão revisar e criar .Select the Review and create button. Você verá uma faixa que lê a validação aprovada.You should see a banner that reads Validation passed.
    8. Selecione Criar.Select Create. Pode levar alguns minutos para criar o plano de serviço de aplicativo.It may take a few minutes to create the app service plan. O plano será listado no grupo de recursos.The plan will be listed in the resource group.

Criar o registro de canais de botCreate the bot channels registration

O registro de canais de bot registra seu serviço Web como um bot com a estrutura de bot, desde que você tenha uma ID de aplicativo da Microsoft e uma senha de aplicativo (segredo do cliente).The bot channels registration registers your web service as a bot with the Bot Framework, provided you have a Microsoft App Id and App password (client secret).

Importante

Você só precisa registrar seu bot se ele não estiver hospedado no Azure.You only need to register your bot if it is not hosted in Azure. Se você criou um bot por meio do portal do Azure, ele já está registrado com o serviço.If you created a bot through the Azure portal then it is already registered with the service. Se você criou o bot por meio da estrutura de bot ou AppStudio seu bot não está registrado no Azure.If you created your bot through the Bot Framework or AppStudio your bot isn't registered in Azure.

  1. No portal do Azure, em serviços do Azure, selecione criar um recurso.In the Azure portal, under Azure services, select Create a resource.

  2. Na caixa de pesquisa, digite "bot".In the search box enter "bot". E, na lista suspensa, selecione o registro de canais de bot.And in the drop-down list, select Bot Channels Registration.

  3. Selecione o botão criar .Select the Create button.

  4. Na lâmina de registro do canal do bot , forneça as informações solicitadas sobre o bot.In the Bot Channel Registration blade, provide the requested information about your bot.

  5. Deixe a caixa de ponto de extremidade de mensagens vazia por enquanto, você inserirá a URL necessária após a implantação do bot.Leave the Messaging endpoint box empty for now, you will enter the required URL after deploying the bot. A imagem a seguir mostra um exemplo das configurações de registro:The following picture shows an example of the registration settings:

    registro de canais de aplicativos bot

  6. Clique em ID e senha do aplicativo Microsoft e crie novo.Click Microsoft App ID and password and then Create New.

  7. Clique em criar ID do aplicativo no link do portal de registro do aplicativo .Click Create App ID in the App Registration Portal link.

  8. Na janela de registro de aplicativo exibido, clique na guia novo registro no canto superior esquerdo.In the displayed App registration window, click the New registration tab in the upper left.

  9. Insira o nome do aplicativo bot que você está registrando, usamos BotTeamsAuth (você precisa selecionar seu próprio nome exclusivo).Enter the name of the bot application you are registering, we used BotTeamsAuth (you need to select your own unique name).

  10. Para os tipos de conta com suporte , selecione contas em qualquer diretório organizacional (qualquer diretório do Azure ad-multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox).For the Supported account types select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).

  11. Clique no botão registrar .Click the Register button. Depois de concluído, o Azure exibe a página visão geral do aplicativo.Once completed, Azure displays the Overview page for the application.

  12. Copie e salve em um arquivo o valor de ID do aplicativo (cliente) .Copy and save to a file the Application (client) ID value.

  13. No painel esquerdo, clique em certificado e segredos.In the left panel, click Certificate and secrets.

    1. Em segredos do cliente, clique em novo segredo do cliente.Under Client secrets, click New client secret.
    2. Adicione uma descrição para identificar esse segredo de outras pessoas que você talvez precise criar para este aplicativo.Add a description to identify this secret from others you might need to create for this app.
    3. Definir expira para sua seleção.Set Expires to your selection.
    4. Clique em Adicionar.Click Add.
    5. Copie o segredo do cliente e salve-o em um arquivo.Copy the client secret and save it to a file.
  14. Volte para a janela de registro do canal do bot e copie a ID do aplicativo e o segredo do cliente nas caixas ID do aplicativo da Microsoft e senha , respectivamente.Go back to the Bot Channel Registration window and copy the App ID and the Client secret in the Microsoft App ID and Password boxes, respectively.

  15. Clique em OK.Click OK.

  16. Por fim, clique em criar.Finally, click Create.

Após o Azure ter criado o recurso de registro, ele será incluído na lista grupo de recursos.After Azure has created the registration resource it will be included in the resource group list.

grupo de registro de canais de aplicativos bot

Depois que o registro dos canais de bot for criado, você precisará habilitar o canal do teams.Once your bot channels registration is created, you'll need to enable the Teams channel.

  1. No portal do Azure, em serviços do Azure, selecione o registro do canal de bot que você acabou de criar.In the Azure portal, under Azure services, select the Bot Channel Registration you just created.
  2. No painel esquerdo, clique em canais.In the left panel, click Channels.
  3. Clique no ícone do Microsoft Teams e escolha salvar.Click the Microsoft Teams icon, then choose Save.

Observação

O recurso de registro de canais de bot mostrará a região global , mesmo se você selecionar oeste dos EUA.The Bot Channels Registration resource will show the Global region even if you selected West US. Isso é esperado.This is expected.

Para obter mais informações, consulte Create a bot for Teams.For more information, see Create a bot for Teams.

Criar o provedor de identidadeCreate the identity provider

Você precisa de um provedor de identidade que possa ser usado para autenticação.You need an identity provider that can be used for authentication. Neste procedimento, você usará um provedor do Azure AD; outros provedores de identidade compatíveis com o Azure AD também podem ser usados.In this procedure you'll use an Azure AD provider; other Azure AD supported identity providers can also be used.

  1. No portal do Azure, no painel de navegação à esquerda, selecione Azure Active Directory.In the Azure portal, on the left navigation panel, select Azure Active Directory.

    Dica

    Você precisará criar e registrar esse recurso do Azure AD em um locatário no qual você pode concordar em delegar permissões solicitadas por um aplicativo.You'll need to create and register this Azure AD resource in a tenant in which you can consent to delegate permissions requested by an application. Para obter instruções sobre como criar um locatário, confira acessar o portal e criar um locatário.For instruction on creating a tenant, see Access the portal and create a tenant.

  2. No painel esquerdo, selecione registros de aplicativo.In the left panel, select App registrations.

  3. No painel direito, selecione a guia novo registro , no canto superior esquerdo.In the right panel, select the New registration tab, in the upper left.

  4. Você será solicitado a fornecer as seguintes informações:You'll be asked to provide the following information:

    1. Nome.Name. Insira o nome do aplicativo.Enter the name for the application. Um exemplo poderia ser BotTeamsIdentity.An example could be BotTeamsIdentity. Lembre-se de que o nome deve ser exclusivo.Remember that the name must be unique.
    2. Selecione os tipos de conta com suporte para o seu aplicativo.Select the Supported account types for your application. Selecione contas em qualquer diretório organizacional (qualquer diretório do Azure ad-multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox).Select Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox).
    3. Para o URI de redirecionamento:For the Redirect URI:
      ✓selecione Web.✓Select Web.
      ✓ definir a URL como https://token.botframework.com/.auth/web/redirect .✓ Set the URL to https://token.botframework.com/.auth/web/redirect.
    4. Selecione Registrar.Select Register.
  5. Depois que ele for criado, o Azure exibirá a página visão geral do aplicativo.Once it is created, Azure displays the Overview page for the app. Copie e salve as seguintes informações em um arquivo:Copy and save the following information to a file:

    1. O valor da ID do aplicativo (cliente) .The Application (client) ID value. Você usará esse valor mais tarde como a ID do cliente ao registrar esse aplicativo de identidade do Azure no bot.You'll use this value later as the Client ID when you register this Azure identity application with your bot.
    2. O valor da ID do diretório (locatário) .The Directory (tenant) ID value. Você também usará esse valor mais tarde como a ID de locatário para registrar esse aplicativo de identidade do Azure no bot.You'll also use this value later as the Tenant ID to register this Azure identity application with your bot.
  6. No painel esquerdo, selecione certificados & segredos para criar um segredo do cliente para seu aplicativo.In the left panel, select Certificates & secrets to create a client secret for your application.

    1. Em segredos do cliente, selecione ➕ novo segredo do cliente.Under Client secrets, select ➕ New client secret.
    2. Adicione uma descrição para identificar esse segredo de outras pessoas que você talvez precise criar para esse aplicativo, como o aplicativo de identidade de bot no Microsoft Teams.Add a description to identify this secret from others you might need to create for this app, such as Bot identity app in Teams.
    3. Definir expira para sua seleção.Set Expires to your selection.
    4. Clique em Adicionar.Select Add.
    5. Antes de sair desta página, Registre o segredo.Before leaving this page, record the secret. Você usará esse valor mais tarde como o segredo do cliente quando registrar seu aplicativo do Azure AD com o bot.You'll use this value later as the Client secret when you register your Azure AD application with your bot.

Configurar a conexão do provedor de identidade e registrá-la com o botConfigure the identity provider connection and register it with the bot

Observação: há duas opções para os provedores de serviços aqui-Azure AD v1 e Azure AD v2.Note-there are two options for Service Providers here-Azure AD V1 and Azure AD V2. As diferenças entre os dois provedores são resumidas aqui, mas em geral, o v2 fornece mais flexibilidade com relação à alteração das permissões de bot.The differences between the two providers are summarized here, but in general, V2 provides more flexibility with respect to changing bot permissions. As permissões de API do Graph estão listadas no campo escopos, e à medida que novas são adicionadas, os bots permitirão que os usuários concordem nas novas permissões na próxima entrada.Graph API permissions are listed in the scopes field, and as new ones are added, bots will allow users to consent to the new permissions on the next sign in. Para o v1, o consentimento de bot deve ser excluído pelo usuário para novas permissões a serem solicitadas na caixa de diálogo do OAuth.For V1, the bot consent must be deleted by the user for new permissions to be prompted in the OAuth dialog.

Azure AD v1Azure AD V1

  1. No portal do Azure, selecione o grupo de recursos no painel.In the Azure portal, select your resource group from the dashboard.

  2. Selecione o link de registro do canal do bot.Select your bot channel registration link.

  3. Na página recurso, selecione configurações.On the resource page, select Settings.

  4. Em configurações de conexão OAuth próximo à parte inferior da página, selecione Adicionar configuração.Under OAuth Connection Settings near the bottom of the page, select Add Setting.

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

    1. Nome.Name. Insira um nome para a conexão.Enter a name for the connection. Você usará esse nome no bot no appsettings.json arquivo.You'll use this name in your bot in the appsettings.json file. Por exemplo BotTeamsAuthADv1.For example BotTeamsAuthADv1.

    2. Provedor de serviços.Service Provider. Selecione Azure Active Directory.Select Azure Active Directory. Depois que você selecionar isso, os campos específicos do Azure AD serão exibidos.Once you select this, the Azure AD-specific fields will be displayed.

    3. ID do cliente. Insira a ID do aplicativo (cliente) que você registrou para seu aplicativo do provedor de identidade do Azure nas etapas acima.Client id. Enter the Application (client) ID that you recorded for your Azure identity provider app in the steps above.

    4. Segredo do cliente.Client secret. Insira o segredo que você gravou para seu aplicativo do provedor de identidade do Azure nas etapas acima.Enter the secret that you recorded for your Azure identity provider app in the steps above.

    5. Tipo de concessão.Grant Type. Inserir authorization_code .Enter authorization_code.

    6. URL de logon.Login URL. Inserir https://login.microsoftonline.com .Enter https://login.microsoftonline.com.

    7. ID do locatário, digite a ID do diretório (locatário) registrada anteriormente para 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.Tenant ID, enter the Directory (tenant) ID that you recorded earlier for your Azure identity app or common depending on the supported account type selected when you created the identity provider app. Para decidir qual o valor a ser atribuído siga estes critérios:To decide which value to assign follow these criteria:

      • Se você selecionou contas nesse diretório organizacional apenas (Microsoft somente um locatário) ou contas em qualquer diretório organizacional (Microsoft AAD Directory-multilocatário) , insira a ID do locatário que você gravou anteriormente para o aplicativo AAD.If you selected either Accounts in this organizational directory only (Microsoft only - Single tenant) or Accounts in any organizational directory(Microsoft AAD directory - Multi tenant) enter the tenant ID you recorded earlier for the AAD app. Este será o locatário associado aos usuários que podem ser autenticados.This will be the tenant associated with the users who can be authenticated.

      • Se você selecionou contas em qualquer diretório organizacional (qualquer usuário do AAD-multilocatário e contas pessoais da Microsoft, por exemplo, Skype, Xbox, Outlook) , insira a palavra comum em vez de uma ID de locatário.If you selected Accounts in any organizational directory (Any AAD directory - Multi tenant and personal Microsoft accounts e.g. Skype, Xbox, Outlook) enter the word common instead of a tenant ID. Caso contrário, o aplicativo AAD verificará o locatário cuja ID foi selecionada e excluirá contas pessoais da Microsoft.Otherwise, the AAD app will verify through the tenant whose ID was selected and exclude personal Microsoft accounts.

    0.h. Para URL de recurso, insira https://graph.microsoft.com/ .For Resource URL, enter https://graph.microsoft.com/. Isso não é usado no exemplo de código atual.This is not used in the current code sample.
    i.i. Deixe escopos em branco.Leave Scopes blank. A imagem a seguir é um exemplo:The following image is an example:

    visão Adv1 da cadeia de conexão do App bots do Team

  6. Clique em Salvar.Select Save.

Azure AD v2Azure AD V2

  1. No portal do Azure, selecione o grupo de recursos no painel.In the Azure portal, select your resource group from the dashboard.

  2. Selecione o link de registro do canal do bot.Select your bot channel registration link.

  3. Na página recurso, selecione configurações.On the resource page, select Settings.

  4. Em configurações de conexão OAuth próximo à parte inferior da página, selecione Adicionar configuração.Under OAuth Connection Settings near the bottom of the page, select Add Setting.

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

    1. Nome.Name. Insira um nome para a conexão.Enter a name for the connection. Você usará esse nome no bot no appsettings.json arquivo.You'll use this name in your bot in the appsettings.json file. Por exemplo BotTeamsAuthADv2.For example BotTeamsAuthADv2.

    2. Provedor de serviços.Service Provider. Selecione Azure Active Directory v2.Select Azure Active Directory v2. Depois que você selecionar isso, os campos específicos do Azure AD serão exibidos.Once you select this, the Azure AD-specific fields will be displayed.

    3. ID do cliente. Insira a ID do aplicativo (cliente) que você registrou para seu aplicativo do provedor de identidade do Azure nas etapas acima.Client id. Enter the Application (client) ID that you recorded for your Azure identity provider app in the steps above.

    4. Segredo do cliente.Client secret. Insira o segredo que você gravou para seu aplicativo do provedor de identidade do Azure nas etapas acima.Enter the secret that you recorded for your Azure identity provider app in the steps above.

    5. URL do token do Exchange.Token Exchange URL. Deixe em branco.Leave this blank.

    6. ID do locatário, digite a ID do diretório (locatário) registrada anteriormente para 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.Tenant ID, enter the Directory (tenant) ID that you recorded earlier for your Azure identity app or common depending on the supported account type selected when you created the identity provider app. Para decidir qual o valor a ser atribuído siga estes critérios:To decide which value to assign follow these criteria:

      • Se você selecionou contas nesse diretório organizacional apenas (Microsoft somente um locatário) ou contas em qualquer diretório organizacional (Microsoft AAD Directory-multilocatário) , insira a ID do locatário que você gravou anteriormente para o aplicativo AAD.If you selected either Accounts in this organizational directory only (Microsoft only - Single tenant) or Accounts in any organizational directory(Microsoft AAD directory - Multi tenant) enter the tenant ID you recorded earlier for the AAD app. Este será o locatário associado aos usuários que podem ser autenticados.This will be the tenant associated with the users who can be authenticated.

      • Se você selecionou contas em qualquer diretório organizacional (qualquer usuário do AAD-multilocatário e contas pessoais da Microsoft, por exemplo, Skype, Xbox, Outlook) , insira a palavra comum em vez de uma ID de locatário.If you selected Accounts in any organizational directory (Any AAD directory - Multi tenant and personal Microsoft accounts e.g. Skype, Xbox, Outlook) enter the word common instead of a tenant ID. Caso contrário, o aplicativo AAD verificará o locatário cuja ID foi selecionada e excluirá contas pessoais da Microsoft.Otherwise, the AAD app will verify through the tenant whose ID was selected and exclude personal Microsoft accounts.

    7. Para escopos, insira uma lista delimitada por espaço de permissões de gráfico que esse aplicativo requer por exemplo: user. Read User. ReadBasic. All mail. ReadFor Scopes, enter a space-delimited list of graph permissions this application requires e.g.: User.Read User.ReadBasic.All Mail.Read

  6. Clique em Salvar.Select Save.

Testar a conexãoTest the connection

  1. Selecione a entrada de conexão para abrir a conexão que você acabou de criar.Select the connection entry to open the connection you just created.

  2. Selecione testar conexão na parte superior do painel configuração de conexão do provedor de serviços .Select Test Connection at the top of the Service Provider Connection Setting panel.

  3. Na primeira vez que você fizer isso, abrirá uma nova janela do navegador solicitando que você selecione uma conta.The first time you do this will open a new browser window asking you to select an account. Selecione aquele que você deseja usar.Select the one you want to use.

  4. Em seguida, você será solicitado a permitir que o provedor de identidade use seus dados (credenciais).Next, you'll be asked to allow to the identity provider to use your data (credentials). A imagem a seguir é um exemplo:The following image is an example:

    Cadeia de conexão de autenticação de Adv1 de bot de equipes

  5. Selecione aceitar.Select Accept.

  6. Isso deve ser redirecionado para uma conexão de teste para uma página com <your-connection-name> êxito .This should then redirect you to a Test Connection to <your-connection-name> Succeeded page. Atualize a página se você receber um erro.Refresh the page if you get an error. A imagem a seguir é um exemplo:The following image is an example:

Adv1 de Seq de conexão do aplicativo de bots do Microsoft Teams

O nome da conexão é usado pelo código do bot para recuperar os tokens de autenticação do usuário.The connection name is used by the bot code to retrieve user authentication tokens.

Preparar o código de exemplo de botPrepare the bot sample code

Com as configurações preliminares concluídas, vamos nos concentrar na criação do bot a ser usado neste artigo.With the preliminary settings done, let's focus on the creation of the bot to use in this article.

  1. Clone cs-auth-Sample.Clone cs-auth-sample.

  2. Inicie o Visual Studio.Launch Visual Studio.

  3. Na barra de ferramentas , selecione Arquivo-> Open-> Project/Solution e abra o projeto bot.From the toolbar select File -> Open -> Project/Solution and open the bot project.

  4. Naappsettings.jsde atualização C# ** da** seguinte maneira:In C# Update appsettings.json as follows:

    • Defina ConnectionName como o nome da conexão do provedor de identidade que você adicionou ao registro do canal de bot.Set ConnectionName to the name of the identity provider connection you added to the bot channel registration. O nome usado neste exemplo é BotTeamsAuthADv1.The name we used in this example is BotTeamsAuthADv1.
    • Defina MicrosoftAppId como a ID do aplicativo bot que você salvou no momento do registro do canal de bot.Set MicrosoftAppId to the bot App ID you saved at the time of the bot channel registration.
    • Defina MicrosoftAppPassword como o segredo do cliente que você salvou no momento do registro do canal do bot.Set MicrosoftAppPassword to the customer secret you saved at the time of the bot channel registration.
    • Defina o ConnectionName como o nome da conexão do provedor de identidade.Set the ConnectionName to the name of the identity provider connection.

    Dependendo dos caracteres no seu segredo de bot, talvez seja necessário escapar da senha por XML.Depending on the characters in your bot secret, you may need to XML escape the password. Por exemplo, qualquer e comercial (&) precisará ser codificado como &amp; .For example, any ampersands (&) will need to be encoded as &amp;.

    {
      "MicrosoftAppId": "",
      "MicrosoftAppPassword": "",
      "ConnectionName": ""
    }
    
  5. No Gerenciador de soluções, navegue até a TeamsAppManifest pasta, abra manifest.json e defina id e botId para o ID do aplicativo bot que você salvou no momento do registro do canal de bot.In the Solution Explorer, navigate to the TeamsAppManifest folder, open manifest.json and set id and botId to the bot App ID you saved at the time of the bot channel registration.

Implantar o bot no AzureDeploy the bot to Azure

Para implantar o bot, siga as etapas descritas em como implantar seu bot no Azure.To deploy the bot, follow the steps in the how to Deploy your bot to Azure.

Como alternativa, enquanto no Visual Studio, você pode seguir estas etapas:Alternatively, while in Visual Studio, you can follow these steps:

  1. No Visual Studio Solution Explorer , selecione e segure (ou clique com o botão direito do mouse) o nome do projeto.In Visual Studio Solution Explorer select and hold (or right-click) the project name.

  2. No menu suspenso, selecione publicar.In the drop-down menu, select Publish.

  3. Na janela exibida, selecione o novo link.In the displayed window, select the New link.

  4. Na janela de diálogo, selecione serviço de aplicativo à esquerda e crie novo à direita.In the dialog window, select App Service on the left and Create New on the right.

  5. Selecione o botão publicar .Select the Publish button.

  6. Na próxima janela de diálogo, insira as informações necessárias.In the next dialog window, enter the required information. Este é um exemplo:The following is an example:

    auth-app-Service

  7. Selecione Criar.Select Create.

  8. Se a implantação for concluída com êxito, você deverá vê-la refletida no Visual Studio.If the deployment completes successfully, you should see it reflected in Visual Studio. Além disso, uma página é exibida no navegador padrão dizendo que o bot está pronto!.Moreover, a page is displayed in your default browser saying Your bot is ready!. A URL será semelhante a esta: https://botteamsauth.azurewebsites.net/ .The URL will be similar to this: https://botteamsauth.azurewebsites.net/. Salve-o em um arquivo.Save it to a file.

  9. No navegador, navegue até o portal do Azure.In your browser, navigate to the Azure portal.

  10. Verifique o grupo de recursos, o bot deve ser listado junto com os outros recursos.Check your resource group, the bot should be listed along with the other resources. A imagem a seguir é um exemplo:The following image is an example:

    Teams-bot-auth-app-Service-Group

  11. No grupo de recursos, selecione o nome de registro do canal de bot (link).In the resource group, select the bot channel registration name (link).

  12. No painel esquerdo, selecione configurações.In the left panel, select Settings.

  13. Na caixa ponto de extremidade de mensagens , digite a URL obtida acima seguida por api/messages .In the Messaging endpoint box, enter the URL obtained above followed by api/messages. Este é um exemplo: https://botteamsauth.azurewebsites.net/api/messages .This is an example: https://botteamsauth.azurewebsites.net/api/messages.

  14. Selecione o botão salvar no canto superior esquerdo.Select the Save button in the upper left.

Testar o bot usando o emuladorTest the bot using the Emulator

Se você ainda não tiver feito isso, instale o emulador do Microsoft bot Framework.If you haven't done it already, install the Microsoft Bot Framework Emulator. Consulte também depurar com o emulador.See also Debug with the Emulator.

Para que o logon de exemplo de bot funcione, você deve configurar o emulador conforme mostrado abaixo.In order for the bot sample login to work you must configure the Emulator as shown below.

Configurar o emulador para autenticaçãoConfigure the Emulator for authentication

Se um bot exigir autenticação, você deve configurar o emulador conforme mostrado abaixo.If a bot requires authentication, you must configure the Emulator as shown below.

  1. Inicie o emulador.Start the Emulator.
  2. No emulador, selecione o ícone de engrenagem ⚙ na parte inferior esquerda ou a guia configurações de emulador no canto superior direito.In the Emulator, select the gear icon ⚙ in the bottom left, or the Emulator Settings tab in the upper right.
  3. Marque a caixa de seleção usar tokens de autenticação da versão 1,0.Check the box by Use version 1.0 authentication tokens.
  4. Insira o caminho local para a ferramenta ngrok .Enter the local path to the ngrok tool. Consulte o ngrok de integração detunelamento/emulador da estrutura do bot.See the Bot Framework Emulator / ngrok tunneling integration Wiki. Para obter mais informações sobre a ferramenta, consulte ngrok.For more tool information, see ngrok.
  5. Marque a caixa de seleção executar ngrok quando o emulador for iniciado.Check the box by Run ngrok when the Emulator starts up.
  6. Selecione o botão salvar .Select the Save button.

Quando o bot exibe um cartão de entrada e o usuário seleciona o botão de entrada, o emulador abre uma página que o usuário pode usar para entrar com o provedor de autenticação.When the bot displays a sign-in card and the user selects the sign-in button, the Emulator opens a page that the user can use to sign in with the authentication provider. Depois que o usuário faz isso, o provedor gera um token de usuário e o envia ao bot.Once the user does so, the provider generates a user token and sends it to the bot. Depois, o bot pode agir em nome do usuário.After that, the bot can act on behalf of the user.

Testar o bot localmenteTest the bot locally

Depois de configurar o mecanismo de autenticação, você pode executar o teste de bot real.After you have configured the authentication mechanism, you can perform the actual bot testing.

  1. Execute o exemplo de bot localmente no seu computador, via Visual Studio por exemplo.Run the bot sample locally on your machine, via Visual Studio for example.

  2. Inicie o emulador.Start the Emulator.

  3. Selecione o botão abrir bot .Select the Open bot button.

  4. Na URL do bot, digite a URL local do bot.In the Bot URL, enter the bot's local URL. Normalmente, http://localhost:3978/api/messages .Usually, http://localhost:3978/api/messages.

  5. Na ID do aplicativo da Microsoft , digite a ID do aplicativo do bot no appsettings.json .In the Microsoft App ID enter the bot's app ID from appsettings.json.

  6. Na senha do aplicativo da Microsoft , digite a senha do aplicativo do bot no appsettings.json .In the Microsoft App password enter the bot's app password from the appsettings.json.

  7. Selecione conectar.Select Connect.

  8. Depois que o bot estiver em funcionamento, insira qualquer texto para exibir o cartão de entrada.After the bot is up and running, enter any text to display the sign-in card.

  9. Selecione o botão entrar .Select the Sign in button.

  10. É exibida uma caixa de diálogo pop-up para confirmar a abertura da URL.A pop-up dialog is displayed to Confirm Open URL. Isso é para permitir que o usuário do bot (você) seja autenticado.This is to allow the bot's user (you) to be authenticated.

  11. Selecione Confirmar.Select Confirm.

  12. Se for solicitado, selecione a conta do usuário aplicável.If asked, select the applicable user's account.

  13. Dependendo da configuração usada para o emulador, você receberá uma das seguintes opções:Depending which configuration you used for the Emulator, you get one of the following:

    1. Usando o código de verificação de entradaUsing sign-in verification code
      ✓ uma janela é aberta exibindo o código de validação.✓ A window is opened displaying the validation code.
      ✓ Copie e insira o código de validação na caixa chat para concluir a entrada.✓ Copy and enter the validation code into the chat box to complete the sign-in.
    2. Usando tokens de autenticação.Using authentication tokens.
      ✓ você está conectado com base em suas credenciais.✓ You're logged in based on your credentials.

    A imagem a seguir é um exemplo da interface do usuário do bot após o logon:The following image is an example of the bot UI after you've logged in:

    emulador de logon do bot de autenticação

  14. Se você selecionar Sim quando o bot solicitar que você deseja exibir seu token?, você receberá uma resposta semelhante à seguinte:If you select Yes when the bot asks Would you like to view your token?, you'll get a response similar to the following:

    token de emulador de logon do bot de autenticação

  15. Digite logout na caixa chat de entrada para sair. Isso libera o token de usuário e o bot não poderá atuar em seu nome até que você entre novamente.Enter logout in the input chat box to sign out. This releases the user token, and the bot won't be able to act on your behalf until you sign in again.

Observação

A autenticação de bot requer o uso do serviço do conector do bot.Bot authentication requires use of the Bot Connector Service. O serviço acessa as informações de registro dos canais de bot para o bot.The service accesses the bot channels registration information for your bot.

Testar o bot implantadoTest the deployed bot

  1. No navegador, navegue até o portal do Azure.In your browser, navigate to the Azure portal.

  2. Encontre o grupo de recursos.Find your resource group.

  3. Selecione o link de recurso.Select the resource link. A página de recursos é exibida.The resource page is displayed.

  4. Na página recurso, selecione testar no chat da Web.In the resource page, select Test in Web Chat. O bot é iniciado e exibe as saudações predefinidas.The bot starts and displays the predefined greetings.

  5. Digite qualquer coisa na caixa chat.Type anything in the chat box.

  6. Selecione a caixa entrar .Select the Sign in box.

  7. É exibida uma caixa de diálogo pop-up para confirmar a abertura da URL.A pop-up dialog is displayed to Confirm Open URL. Isso é para permitir que o usuário do bot (você) seja autenticado.This is to allow the bot's user (you) to be authenticated.

  8. Selecione Confirmar.Select Confirm.

  9. Se for solicitado, selecione a conta do usuário aplicável.If asked, select the applicable user's account. A imagem a seguir é um exemplo da interface do usuário do bot após o logon:The following image is an example of the bot UI after you have logged in:

    logon de bot de autenticação implantado..

  10. Selecione o botão Sim para exibir o token de autenticação.Select the Yes button to display your authentication token. A imagem a seguir é um exemplo:The following image is an example:

    token de logon de bot de auth implantado..

  11. Digite logout para sair.Enter logout to sign out.

    logoff de autenticação do bot implantado

Observação

Se você estiver tendo problemas para entrar, tente testar a conexão novamente, conforme descrito nas etapas anteriores.If you're having problems signing in, try to test the connection again as described in the previous steps. Isso pode recriar o token de autenticação.This could recreate the authentication token. Com o cliente de chat da Web do bot Framework no Azure, talvez seja necessário entrar várias vezes antes de a autenticação ser estabelecida corretamente.With the Bot Framework Web Chat client in Azure, you may need to sign in several times before the authentication is established correctly.

Instalar e testar o bot no TeamsInstall and test the bot in Teams

  1. No seu projeto bot, verifique se a TeamsAppManifest pasta contém o manifest.json junto com um outline.png e color.png arquivos.In your bot project, ensure that the TeamsAppManifest folder contains the manifest.json along with an outline.png and color.png files.

  2. No Gerenciador de soluções, navegue até a TeamsAppManifest pasta.In Solution Explorer, navigate to the TeamsAppManifest folder. Edit manifest.json atribuindo os seguintes valores:Edit manifest.json by assigning the following values:

    1. Certifique-se de que a ID do aplicativo bot recebida no momento do registro do canal de bot está atribuída a id e botId .Ensure that the bot App ID you received at the time of the bot channel registration is assigned to id and botId.
    2. Atribua este valor: validDomains: [ "token.botframework.com" ] .Assign this value: validDomains: [ "token.botframework.com" ].
  3. Selecionar e compactar os manifest.json outline.png arquivos, e color.png .Select and zip the manifest.json, outline.png, and color.png files.

  4. Abra o Microsoft Teams.Open Microsoft Teams.

  5. No painel esquerdo, na parte inferior, selecione o ícone aplicativos.In the left panel, at the bottom, select the Apps icon.

  6. No painel direito, na parte inferior, selecione carregar um aplicativo personalizado.In the right panel, at the bottom, select Upload a custom app.

  7. Navegue até a TeamsAppManifest pasta e carregue o manifesto zipado.Navigate to the TeamsAppManifest folder and upload the zipped manifest. O seguinte assistente é exibido:The following wizard is displayed:

    carregamento de equipes de bot de autenticação

  8. Selecione o botão Adicionar a uma equipe .Select the Add to a team button.

  9. Na janela seguinte, selecione a equipe onde você deseja usar o bot.In the next window, select the team where you want to use the bot.

  10. Selecione o botão configurar um bot .Select the Set up a bot button.

  11. Selecione os três pontos (●●●) no painel esquerdo.Select the three dots (●●●) in the left panel. Em seguida, selecione o ícone do app Studio .Then select the App Studio icon.

  12. Selecione a guia Editor de manifesto . Você deve ver o ícone do bot que você carregou.Select the Manifest editor tab. You should see the icon for the bot you uploaded.

  13. Além disso, você deve ser capaz de ver o bot listado como um contato na lista de chat que você pode usar para trocar mensagens com o bot.Also, you should be able to see the bot listed as a contact in the chat list that you can use to exchange messages with the bot.

Testando o bot localmente no TeamsTesting the bot locally in Teams

O Microsoft Teams é um produto totalmente baseado em nuvem, que exige que todos os serviços que ele acessa estejam disponíveis na nuvem usando pontos de extremidade HTTPS.Microsoft Teams is an entirely cloud-based product, it requires all services it accesses to be available from the cloud using HTTPS endpoints. Portanto, para permitir que o bot (nosso exemplo) funcione no Teams, você precisa publicar o código na nuvem de sua escolha ou tornar uma instância em execução local externamente acessível por meio de uma ferramenta de encapsulamento .Therefore, to enable the bot (our sample) to work in Teams, you need to either publish the code to the cloud of your choice, or make a locally running instance externally accessible via a tunneling tool. Recomendamos o ngrok, que cria uma URL endereçável externamente para uma porta que você abre localmente no seu computador.We recommend ngrok, which creates an externally addressable URL for a port you open locally on your machine. Para configurar o ngrok em preparação para executar seu aplicativo do Microsoft Teams localmente, siga estas etapas:To set up ngrok in preparation for running your Microsoft Teams app locally, follow these steps:

  1. Em uma janela de terminal, vá para o diretório onde você ngrok.exe instalou.In a terminal window, go the directory where you have ngrok.exe installed. Sugerimos definir o caminho da variável de ambiente para apontar para ele.We suggest setting the environment variable path to point to it.

  2. Executar, por exemplo, ngrok http 3978 --host-header=localhost:3978 .Run, for example, ngrok http 3978 --host-header=localhost:3978. Substitua o número da porta, conforme necessário.Replace the port number as needed. Isso inicia o ngrok para escutar na porta que você especificar.This launches ngrok to listen on the port you specify. Em retorno, ele fornece uma URL endereçável externamente, válida por enquanto o ngrok está em execução.In return, it gives you an externally addressable URL, valid for as long as ngrok is running. A imagem a seguir é um exemplo:The following image is an example:

    Cadeia de caracteres de conexão de autenticação do aplicativo bot do teams Adv1..

  3. Copie o endereço HTTPS de encaminhamento.Copy the forwarding HTTPS address. Ele deve ser semelhante ao seguinte: https://dea822bf.ngrok.io/ .It should be similar to the following: https://dea822bf.ngrok.io/.

  4. Anexar /api/messages para obter https://dea822bf.ngrok.io/api/messages .Append /api/messages to obtain https://dea822bf.ngrok.io/api/messages. Este é o ponto de extremidade das mensagens para o bot executado localmente em sua máquina e alcançável pela Web em um chat no Microsoft Teams.This is the messages endpoint for the bot running locally on your machine and reachable over the web in a chat in Microsoft Teams.

  5. Uma etapa final a ser executada é atualizar o ponto de extremidade das mensagens do bot implantado.One final step to perform is to update the messages endpoint of the deployed bot. No exemplo, implantamos o bot no Azure.In the example, we deployed the bot in Azure. Portanto, * * vamos executar estas etapas:So **let's perform these steps:

    1. No navegador, navegue até o portal do Azure.In your browser navigate to the Azure portal.
    2. Selecione o registro do canal do bot.Select your Bot Channel Registration.
    3. No painel esquerdo, selecione configurações.In the left panel, select Settings.
    4. No painel direito, na caixa ponto de extremidade de mensagens , digite a URL ngrok, no nosso exemplo, https://dea822bf.ngrok.io/api/messages .In the right panel, in the Messaging endpoint box, enter the ngrok URL, in our example, https://dea822bf.ngrok.io/api/messages.
  6. Inicie seu bot localmente, por exemplo no modo de depuração do Visual Studio.Start your bot locally, for example in Visual Studio debug mode.

  7. Teste o bot durante a execução local usando o chat da Web de testedo portal da estrutura de bot.Test the bot while running locally using the Bot Framework portal's Test Web chat. Assim como o emulador, esse teste não permite acessar a funcionalidade específica da equipe.Like the Emulator, this test doesn't allow you to access Teams-specific functionality.

  8. Na janela do terminal onde ngrok o está sendo executado, você pode ver o tráfego http entre o bot e o cliente de chat da Web.In the terminal window where ngrok is running you can see HTTP traffic between the bot and the web chat client. Se você quiser um modo de exibição mais detalhado, em uma janela do navegador, insira- http://127.0.0.1:4040 o na janela anterior do terminal.If you want a more detailed view, in a browser window enter http://127.0.0.1:4040 you obtained from the previous terminal window. A imagem a seguir é um exemplo:The following image is an example:

    testes de ngrok de equipes de bot de autenticação..

Observação

Se você parar e reiniciar o ngrok, a URL será alterada.If you stop and restart ngrok, the URL changes. Para usar o ngrok em seu projeto e dependendo dos recursos que você está usando, você deve atualizar todas as referências de URL.To use ngrok in your project, and depending on the capabilities you're using, you must update all URL references.

Informações adicionaisAdditional information

TeamsAppManifest/manifest.jsemTeamsAppManifest/manifest.json

Este manifesto contém as informações necessárias para que o Microsoft Teams se conecte ao bot.This manifest contains information needed by Microsoft Teams to connect with the bot.

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.7/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0.0",
  "id": "",
  "packageName": "com.teams.auth.bot",
  "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 Microsoft Teams se comporta de forma ligeiramente diferente de outros canais, conforme explicado abaixo.With authentication, Teams behaves slightly differently than other channels, as explained below.

Tratamento da atividade de invocaçãoHandling Invoke Activity

Uma atividade de invocação é enviada ao bot em vez da atividade de evento usada por outros canais.An Invoke Activity is sent to the bot rather than the Event Activity used by other channels. Isso é feito com a subclasse de ActivityHandler.This is done by sub-classing the ActivityHandler.

Bots/DialogBot. csBots/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. csBots/TeamsBot.cs

A atividade chamar deve ser encaminhada para a caixa de diálogo se o OAuthPrompt for usado.The Invoke Activity must be forwarded to the dialog if the OAuthPrompt is used.

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.csTeamsActivityHandler.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;
}