Adicionar autenticação a um bot

  • Artigo

APLICA-SE A: SDK v4

O SDK v4 do Serviço de Bot de IA do Azure facilita o desenvolvimento de bots que podem acessar recursos online que exigem autenticação do usuário. O bot não precisa gerenciar tokens de autenticação porque o Azure faz isso por você usando o OAuth 2.0 para gerar um token com base nas credenciais de cada usuário. O bot usa o token gerado pelo Azure para acessar esses recursos. Dessa forma, o usuário não precisa fornecer a ID e a senha ao bot para acessar um recurso protegido, mas apenas a um provedor de identidade confiável.

Para obter uma visão geral de como o Bot Framework lida com esse tipo de autenticação, confira Autenticação de usuário.

Este artigo faz referência a dois exemplos. Um deles mostra como obter um token de autenticação. O outro é mais complexo e mostra como acessar o Microsoft Graph em nome do usuário. Em ambos os casos, você pode usar o Azure AD v1 ou v2 como provedor de identidade para obter um token OAuth para o bot. Este artigo aborda como:

  • Criar um recurso de Bot do Azure
  • Criar o provedor de identidade do Microsoft Entra ID
  • Registrar o provedor de identidade do Microsoft Entra ID no bot
  • Preparar o código do bot

Depois de concluir este artigo, você terá um bot que pode responder a algumas tarefas simples. No exemplo do Microsoft Graph, você pode enviar um email, exibir quem você é e verificar os emails recentes. Você não precisa publicar o bot para testar os recursos do OAuth. No entanto, o bot precisará de um ID e de uma senha válidos do aplicativo do Azure.

Observação

Os SDKs JavaScript, C# e Python do Bot Framework continuarão a ser compatíveis. No entanto, o SDK Java está sendo desativado, com o suporte final de longo prazo terminando em novembro de 2023. Somente correções críticas de segurança e de bugs serão realizadas neste repositório.

Os bots existentes criados com o SDK para Java continuarão a funcionar.

Para a criação de novos bots, considere usar o Power Virtual Agents e ler sobre como escolher a solução de chatbot correta.

Para obter mais informações, confira O futuro da criação de bots.

Considerações de Webchat e Direct Line

Importante

Você precisa usar o Direct Line com autenticação avançada habilitada para mitigar os riscos de segurança ao se conectar a um bot usando o controle do WebChat. Para obter mais informações, confira Autenticação avançada do Direct Line.

Pré-requisitos

  • Conhecimento de fundamentos do bot, gerenciamento de estado, biblioteca de caixas de diálogo, como implementar o fluxo de conversa sequencial e como reutilizar caixas de diálogo.

  • Conhecimento do desenvolvimento do Azure e do OAuth 2.0.

  • Visual Studio 2017 ou posterior para .NET.

  • Node.js para Javascript.

  • Python 3.8+ para Python.

  • Um dos exemplos listados abaixo.

    Amostra Versão do BotBuilder Demonstra
    Autenticação em C# ou JavaScript ou Java ou Python v4 Suporte de OAuthCard
    Autenticação para o Microsoft Graph em C# ou JavaScript ou Java ou Python v4 Suporte da API do Microsoft Graph com o OAuth 2.0
    Autenticação para o Microsoft Teams em C# ou JavaScript ou Java ou Python v4 Suporte da API do Microsoft Graph com o OAuth 2.0

    Para executar os exemplos referenciados neste artigo, você precisará de:

    • Um aplicativo do Microsoft Entra ID com o qual registrar um recurso de bot no Azure. Esse aplicativo permite que o bot acesse um recurso protegido externo, como o Microsoft Graph. Ele também permite que o usuário se comunique com o bot por meio de vários canais, como o WebChat.
    • Um aplicativo separado do Microsoft Entra ID para funcionar como provedor de identidade. Esse aplicativo fornece as credenciais necessárias para estabelecer uma conexão OAuth entre o bot e o recurso protegido. Observe que este artigo usa o Active Directory como um provedor de identidade. Muitos outros provedores também são compatíveis.

