Criar um bot com autenticação SSO
Os bots de conversa no Microsoft Teams executam tarefas automatizadas repetitivas iniciadas pelos usuários, como o serviço ao cliente. O usuário precisa entrar várias vezes sem autenticação SSO (logon único). Com métodos de autenticação SSO, os usuários não precisam entrar no bot várias vezes.
Um bot se comporta de forma diferente dependendo da conversa em que está envolvido:
- Bots em conversas de chat de canal e de grupo exigem os usuários para @mention o bot.
- Os bots em uma conversa um-para-um não exigem um @mention. Todas as mensagens enviadas pelas rotas do usuário para o bot.
Este guia passo a passo ajuda você a criar um bot com autenticação SSO. Você verá a seguinte saída:
Pré-requisitos
Certifique-se de instalar as seguintes ferramentas e configurar seu ambiente de desenvolvimento:
| Instalar | Para usar... | |
|---|---|---|
| Microsoft Teams | Microsoft Teams para colaborar com todos com quem você trabalha por meio de aplicativos para chat, reuniões e chamadas em um só lugar. | |
| Visual Studio 2022 | Você pode instalar a versão corporativa no Visual Studio 2022 e instalar as cargas de trabalho ASP.NET e desenvolvimento da Web. Use a versão mais recente. | |
| Conta de desenvolvedor do Microsoft 365 | Acesso à conta do Teams com as permissões apropriadas para instalar um aplicativo. | |
| Túnel de desenvolvimento | Os recursos do aplicativo Teams (bots de conversa, extensões de mensagem e webhooks de entrada) precisam de conexões de entrada. Um túnel conecta seu sistema de desenvolvimento ao Teams. O túnel de desenvolvimento é uma ferramenta poderosa para abrir com segurança seu localhost para a Internet e controlar quem tem acesso. O túnel de desenvolvimento está disponível no Visual Studio 2022 versão 17.7.0 ou posterior. ou você também pode usar o ngrok como um túnel para conectar seu sistema de desenvolvimento ao Teams. Não é necessário para aplicativos que incluem apenas guias. Esse pacote é instalado no diretório do projeto (usando npm devDependencies). |
Observação
Depois de baixar o ngrok, inscreva-se e instale authtoken.
Configurar seu locatário de desenvolvimento do Teams
Um locatário é como um espaço ou um contêiner em que você conversa, compartilha arquivos e executa reuniões para sua organização no Teams. Você também pode carregar e testar o aplicativo personalizado.
Verificar a opção de carregamento de aplicativo personalizado
Depois de criar o aplicativo, você deve carregar seu aplicativo no Teams sem distribuí-lo. Esse processo é conhecido como upload de aplicativo personalizado. Entre em sua conta do Microsoft 365 para exibir essa opção.
Observação
O upload personalizado do aplicativo é necessário para visualizar e testar aplicativos no ambiente local do Teams. Habilite o upload do aplicativo para visualizar e testar seu aplicativo no Teams localmente.
Você já tem um locatário e tem acesso ao administrador? Vamos marcar se você realmente fizer isso!
Para verificar aplicativos de carregamento personalizados no Teams:
No cliente do Teams, selecione o ícone Aplicativos .
Selecione Gerenciar seus aplicativos.
Selecione Carregar um aplicativo
Procure a opção Carregar um aplicativo personalizado. Se você vir a opção, o upload de aplicativo personalizado estará habilitado.
Observação
Entre em contato com o administrador do Teams, se você não tiver a opção de carregar um aplicativo personalizado.
Create um locatário gratuito do desenvolvedor do Teams (opcional)
Se você não tiver uma conta de desenvolvedor do Teams, poderá obtê-la gratuitamente. Ingresse no programa de desenvolvedor do Microsoft 365!
Selecione Ingressar Agora e siga as instruções na tela.
Na tela de boas-vindas, selecione Configurar assinatura E5.
Configure uma conta de administrador. Depois de concluir, a tela a seguir será exibida.
Entre no Teams usando a nova conta de administrador que você acabou de configurar. Verifique se você tem a opção Carregar um aplicativo personalizado no Teams.
Configurar o ambiente local
Selecione Código.
No menu suspenso, selecione Abrir com o GitHub Desktop.
Selecione Clonar.
Registrar Microsoft Entra aplicativo
As seguintes etapas ajudam você a criar e registrar seu bot no portal do Azure:
- Create e registre seu aplicativo do Azure.
- Create segredo do cliente para habilitar a autenticação SSO do bot.
- Adicione o canal do Teams para implantar o bot.
- Create um túnel para os pontos de extremidade do servidor Web usando túnel de desenvolvimento (recomendado) ou ngrok.
- Adicione o ponto de extremidade de mensagens ao túnel de desenvolvimento que você criou.
Adicionar registro de aplicativo
Acesse o portal do Azure.
Selecione Registros de aplicativos.
Selecione + Novo registro.
Insira o nome do seu aplicativo.
Selecione Contas em qualquer diretório organizacional (Qualquer locatário Microsoft Entra ID – Multilocatário).
Selecione Registrar.
Seu aplicativo está registrado em Microsoft Entra ID. A página de visão geral do aplicativo é exibida.
Observação
Salve a ID do aplicativo da ID do Aplicativo (cliente) e da ID do Diretório (locatário) para uso adicional.
Create um túnel
Abra o Visual Studio.
Selecione Create um novo projeto.
Na caixa de pesquisa, insira ASP.NET. Nos resultados da pesquisa, selecione ASP.NET Core Aplicativo Web.
Selecione Avançar.
Insira o nome do projeto e selecione Avançar.
Selecione Criar.
Uma janela de visão geral é exibida.
Na lista suspensa de depuração, selecione Túneis de Desenvolvimento (nenhum túnel ativo)>Create um túnel....
Uma janela pop-up será exibida.
Atualize os seguintes detalhes na janela pop-up:
- Conta: insira uma conta Microsoft ou GitHub.
- Nome: insira um nome para o túnel.
- Tipo de túnel: na lista suspensa, selecione Temporário.
- Acesso: Na lista suspensa, selecione Público.
Clique em OK.
Uma janela pop-up aparece mostrando que o túnel de desenvolvimento foi criado com êxito.
Clique em OK.
Você pode encontrar o túnel que você criou na lista suspensa de depuração da seguinte maneira:
Selecione F5 para executar o aplicativo no modo de depuração.
Se uma caixa de diálogo Aviso de Segurança for exibida, selecione Sim.
Uma janela pop-up será exibida.
Selecione Continuar.
A página inicial do túnel de desenvolvimento é aberta em uma nova janela do navegador e o túnel de desenvolvimento agora está ativo.
Vá para o Visual Studio, selecione Exibir > Saída.
No menu suspenso Do console de saída , selecione Túneis de Desenvolvimento.
O console de saída mostra a URL do túnel de desenvolvimento.
Adicionar uma autenticação da Web
No painel esquerdo, em Gerenciar, selecione Autenticação.
Selecione Adicionar uma Web de plataforma>.
Insira o URI de redirecionamento para seu aplicativo acrescentando
auth-endao nome de domínio totalmente qualificado. Por exemplo:https://your-devtunnel-domain/auth-endouhttps://your-ngrok-domain/auth-end.Em Concessão implícita e fluxos híbridos, selecione as caixas de seleção Tokens de acesso e tokens de ID .
Selecione Configurar.
Na Web, selecione Adicionar URI.
Digite
https://token.botframework.com/.auth/web/redirect.Selecione Salvar.
Criar um segredo do cliente
No painel esquerdo, em Gerenciar, selecione Certificados & segredos.
Em Segredos do cliente, selecione + Novo segredo do cliente.
A janela Adicionar um segredo do cliente é exibida.
Insira Descrição.
Selecione Adicionar.
Em Valor, selecione Copiar para área de transferência para salvar o valor de segredo do cliente para uso adicional.
Adicionar permissões de API
No painel esquerdo, selecione permissões de API.
Selecione + Adicionar uma permissão.
Selecione Microsoft Graph.
Selecione Permissões delegadas.
SelecioneUser.Read>.
Selecione Adicionar permissões.
Observação
Se um aplicativo não tiver o consentimento do administrador de TI, os usuários deverão fornecer consentimento na primeira vez que usarem um aplicativo. Os usuários precisam consentir com as permissões de API somente se o aplicativo Microsoft Entra estiver registrado em um locatário diferente.
URI da ID do Aplicativo
No painel esquerdo, em Gerenciar, selecione Expor uma API.
Ao lado do URI da ID do Aplicativo, selecione Adicionar.
Atualize o URI da ID do Aplicativo no
api://botid-{AppID}formato e selecione Salvar.
Adicionar um escopo
No painel esquerdo, em Gerenciar, selecione Expor uma API.
Selecione + Adicionar um escopo.
Insira access_as_user como o nome escopo.
Em Quem pode consentir?, selecione Administradores e usuários.
Atualize os valores para o restante dos campos da seguinte maneira:
O Enter Teams pode acessar o perfil do usuário como Administração nome de exibição de consentimento.
Insira Permitir que o Teams chame as APIs Web do aplicativo como o usuário atual como Administração descrição de consentimento.
O Enter Teams pode acessar o perfil do usuário e fazer solicitações em nome do usuário como nome de exibição de consentimento do usuário.
Insira Habilitar o Teams para chamar as APIs deste aplicativo com os mesmos direitos que o usuário que adescrição do consentimento do usuário.
Verifique se o Estado está definido como Habilitado.
Selecione Adicionar escopo.
A imagem a seguir mostra os campos e os valores:
Observação
O nome escopo deve corresponder ao URI da ID do Aplicativo com
/access_as_useracrescentado no final.
Adicionar aplicativo cliente
No painel esquerdo, em Gerenciar, selecione Expor uma API.
Em Aplicativos cliente autorizados, identifique os aplicativos que você deseja autorizar para o aplicativo Web do aplicativo.
Selecione + Adicionar um aplicativo cliente.
Adicione o aplicativo Web do Teams para dispositivos móveis ou desktop e teams.
Para o teams móvel ou área de trabalho: insira a ID do cliente como
1fec8e78-bce4-4aaf-ab1b-5451cc387264.
Para o Teams Web: insira a ID do cliente como
5e3ce6c0-2b1f-4285-8d4b-75ee78787346.
Selecione a caixa de seleção Escopos autorizados .
Selecione Adicionar aplicativo.
A imagem a seguir exibe a ID do cliente:
Atualizar o manifesto
No painel esquerdo, selecione Manifesto.
Defina o valor para o
accessTokenAcceptedVersionpara2e selecione Salvar.
Create seu bot
Create um recurso de bot do Azure
Observação
Se você já estiver testando seu bot no Teams, saia deste aplicativo e do Teams. Para ver essa alteração, entre novamente.
Vá para a Página Inicial.
Selecione + Create um recurso.
Na caixa de pesquisa, insira o Bot do Azure.
Selecione Enter.
Selecione Bot do Azure.
Selecione Criar.
Insira o nome do bot no identificador do Bot.
Selecione sua Assinatura na lista suspensa.
Selecione seu Grupo de recursos na lista suspensa.
Se você não tiver um grupo de recursos existente, poderá criar um novo grupo de recursos. Para criar um novo grupo de recursos, siga estas etapas:
- Selecione Create novo.
- Insira o nome do recurso e selecione OK.
- Selecione um local na lista suspensa Local do novo grupo de recursos .
Em Preços, selecione Alterar plano.
Selecione FO Free>Select.
Em ID do Aplicativo Microsoft, selecione Tipo de Aplicativo como Vários Locatários.
No tipo Criação, selecione Usar o registro de aplicativo existente.
Insira a ID do aplicativo.
Observação
Você não pode criar mais de um bot com a mesma ID do Aplicativo Microsoft.
Selecione Rever + criar.
Depois que a validação for aprovada, selecione Create.
O bot leva alguns minutos para provisionar.
Selecione Vá para o recurso.
Você criou com êxito seu bot do Azure.
Adicionar um canal do Teams
No painel esquerdo, selecione Canais.
Em Canais Disponíveis, selecione Microsoft Teams.
Selecione a caixa de seleção para aceitar os Termos de Serviço.
Selecione Concordar.
Selecione Aplicar.
Para adicionar um ponto de extremidade de mensagens
Use a URL do túnel de desenvolvimento no console de saída como o ponto de extremidade de mensagens.
No painel esquerdo, em Configurações, selecione Configuração.
Atualize o ponto de extremidade mensagens no formato
https://your-devtunnel-domain/api/messages.
Selecione Aplicar.
Você configurou com êxito um bot no serviço de Bot do Azure.
Observação
Se a chave instrumentação do Application Insights mostrar um erro, atualize com a ID do aplicativo.
Adicionar uma configuração de conexão OAuth
No painel esquerdo, selecione Configuração.
Selecione Adicionar configurações de conexão OAuth.
Em Nova Configuração de Conexão, atualize os seguintes detalhes:
- Nome: insira um nome para sua nova configuração de conexão. Você pode usar o nome nas configurações do código do serviço de bot.
- Provedor de Serviços: na lista suspensa, selecione Azure Active Directory v2.
- ID do cliente: atualize sua ID do Aplicativo Microsoft.
- Segredo do cliente: atualize o valor dos segredos do cliente.
- URL do Token Exchange: atualize o URI da ID do Aplicativo.
- ID do locatário: Insira Common.
- Escopos: InsiraUser.Read.
Selecione Salvar.
Configurar configurações de aplicativo e arquivos de manifesto
Vá para o arquivo appsettings.json no repositório clonado.
Abra o arquivo appsettings.json e atualize as seguintes informações:
- Defina
"MicrosoftAppId"como a ID do aplicativo Microsoft do bot. - Defina
"MicrosoftAppPassword"como o valor da ID secreta do cliente do bot. - Defina
ConnectionNamecomo nome de conexão OAuth. - Defina
"MicrosoftAppType"como MultiTenant. - Defina
"MicrosoftAppTenantId"como comum.
- Defina
Vá para o arquivo manifest.json no repositório clonado.
Abra o arquivo manifest.json e atualize as seguintes alterações:
- Substitua todas as ocorrências de por sua ID do
"{TODO: MicrosoftAppId}"Aplicativo Microsoft. - Defina
"<<domain-name>>"como seu domínio de túnel ngrok ou dev.
- Substitua todas as ocorrências de por sua ID do
Compilar e executar o serviço
Abra o Visual Studio.
Vá para Arquivo>Abrir>Projeto/Solução....
Na pasta bot-conversation-sso-quickstart>csharp_dotnetcore e selecione BotConversationSsoQuickstart.sln arquivo.
Selecione F5 para executar o projeto.
Se uma caixa de diálogo Aviso de Segurança for exibida, selecione Sim.
Uma página da Web é aberta com uma mensagem Seu bot está pronto!.
Solucionando problemas
Se você receber o erro De não localizar o pacote , siga estas etapas:
- Acesse Ferramentas Configurações> doGerenciador de Pacotes> doNuGetPackage Manager.
- Na janela Opções exibida, selecioneFontes de Pacote do Gerenciador de Pacotes> do NuGet.
- Selecione Adicionar.
- Em Nome, insira
nuget.orge na Origem, insirahttps://api.nuget.org/v3/index.json. - Selecione Atualizar e OK.
- Recompile seu projeto.
Carregar o bot no Teams
Em seu repositório clonado, acesse Exemplos do Microsoft-Teams-Samples>>bot-conversation-sso-quickstart>csharp_dotnetcore>BotConversationSsoQuickstart.
Create um arquivo .zip com os seguintes arquivos presentes na pasta appPackage:
- manifest.json
- outline.png
- color.png
Acesse o Microsoft Teams.
No cliente do Teams, selecione Aplicativos.
Selecione Gerenciar seus aplicativos.
Selecione Carregar um aplicativo.
Procure a opção para Carregar um aplicativo personalizado.
Selecione Abrir para carregar o arquivo .zip que você criou na pasta Manifesto .
Selecione Adicionar para adicionar o bot ao chat.
Você pode interagir com o bot enviando-lhe uma mensagem. O bot troca um token SSO e chama o API do Graph em seu nome. Ele mantém você conectado, a menos que você envie uma mensagem para sair.
Envie uma mensagem para o bot. O bot de conversa pede consentimento pela primeira vez.
Para área de trabalho: selecione Continuar para dar permissões ao cliente do Teams para acessar o bot.
Observação
Agora você configurou o SSO com seu aplicativo bot e é a única vez que você terá que dar consentimento.
Para celular: selecione Aceitar.
Observação
Agora você configurou o SSO com seu aplicativo bot no celular e é a única vez que você terá que dar consentimento.
Desafio completo
Você veio com algo assim?
Parabéns!
Você concluiu o tutorial para começar a criar um bot com autenticação SSO.
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de