Adicionar autenticação a um bot

aplica-se a: SDK v4

O SDK v4 do serviço de bot 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 para você usando o OAuth 2,0 para gerar um token baseado 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 nem a senha para o bot para acessar um recurso protegido, mas apenas para um provedor de identidade confiável.

Para obter uma visão geral de como a estrutura de bot lida com esse tipo de autenticação, consulte autenticação do usuário.

Observação

A autenticação também funciona com o BotBuilder v3. No entanto, este artigo aborda apenas o código de exemplo v4.

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

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

Considerações de Webchat e Direct Line

Importante

Você precisa usar a linha direta com autenticação avançada habilitada para mitigar riscos de segurança ao se conectar a um bot usando o controle de chat da Web. Para obter mais informações, consulte Autenticação avançada de linha direta.

Pré-requisitos

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

Sobre as amostras

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

  1. Um aplicativo do Azure AD (Azure Active Directory) para 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.
  2. Um aplicativo do Azure AD separado que funciona como o 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 Azure AD é atribuído a ele. No entanto, esse aplicativo protege o acesso do canal ao bot. Você precisa de um aplicativo do Azure AD adicional para cada recurso protegido externo que deseja que o bot acesse em nome do usuário.

Criar o recurso

Crie o recurso de bot do Azure , que permitirá que você registre seu bot com o serviço de bot do Azure.

Aviso

O registro dos canais de bot e bot do aplicativo Web será preterido, mas os recursos existentes continuarão a funcionar. Em vez disso, você deve usar o bot do Azure.

  1. Vá para o Portal do Azure.

  2. No painel direito, selecione criar um recurso.

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

  4. Selecione o cartão de bot do Azure .

    Selecionar recurso de bot do Azure

  5. Selecione Criar.

    Criar recurso de bot do Azure

  6. Insira os valores necessários. A figura a seguir mostra a criação da nova ID do aplicativo Microsoft selecionada.

    Criar valores de recurso de bot do Azure

    Você também pode selecionar usar registro de aplicativo existente e inserir sua ID de aplicativo e senha existentes.

    Criar valores existentes do recurso de bot do Azure

  7. Selecione Examinar + criar.

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

  9. Selecione Ir para grupo de recursos. Você deve ver o bot e os recursos de Azure Key Vault relacionados listados no grupo de recursos selecionado.

    Dica

    O segredo do aplicativo (senha) é armazenado no cofre de chaves e há um cofre de chaves por grupo de recursos. O uso do Key Vault é recomendado em vez de copiar e armazenar dados confidenciais.

  10. Selecione obter o SDK do GitHub para criar o bot com o SDK do bot Framework.

    Criar bot no SDK

Cofre de Chave do Azure

Quando o Azure cria o recurso de bot do Azure, ele também gera uma ID de aplicativo e uma senha e armazena a senha em Azure Key Vault.

Key Vault é um serviço que fornece gerenciamento de segredos centralizado, com controle total sobre políticas de acesso e histórico de auditoria. Para obter mais informações, consulte usar referências de Key Vault para o serviço de aplicativo e Azure Functions. Observe que você será cobrado por uma pequena taxa para usar o serviço. Para saber mais, confira Preços do Key Vault.

ID e senha do aplicativo

Você precisa da ID e da senha do aplicativo de recurso de bot do Azure para configurar o bot para implantação. Você atribuirá seus valores às variáveis relacionadas: MicrosoftAppId e MicrosoftAppPassword contidas no arquivo de configuração do projeto de bot. O arquivo difere dependendo da linguagem de programação usada para criar o bot, conforme mostrado abaixo.

O appsettings.json arquivo contém estas configurações:

{
  "MicrosoftAppId": "<your app id>",
  "MicrosoftAppPassword": "<your password>"
}

Obter a ID do aplicativo de recurso de bot do Azure

  1. Vá para o Portal do Azure.
  2. Selecione o recurso de bot do Azure para obter sua ID do aplicativo.
  3. No painel esquerdo, na seção Configurações, selecione Configuração.
  4. Copie e salve o valor contido na caixa ID do Aplicativo da Microsoft.