Importante

Sempre que você registra um bot no Azure, um aplicativo do Microsoft Entra ID é atribuído a ele. No entanto, esse aplicativo protege o acesso do canal ao bot. Você precisa de um aplicativo do Microsoft Entra ID adicional para cada recurso externo protegido que você deseja que o bot acesse em nome do usuário.

Criar o recurso

Crie o recurso Bot do Azure, que permitirá a você efetuar o registro do seu bot no Serviço de Bot de IA do Azure.

Dica

Não é possível criar novos recursos do Bot de aplicativo web e do Registro de Canais de Bot, no entanto, qualquer recurso existente que esteja configurado e implantado continuará a funcionar. Os bots criados usando um modelo VSIX ou Yeoman do SDK versão 4.14.1.2, ou versões posteriores, contêm modelos do ARM que gerarão um recurso de Bot do Azure.

  1. Vá para o Portal do Azure.

  2. No painel à direita, selecione Criar um recurso.

  3. Na caixa de pesquisa, insira bot e pressione Enter.

  4. Selecione o cartão do Bot do Azure.

    Select Azure bot resource

  5. Selecione Criar.

  6. Insira valores nos campos obrigatórios e revise e atualize as configurações.

    1. Forneça informações em Detalhes do projeto. Selecione se o bot terá residência de dados global ou local. Atualmente, o recurso de residência de dados locais está disponível para recursos na região "westeurope" e "centralindia". Para obter mais informações, confira como Regionalização no Serviço de Bot de IA do Azure.

      The project details settings for an Azure Bot resource

    2. Forneça informações no ID do Aplicativo da Microsoft. Selecione como a identidade do bot será gerenciada no Azure e se deseja criar uma nova identidade ou usar uma existente.

      The Microsoft app ID settings for an Azure Bot resource

  7. Selecione Examinar + criar.

  8. Se os testes de validação forem aprovados, selecione Criar.

  9. Assim que a implantação for concluída, selecione Ir para o recurso. Você deve ver o bot e os recursos relacionados listados no grupo de recursos selecionado.

  10. Se você ainda não tem o SDK do Bot Framework, selecione Fazer download usando o GitHub para saber como consumir os pacotes de seu idioma preferido.

    Create bot in SDK

Agora, você está com tudo pronto para desenvolver o bot com o SDK do Bot Framework.

Dica

Quando o Azure cria um recurso de Bot do Azure de locatário único ou multilocatário com uma nova ID de aplicativo, ele também gera uma senha.

Informações de identidade do bot

Siga estas etapas para adicionar informações de identidade ao arquivo de configuração do bot. O arquivo difere dependendo da linguagem de programação usada para criar o bot.

Importante

As versões Java e Python do SDK do Bot Framework oferecem suporte apenas a bots multilocatário. As versões para C# e para JavaScript oferecem suporte a todos os três tipos de aplicativos para o gerenciamento da identidade do bot.

Idioma Nome do arquivo Observações
C# appsettings.json Oferece suporte a todos os três tipos de aplicativos para gerenciar a identidade do bot.
JavaScript .env Oferece suporte a todos os três tipos de aplicativos para gerenciar a identidade do bot.
Java application.properties Suporta apenas bots multilocatário.
Python config.py Suporta apenas bots multilocatário. Forneça as propriedades de identidade como argumentos para as chamadas de método os.environ.get.

As informações de identidade que você precisa adicionar dependem do tipo de aplicativo do bot. Forneça os valores a seguir no arquivo de configuração.

Disponível somente para bots em C# e JavaScript.

Propriedade Valor
MicrosoftAppType UserAssignedMSI
MicrosoftAppId A ID do cliente da identidade gerenciada atribuída pelo usuário.
MicrosoftAppPassword Não aplicável. Deixe em branco para um bot de identidade gerenciada atribuída pelo usuário.
MicrosoftAppTenantId A ID do locatário de uma identidade gerenciada atribuída pelo usuário.

Para atualizar seu serviço de aplicativo

Se você tiver um recurso de serviço de aplicativo existente (aplicativo Web) para o bot e o bot for um aplicativo de identidade gerenciada atribuída pelo usuário, poderá ser necessário atualizar o serviço de aplicativo do bot:

  1. Acesse a folha Serviço de Aplicativo do aplicativo Web do bot.
  2. Em Configurações, selecione Identidade.
  3. Na folha Identidade, selecione a guia Atribuído pelo usuário e Adicionar (+).
  4. Na folha Adicionar a identidade gerenciada atribuída pelo usuário:

    1. Selecione sua assinatura.

    2. Para Identidades gerenciadas atribuídas pelo usuário, selecione a identidade gerenciada para seu bot. Se a identidade gerenciada foi gerada automaticamente para você, ela terá o mesmo nome do seu bot.

    3. Selecione Adicionar para usar essa identidade para o bot.

      The App Service Identity blade with the managed identity for the bot selected.

Como obter a ID do aplicativo ou do locatário

Para obter a ID do aplicativo ou do locatário do bot:

  1. Acesse a folha de recursos do Bot do Azure para seu bot.
  2. Acesse a folha Configuração do bot. Nessa folha, é possível copiar a ID do Aplicativo da Microsoft ou a ID do aplicativo do Locatário do bot.

Para gerar uma nova senha

Os bots de locatário único e de multilocatário têm um segredo ou uma senha para o aplicativo que você precisa para efetuar algumas operações. O Serviço de Bot de IA do Azure oculta o segredo do bot. No entanto, o proprietário do recurso de Serviço de Aplicativo do bot pode gerar uma nova senha:

  1. Acesse a folha de recursos do Bot do Azure para seu bot.
  2. Acesse a folha Configuração do bot.
  3. Selecione Gerenciar, ao lado da ID do Aplicativo da Microsoft, para acessar a folha Certificados + segredos do serviço de aplicativo.
  4. Siga as instruções na folha para criar um novo segredo do cliente e registrar o valor em um local seguro.

Serviço de identidade do Microsoft Entra ID

O Microsoft Entra ID é um serviço de identidade de nuvem que permite a criação de aplicativos que conectam usuários com segurança usando protocolos padrão do setor, como o OAuth2.0.

Você pode usar um destes dois serviços de identidade:

  1. Plataforma do desenvolvedor (v1.0) do Microsoft Entra ID. Também conhecida como o ponto de extremidade do Azure AD v1, que permite que você crie aplicativos que conectam usuários com segurança a uma conta corporativa ou de estudante da Microsoft. Para obter mais informações, confira a visão geral do Microsoft Entra ID para desenvolvedores (v1.0).
  2. Plataforma de identidade da Microsoft (v2.0). Também conhecida como o ponto de extremidade do Microsoft Entra ID, que é uma evolução da plataforma do Azure AD (v1.0). Ela permite que você crie aplicativos que se conectam em todos os provedores de identidade da Microsoft e obtenha tokens para chamar APIs da Microsoft, como o Microsoft Graph, ou outras APIs que os desenvolvedores criaram. Para obter mais informações, confira a Visão geral da plataforma de identidade da Microsoft (v2.0).

Para obter informações sobre as diferenças entre os pontos de extremidade v1 e v2, confira Por que atualizar para a plataforma de identidade da Microsoft (v2.0)?. Para obter informações completas, confira a Plataforma de identidade da Microsoft (anteriormente, Microsoft Entra ID para desenvolvedores).

Criar o provedor de identidade do Microsoft Entra ID

Esta seção mostra como criar um provedor de identidade do Microsoft Entra ID que usa o OAuth 2.0 para autenticar o bot. Você pode usar pontos de extremidade do Azure AD v1 ou do Microsoft Entra ID.

Dica