Obter a senha do recurso de bot do Azure Azure Key Vault

Quando o Azure cria o recurso de Bot do Azure, ele armazena a senha do aplicativo Azure Key Vault. Para obter informações sobre como acessar o cofre de chaves para obter sua senha, consulte:

Serviço de identidade do Azure AD

O Azure AD (Azure Active Directory) é um serviço de identidade de nuvem que permite que você crie 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 do Azure AD (v1.0). 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 Azure Active Directory para desenvolvedores (v1.0).
  2. Plataforma de identidade da Microsoft (v2.0). Também conhecida como o ponto de extremidade do Azure AD v2, 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 Plataforma de identidade da Microsoft (conhecida anteriormente como Azure Active Directory para desenvolvedores).

Criar o provedor de identidade do Azure AD

Esta seção mostra como criar um provedor de identidade do Azure AD que usa OAuth2 para autenticar o bot. Você pode usar os pontos de extremidade do Azure AD v1 ou Azure AD v2.

Dica

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

  1. Abra o painel do Azure Active Directory no portal do Azure. Se você não estiver no locatário correto, clique em Trocar de diretório para trocar para o locatário correto. (Para obter instruçõ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, clique em 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. Para o URI de redirecionamento

      1. Selecione Web.
      2. Defina a URL como https://token.botframework.com/.auth/web/redirect.
    4. Clique em 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 ao criar a cadeia de conexão e registrar o provedor do AD do Azure com o registro de bot.
      • Registre também o valor da ID do diretório (locatário) . Você também usará isso para registrar este aplicativo de provedor com o bot.
  5. No painel de navegação, clique em Certificados e segredos para criar um segredo para o aplicativo.

    1. Em Segredos de cliente, clique em 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. Defina Expira como Nunca.
    4. Clique em Adicionar.
    5. Antes de sair desta página, registre o segredo. Você usará esse valor posteriormente como o Segredo do cliente ao registrar seu aplicativo do Azure AD com seu bot.
  6. No painel de navegação, clique em Permissões de API para abrir o painel Permissões de API. Uma prática recomendada é definir explicitamente as permissões de API para o aplicativo.

    1. Clique em Adicionar uma permissão para mostrar o painel Permissões da API de solicitação.

    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. Clique em Adicionar permissões. (Na primeira vez que um usuário acessar esse aplicativo por meio do bot, ele precisará dar consentimento.)

Agora você tem um aplicativo do Azure AD configurado.

Observação

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

Registrar o provedor de identidade do Azure AD com o bot

A próxima etapa é registrar o aplicativo do Azure AD que você acabou de criar com o bot.

Azure AD v2

  1. Navegue até a página Registro de Canais de Bot do seu bot no Portal do Azure.

  2. Clique em Configurações.

  3. Em Configurações de Conexão do OAuth na parte inferior da página, clique em 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. Selecione Azure Active Directory v2. Depois que você selecionar esta opção, os campos específicos do Azure AD serão exibidos.

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

    4. Segredo do cliente. Insira o segredo que você registrou para seu provedor de identidade do Azure AD v2.

    5. URL Exchange token. Deixe em branco porque ele é usado apenas para SSO no Azure AD v2.

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

      • Ao criar o aplicativo do Azure AD, se você tiver selecionado Contas neste diretório organizacional somente (somente Microsoft – locatário único) insira a ID de locatário que você registrou antes para o aplicativo AAD.
      • No entanto, se você selecionou Contas em qualquer diretório organizacional (qualquer conta Microsoft pessoal e multilocatário do diretório do AAD, por exemplo, XBox, Outlook.com) ou Contas em qualquer diretório organizacional (diretório do Microsoft Azure AD – multilocatário) , insira a palavra common, em vez de uma ID de locatário. Caso contrário, o aplicativo AAD verificará o locatário cuja ID foi selecionada e excluirá as contas MS pessoais.

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

    7. Para Escopos, insira os nomes da permissão que você escolheu no registro do aplicativo. Para fins de teste, você pode simplesmente inserir: openid profile .

      Observação

      Para o Azure AD v2, o campo Escopos usa uma lista de valores separada por espaços que diferencia maiúsculas de minúsculas.

  5. Clique em Save (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 Azure AD v2.

Testar sua conexão

  1. Clique na entrada de conexão para abrir a conexão que você acabou de criar.
  2. Clique em Testar Conexão na parte superior do painel Configuração de 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. Clique em Aceitar.
  5. Isso deve, então, redirecioná-lo para uma página Teste da conexão com <your-connection-name> bem-sucedido.

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

Como preparar o código do bot

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

  1. Clone do repositório do GitHub o exemplo com o qual deseja trabalhar: Autenticação de bot ou Autenticação de bot MSGraph.

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

    {
      "MicrosoftAppId": "",
      "MicrosoftAppPassword": "",
      "ConnectionName": ""
    }
    
  3. Atualizar startup.cs:

    Para usar o OAuth em nuvens não públicas do Azure, como a nuvem governamental, você deve adicionar o seguinte código no startup.cs arquivo:

    string uri = "https://api.botframework.azure.us";
    MicrosoftAppCredentials.TrustServiceUrl(uri);
    OAuthClientConfig.OAuthEndpoint = uri;
    

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

Observação

Agora você poderia publicar esse código de bot em 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

Se ainda não tiver feito isso, instale o Bot Framework Emulator. Consulte também depurar com o Emulator.

para que o logon de exemplo de bot funcione, você deve 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 de exemplo do bot real.

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 remover o código mágico, há um risco maior à segurança. Isso pode ser mitigado usando a linha direta com autenticação avançada habilitada. Para obter mais informações, consulte Autenticação avançada do bot Framework.

  1. Execute o exemplo do bot localmente em seu computador.
  2. Inicie o Emulador.
  3. Será necessário fornecer a ID e a senha de aplicativo do seu bot ao 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, você atribui esses valores no arquivo de configuração ou na primeira vez que se conecta 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 de Conector de Bot. O serviço acessa as informações de registro de canais do seu bot.

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.

imagem de teste do bot de autenticação

Exemplo de MSGraph de autenticação

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

imagem de teste do bot msgraph


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 se o Serviço de Bot 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 do Azure não tiver um token em cache, um OAuthCard será criado, o qual é um botão de entrada no qual o usuário pode clicar.
  3. Após o usuário clicar no botão OAuthCard, o Serviço de Bot do Azure enviará diretamente ao bot o token do usuário ou apresentará ao usuário um código de autenticação de 6 dígitos para inserir 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

imagem da arquitetura Csharp

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 do Azure envia o evento de resposta do token depois que o usuário tenta entrar.
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, 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

Considera-se melhor prática permitir que os usuários saiam ou 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 Teams se comporta de maneira um pouco diferente de outros canais em relação ao OAuth e exige algumas alterações para implementar a autenticação corretamente. adicionaremos o código da amostra de Bot de autenticação Teams (C# / JavaScript / Java).

Uma diferença entre outros canais e o Temas é o Teams envia uma atividade de invocação para o bot, em vez de uma atividade de evento.

Bots/TeamsBot.cs

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);
}

Se você usar um prompt OAuth, essa atividade de invocação deverá ser encaminhada para a caixa de diálogo. Faremos isso no TeamsActivityHandler. Adicione o código a seguir ao arquivo de caixa de diálogo principal.

Bots/DialogBot.cs

public class DialogBot<T> : TeamsActivityHandler where T : Dialog

Por fim, não deixe de adicionar um arquivo TeamsActivityHandler apropriado (TeamsActivityHandler.cs para bots C# e teamsActivityHandler.js para bots do JavaScript) no nível mais alto na pasta do bot.

O TeamsActivityHandler também envia atividades de reação de mensagem. Uma atividade de reação de mensagem faz referência à atividade original usando o campo responder à ID. Essa atividade também deve ser visível por meio do Feed de Atividades no Microsoft Teams.

Observação

Você precisa criar um manifesto e incluir token.botframework.com na seção validDomains; caso contrário, o botão Entrar do OAuthCard não abrirá a janela de autenticação. Use o App Studio para gerar seu manifesto.

Leitura adicional