Você precisará criar e registrar o aplicativo do Microsoft Entra ID em um locatário no qual você pode consentir em delegar permissões solicitadas por um aplicativo.

  1. Abra o painel do Microsoft Entra ID no portal do Azure. Se você não estiver no locatário correto, escolha Trocar de diretório para trocar para o locatário correto. (Para obter informações sobre como criar um locatário, confira Acessar o portal e criar um locatário.)

  2. Abra o painel Registros de aplicativo.

  3. No painel Registros de aplicativo, escolha Novo registro.

  4. Preencha os campos obrigatórios e crie o registro do aplicativo.

    1. Nome do seu aplicativo.

    2. Selecione os Tipos de conta compatíveis para o aplicativo. (Qualquer uma dessas opções funcionará com este exemplo.)

    3. Na URI de redirecionamento, escolha Web e defina a URL como uma das URLs de redirecionamento do OAuth suportadas..

    4. Selecione Registrar.

      • Depois de criado, o Azure exibe a página Visão geral do aplicativo.
      • Registre o valor da ID do aplicativo (cliente). Você usará esse valor posteriormente como a ID do cliente quando criar a cadeia de conexão e registrar o provedor do Microsoft Entra ID no registro do bot.
      • Registre o valor da ID do diretório (locatário). Você usará esse valor para registrar esse aplicativo do provedor no bot.

  5. No painel de navegação, selecione Certificados e segredos para criar um segredo para seu aplicativo.

    1. Em Segredos do cliente, selecione Novo segredo do cliente.
    2. Adicione uma descrição para identificar esse segredo em relação a outros que talvez você precise criar para esse aplicativo, como bot login.
    3. Em Expira, escolha um período após o qual o segredo expirará.
    4. Selecione Adicionar.
    5. Antes de deixar os Certificados e os segredos, registre o segredo. Você usará esse valor posteriormente como o Segredo do cliente quando registrar o aplicativo do Microsoft Entra ID no bot.

  6. No painel de navegação, escolha Permissões de API para abrir o painel Permissões de API. A melhor prática é definir explicitamente as permissões de API para o aplicativo.

    1. Escolha Adicionar uma permissão para mostrar o painel Solicitar permissões de API.

    2. Para este exemplo, selecione as APIs da Microsoft e o Microsoft Graph.

    3. Escolha Permissões delegadas e verifique se as permissões necessárias estão selecionadas. Este exemplo requer estas permissões.

      Observação

      As permissões marcadas como CONSENTIMENTO DO ADMINISTRADOR NECESSÁRIO exigirão um usuário e um administrador de locatário para fazer logon, portanto, evite-os para seu bot.

      • openid
      • profile
      • Mail.Read
      • Mail.Send
      • User.Read
      • User.ReadBasic.All

    4. Selecione Adicionar Permissões. (Na primeira vez que um usuário acessar esse aplicativo por meio do bot, ele precisará conceder consentimento.)

Agora, você tem um aplicativo do Microsoft Entra ID configurado.

Observação

Você atribuirá a ID do aplicativo (cliente) e o Segredo do cliente quando criar a cadeia de conexão e registrar o provedor de identidade no registro do bot. Confira a próxima seção.

Registrar o provedor de identidade do Microsoft Entra ID no bot

O próximo passo é registrar provedor de identidade no bot.

  1. Abra a página de recursos do Bot do Azure do bot no Portal do Azure.

  2. Selecione Configurações.

  3. Em Configurações de Conexão do OAuth perto da parte inferior da página, escolha Adicionar configuração.

  4. Preencha o formulário da seguinte maneira:

    1. Nome. Digite um nome para a conexão. Você o usará em seu código de bot.

    2. Provedor de serviços. Escolha Microsoft Entra ID para exibir campos específicos do Microsoft Entra ID.

    3. ID do cliente. Insira a ID do aplicativo (cliente) que você registrou para o provedor de identidade do Microsoft Entra ID.

    4. Segredo do cliente. Insira o segredo que você registrou para o provedor de identidade do Microsoft Entra ID.

      Dica

      Se você desejar usar certificados, poderá escolher o provedor AAD v2 com certificados. Você precisará dar ao repositório de tokens do Serviço de Bot (appid: 5b404cf4-a79d-4cfe-b866-24bf8e1a4921) a permissão para obter o certificado.

    5. URL de troca de token. Deixe-a em branco porque ela só é usada para SSO no Microsoft Entra ID.

    6. ID do locatário. Insira a ID do diretório (locatário) que você registrou anteriormente para o aplicativo do Microsoft Entra ID ou comum, dependendo dos tipos de conta compatíveis selecionados quando você criou o aplicativo do Azure DD. Para decidir qual valor atribuir, siga estes critérios:

      • Quando criar o aplicativo do Microsoft Entra ID, se você tiver escolhido Contas neste diretório organizacional somente (somente Microsoft: locatário único), insira a ID de locatário que você registrou anteriormente para o aplicativo do Microsoft Entra ID.
      • No entanto, se você tiver escolhido Contas em qualquer diretório organizacional (qualquer diretório do Microsoft Entra ID: contas Microsoft multilocatário e pessoais, p. ex., XBox, Outlook.com) ou Contas em qualquer diretório organizacional (diretório do Microsoft entra ID: multilocatário), insira common em vez de um ID de locatário. Caso contrário, o aplicativo do Microsoft Entra ID verificará o locatário cuja ID foi escolhida e excluirá as contas Microsoft pessoais.

      Esse será o locatário associado aos usuários que podem ser autenticados. Para obter mais informações, confira Locação no Microsoft Entra ID.

    7. Em Escopos, digite os nomes da permissão que você escolheu no registro de aplicativo. Para fins de teste, insira somente openid profile.

      Observação

      No Microsoft Entra ID, o campo Escopos usa uma lista de valores separada por espaços que diferencia maiúsculas de minúsculas.

  5. Selecione Salvar.

Observação

Esses valores permitem que seu aplicativo acesse os dados do Office 365 por meio da API do Microsoft Graph. Além disso, a URL de troca de token deve ser deixada em branco porque é usada para SSO somente no Microsoft Entra ID.

Testar a conexão

  1. Escolha a entrada de conexão para abrir a conexão que você criou.
  2. Escolha Testar Conectividade na parte superior do painel Configuração da Conexão do Provedor de Serviços.
  3. Na primeira vez, deve abrir uma nova guia do navegador listando as permissões que seu aplicativo está solicitando e solicitará que você aceite.
  4. Selecione Aceitar.
  5. Essa ação deve redirecionar você para uma página de Teste de Conectividade para <nome-da-sua-conexão> bem-sucedida.

Agora você pode usar esse nome de conexão no código do bot para recuperar tokens de usuário.

Preparar o código do bot

Você precisará da ID de aplicativo e da senha do bot para concluir esse processo.

  1. Clone no repositório do GitHub o exemplo com o qual você deseja trabalhar: Autenticação de bot ou Autenticação de bot para o Microsoft Graph.

  2. Atualize appsettings.json:

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

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

      Dependendo dos caracteres do segredo do bot, você pode precisar ignorar a senha com XML. Por exemplo, qualquer "e" comercial (&) será necessário a ser codificado como &amp;.

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

    Para usar o OAuth no bot com residência de dados na nuvem pública, você deve adicionar as configurações a seguir ao appsettings

    "OAuthUrl": "<Regional-OAuth-Uri>",
"ToChannelFromBotOAuthScope": "https://api.botframework.com",
"ToChannelFromBotLoginUrlTemplate": "https://api.botframework.com",
"PublicAzureChannel": "https://api.botframework.com",
"ToBotFromChannelOpenIdMetadataUrl": "https://login.botframework.com/v1/.well-known/openidconfiguration",
"ToBotFromEmulatorOpenIdMetadataUrl": "https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration",
"ToBotFromChannelTokenIssuer": "https://api.botframework.com",
"ToChannelFromBotLoginUrl": "https://login.microsoftonline.com/botframework.com",

    Em que <Regional-OAuth-Url> é uma das seguintes URIs:

    URI Descrição
    https://europe.api.botframework.com Para bots de nuvem pública com residência de dados na Europa.
    https://unitedstates.api.botframework.com Para bots de nuvem pública com residência de dados nos Estados Unidos.
    https://india.api.botframework.com Para bots de nuvem pública com residência de dados na Índia.

  3. Atualize Startup.cs:

    Para usar o OAuth em nuvens do Azure não públicas, como a nuvem do governo, você deve adicionar o código a seguir ao arquivo Startup.cs.

    string uri = "<uri-to-use>";
MicrosoftAppCredentials.TrustServiceUrl(uri);
OAuthClientConfig.OAuthEndpoint = uri;

    Em que <uri-to-use> é uma das seguintes URIs:

    URI Descrição
    https://api.botframework.azure.us Para bots de nuvem do governo dos Estados Unidos sem residência de dados.
    https://api.botframework.com Para bots de nuvem pública sem residência de dados. Essa é a URI padrão e não requer alterações no Startup.cs.

Para obter a ID do aplicativo da Microsoft e os valores de Senha do aplicativo da Microsoft, confira Obter senha de registro.

Observação

Agora, você pode publicar esse código de bot na sua assinatura do Azure (clique com o botão direito no projeto e escolha Publicar), mas isso não é necessário para este artigo. Você precisaria definir uma configuração de publicação que usasse o aplicativo e o plano de hospedagem que você usou ao configurar o bot no portal do Azure.

Testar o bot usando o Emulator

Caso ainda não tenha feito isso, instale o Bot Framework Emulator. Confira também Depurar com o Emulator.

Para que o logon do exemplo do bot funcione é necessário configurar o Emulator, conforme mostrado em Configurar o Emulator para autenticação.

Testando

Após configurar o mecanismo de autenticação, é possível executar o teste real do exemplo do bot.

Observação

Talvez seja necessário inserir um código mágico devido à maneira como a amostra de bot é implementada. Este código mágico faz parte do RFC#7636 e está lá para adicionar um elemento de segurança extra. Ao ser removido o código mágico, existe um risco maior à segurança. Isso pode ser mitigado por meio da Direct Line com autenticação avançada habilitada. Para obter mais informações, confira Autenticação avançada do Bot Framework.

  1. Execute o exemplo do bot localmente em seu computador.
  2. Inicie o Emulator.
  3. Você precisará fornecer a ID e a senha do aplicativo do bot quando se conectar com ele.
    • Obtenha a ID do aplicativo e a senha do registro de aplicativo do Azure. Esses são os mesmos valores atribuídos ao aplicativo bot no arquivo appsettings.json ou .env. No Emulator, atribua esses valores no arquivo de configuração ou na primeira vez que se conectar ao bot.
    • Se você precisar usar um escape XML na senha no código do bot, isso também precisará ser feito aqui.
  4. Digite help para ver uma lista dos comandos disponíveis para o bot e testar os recursos de autenticação.
  5. Quando você tiver entrado, você não precisa fornecer suas credenciais novamente até sair.
  6. Para sair e cancelar a sua autenticação, digite logout.

Observação

A autenticação do bot requer o uso do Serviço do Bot Connector.. O serviço acessa informações do recurso de bot do Azure.

Exemplo de autenticação

No exemplo Autenticação de Bot, o diálogo foi projetado para recuperar o token de usuário após este se conectar.

Sample conversation with the authentication sample bot.

Exemplo de autenticação para o Microsoft Graph

No exemplo Autenticação de Bot para o Microsoft Graph, o diálogo é projetado para aceitar um conjunto limitado de comandos depois que o usuário faz logon.

Sample conversation with the Microsoft Graph authentication sample bot.

Informações adicionais

Quando um usuário pede ao bot para fazer algo que requer que o bot tenha o usuário conectado, o bot pode usar um OAuthPrompt para iniciar a recuperação de um token para uma determinada conexão. O OAuthPrompt cria um fluxo de recuperação de token composto por:

  1. Verificação para conferir se o Serviço de Bot de IA do Azure já tem um token para o usuário e a conexão atuais. Se houver um token, o token será retornado.
  2. Se o Serviço de Bot de IA do Azure não tiver um token em cache, um OAuthCard será criado, que é um botão de credencial no qual o usuário pode clicar.
  3. Após o usuário clicar no botão OAuthCard de credencial, o Serviço de Bot de IA do Azure enviará diretamente ao bot o token do usuário ou apresentará ao usuário um código de autenticação de seis dígitos para ser inserido na janela de chat.
  4. Se o usuário receber um código de autenticação, o bot trocará esse código de autenticação pelo token do usuário.

As seções a seguir descrevem como o exemplo implementa algumas tarefas de autenticação comuns.

Use um prompt do OAuth para conectar o usuário e obter um token

Architecture diagram for the C# sample.

Dialogs\MainDialog.cs

Adicione um prompt do OAuth a MainDialog em seu construtor. Aqui, o valor para o nome da conexão foi recuperado do arquivo appsettings.JSON.

AddDialog(new OAuthPrompt(
    nameof(OAuthPrompt),
    new OAuthPromptSettings
    {
        ConnectionName = ConnectionName,
        Text = "Please Sign In",
        Title = "Sign In",
        Timeout = 300000, // User has 5 minutes to login (1000 * 60 * 5)
    }));

Dentro de uma etapa de diálogo, use BeginDialogAsync para iniciar o prompt do OAuth, que pede ao usuário para entrar.

  • Se o usuário já estiver conectado, isso irá gerar um evento de resposta de token, sem avisar o usuário.
  • Caso contrário, será solicitado que o usuário entre. O Serviço de Bot de iA do Azure envia o evento de resposta do token depois que o usuário tenta iniciar sessão.
return await stepContext.BeginDialogAsync(nameof(OAuthPrompt), null, cancellationToken);

Dentro da etapa de diálogo a seguir, procure a presença de um token no resultado da etapa anterior. Se não for nulo, significará que o usuário foi conectado com êxito.

// 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.
var tokenResponse = (TokenResponse)stepContext.Result;

Aguardar um TokenResponseEvent

Quando iniciamos um prompt do OAuth, ele aguarda um evento de resposta de token, a partir do qual ele recupera o token do usuário.

Bots\AuthBot.cs

AuthBot deriva de ActivityHandler e lida explicitamente com atividades de evento de resposta de token. Aqui, damos sequência ao diálogo ativo, que permite que o prompt do OAuth processe o evento e recupere o token.

protected override async Task OnTokenResponseEventAsync(ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    Logger.LogInformation("Running dialog with Token Response Event Activity.");

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

Desconecte o usuário

É uma melhor prática permitir que os usuários se desconectem explicitamente, em vez de esperar que a conexão atinja o tempo limite.

Dialogs\LogoutDialog.cs

private async Task<DialogTurnResult> InterruptAsync(DialogContext innerDc, CancellationToken cancellationToken = default(CancellationToken))
{
    if (innerDc.Context.Activity.Type == ActivityTypes.Message)
    {
        var text = innerDc.Context.Activity.Text.ToLowerInvariant();

        if (text == "logout")
        {
            // The UserTokenClient encapsulates the authentication processes.
            var userTokenClient = innerDc.Context.TurnState.Get<UserTokenClient>();
            await userTokenClient.SignOutUserAsync(innerDc.Context.Activity.From.Id, ConnectionName, innerDc.Context.Activity.ChannelId, cancellationToken).ConfigureAwait(false);

            await innerDc.Context.SendActivityAsync(MessageFactory.Text("You have been signed out."), cancellationToken);
            return await innerDc.CancelAllDialogsAsync(cancellationToken);
        }
    }

    return null;
}

Como adicionar autenticação do Teams

O OAuth é tratado de forma diferente no Teams com relação a outros canais. O exemplo de Bot de Autenticação do Teams (em C#, JavaScript, Java ou Python) demonstra como implementar adequadamente a autenticação do Teams.

Leitura adicional