Criar um bot com autenticação de SSO
Os bots do Teams são bots de conversa que executam tarefas automatizadas repetitivas realizadas pelos usuários, como o atendimento ao cliente. O usuário precisa entrar várias vezes sem autenticação de SSO (logon único). Com os métodos de autenticação de SSO, os usuários não precisam entrar no bot várias vezes.
Um bot se comporta de maneira diferente, dependendo da conversa em que ele está envolvido:
- Os bots em conversas de chat em grupo e canal exigem que os usuários @mention o bot.
- Bots em uma conversa privada não exigem uma @menção. Todas as mensagens enviadas pelo usuário são roteadas para o bot.
Este guia passo a passo ajuda você a criar um bot com autenticação de SSO. Você verá a seguinte saída:
Pré-requisitos
Instale as seguintes ferramentas e configure seu ambiente de desenvolvimento:
Versão mais recente do ngrok ou qualquer solução de túnel equivalente
Observação
Depois de baixar o ngrok, inscreva-se e instale o authtoken.
Verifique se você tem as seguintes contas e configure seu ambiente de desenvolvimento:
-
Dica
Verifique se a conta do Microsoft Teams não é uma conta de convidado.
Conta de desenvolvedor do Microsoft 365 ou acesso à conta do Teams com as permissões apropriadas para instalar um aplicativo
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 realizar o sideload e testar o aplicativo.
Verificar a opção de sideload
Depois de criar o aplicativo, você deve carregar seu aplicativo no Teams sem distribuí-lo. Isso é conhecido como sideload. Entre em sua conta do Microsoft 365 para exibir essa opção.
Observação
O sideload é necessário para visualizar e testar aplicativos no ambiente local do Teams. Habilite o Sideload para visualizar e testar seu aplicativo no Teams localmente.
Você já tem um locatário e tem acesso de administrador? Vamos verificar se você realmente faz!
Para verificar o sideload de aplicativos no Teams:
No cliente do Teams, selecione Loja.
Selecione Gerenciar seus aplicativos.
Selecione Publicar um aplicativo.
Procure a opção para carregar um aplicativo personalizado. Se você vir a opção, o sideload de aplicativos 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.
Criar um locatário de desenvolvedor gratuito do Teams (opcional)
Se você não tiver uma conta de desenvolvedor do Teams, poderá obtê-la gratuitamente. Participe do programa de desenvolvedor do Microsoft 365!
Selecione Ingressar Agora e siga as instruções na tela.
Selecione Configurar assinatura do E5 na tela de boas-vindas.
Configurar conta de administrador. Depois de concluir, a tela a seguir será exibida.
Entre no Teams usando a nova conta de administrador. Agora você deve ter a opção Carregar um aplicativo personalizado.
Criar e registrar seu bot
As etapas a seguir ajudam você a criar e registrar seu bot portal do Azure:
- Crie um recurso de Bot do Azure para registrar o bot no Azure Serviço de Bot.
- Crie o segredo do cliente para habilitar a autenticação de SSO do bot.
- Adicione o canal do Teams para implantar o bot.
- Use o ngrok para criar um túnel para os pontos de extremidade do servidor Web.
- Adicione o ponto de extremidade de mensagens ao túnel ngrok que você criou.
Para criar um recurso de Bot do Azure
Acesse o Portal do Azure. Ele pode solicitar que você entre com suas credenciais de conta da Microsoft.
Selecione Criar um recurso.
Na caixa de pesquisa, insira o bot do Azure.
Selecione Enter.
Selecione o Bot do Azure.
Selecionar Criar.
A página Criar um Bot do Azure é exibida.
Insira os detalhes a seguir para criar o bot do Azure.
Insira o nome do identificador do bot necessário no identificador do Bot e ele é um identificador exclusivo para o bot.
Selecione sua Assinatura na lista suspensa.
Selecione o grupo de recursos na lista suspensa que você deseja provisionar para seu aplicativo de bot.
Você também pode criar um novo grupo de recursos seguindo as seguintes etapas:
Para criar um novo grupo de recursos, selecione Criar > insira o nome do recurso > selecione OK.
Se você tiver criado um novo grupo de recursos, selecione o local necessário na lista suspensa Novo local do grupo de recursos.
Selecione o tipo de aplicativo como multilocatário.
Na seção ID do Aplicativo da Microsoft , por padrão , a opção Criar nova ID de Aplicativo da Microsoft está selecionada.
Você pode selecionar Usar o registro de aplicativo existente e inserir a ID do aplicativo existente e a senha do aplicativo existente ou selecionar Criar nova ID de Aplicativo da Microsoft.
Observação
Não é possível criar mais de um bot com a mesma ID do Aplicativo da Microsoft.
Selecione Rever + criar.
Depois que a validação for aprovada, selecione Criar.
Leva alguns instantes para que o serviço de bot seja provisionado e a seguinte página seja exibida:
Selecione Vá para o recurso.
Seu bot do Azure é criado e você pode ver o grupo de recursos e a ID da assinatura no bot do Azure.
Para criar o segredo do cliente
Execute as seguintes etapas para criar o segredo do cliente:
No painel esquerdo, selecione Configuração.
Importante
Salve a ID do Aplicativo da Microsoft ou a ID do Cliente para referência futura.
Ao lado da ID do Aplicativo da Microsoft, selecione Gerenciar.
Na seção Segredos do cliente , selecione Novo segredo do cliente.
A janela Adicionar um segredo do cliente é exibida.
Insira Descrição.
Selecione Adicionar.
Na coluna Valor , selecione Copiar para área de transferência.
Importante
Salve o valor de segredos do cliente ou a senha do aplicativo para referência futura.
Adicionar bot ao canal do Teams
Selecione Início.
Selecione seu bot de recursos recentes.
Selecione Canais no painel esquerdo e selecione Teams
.
Selecionar o Microsoft Teams
.
Marque a caixa de seleção para aceitar os Termos de Serviço.
Selecione Concordar.
Selecione Aplicar.
Para criar um túnel para o servidor Web local
Use o ngrok para criar um túnel para os pontos de extremidade HTTPS disponíveis publicamente do servidor Web em execução localmente. Execute o seguinte comando no ngrok:
ngrok http -host-header=localhost 3978
Dica
Se você encontrar ERR_NGROK_4018, siga as etapas, conforme exibido no prompt de comando para se inscrever e autenticar o ngrok. Em seguida, execute o ngrok http -host-header=localhost 3978 comando.
Para adicionar o ponto de extremidade de mensagens
No ngrok, copie a URL HTTPS.
Observação
A URL HTTPS em seu ngrok é seu nome de domínio totalmente qualificado. É
WebAppDomainum nome de domínio totalmente qualificado que não incluihttps://nele.Voltar à portal do Azure.
Em Configurações do bot do Azure que você criou, selecione Configuração.
No ponto de extremidade de Mensagens, use a URL HTTPS disponível no ngrok e, no final da URL, adicione /api/messages.
Selecione Aplicar.
Você configurou com êxito um bot no Azure Serviço de Bot.
Configurar o SSO para o bot
Para adicionar o URI de redirecionamento ao recurso de bot do Azure
Selecione Gerenciar.
No painel esquerdo, selecione Autenticação.
Em Configurações de plataforma, selecione Adicionar uma plataforma para escolher a plataforma na qual você deseja hospedar o aplicativo de bot.
Para este tutorial, selecione Web.
Insira URIs de Redirecionamento como
https://token.botframework.com/.auth/web/redirecte esse é o URI no qual Azure AD enviará resposta para autenticação do usuário.
Habilite a concessão implícita e os fluxos híbridos selecionando as seguintes caixas de seleção:
- Tokens de ID
- Tokens de acesso
Selecione Configurar.
O URI de redirecionamento é adicionado ao recurso de bot do Azure.
Para expor o ponto de extremidade da API
No painel esquerdo, selecione Expor uma API.
Selecione Definir.
Use o URI da ID do aplicativo mostrado e acrescente api://botid- no início do URI.
Selecione Salvar.
Importante
Salve o URI da ID do Aplicativo para referência futura.
Selecione Adicionar um escopo.
Adicionar um painel de escopo é exibido.
Insira os detalhes para configurar o escopo.
Insira
access_as_usercomo o Nome do Escopo.Observação
O nome do escopo deve corresponder ao URI da ID do Aplicativo
/access_as_usercom acrescentado no final.Definir Quem pode consentir? para
Admins and users.Para configurar os prompts de consentimento do administrador e do usuário com os valores apropriados para
access_as_usero escopo, forneça as seguintes informações nos campos:Insira
Teams can access the user’s profilecomo Administração de exibição de consentimento.Insira
Allows Teams to call the app’s web APIs as the current usercomo Administração de consentimento.Insira como
Teams can access the user profile and make requests on the user’s behalfnome de exibição de consentimento do usuário.Insira como
Enable Teams to call this app’s APIs with the same rights as you havedescrição de consentimento do usuário.
Verifique se o Estado está definido como Habilitado.
Selecione Adicionar escopo para salvar.
O URI da ID do aplicativo é criado com o nome do escopo.
Na seção Aplicativos cliente autorizados, identifique os aplicativos que você deseja autorizar para o aplicativo Web do seu aplicativo.
Selecione Adicionar um aplicativo cliente.
Adicionar um painel de aplicativo cliente é exibido.
Insira a ID do Cliente para a área de trabalho e o aplicativo Web separadamente que você deseja autorizar. É a ID do aplicativo cliente que você deseja autorizar.
ID do cliente Para autorizar 1fec8e78-bce4-4aaf-ab1b-5451cc387264Aplicativo móvel ou da área de trabalho do Teams 5e3ce6c0-2b1f-4285-8d4b-75ee78787346Aplicativo Web do Teams. Selecione escopos autorizados para determinar qual tipo de token será retornado pelo serviço.
Selecione Adicionar aplicativo.
A imagem a seguir exibe a ID do Cliente:
Configurar permissões do Graph
No painel esquerdo, selecione Permissões de API.
Observação
Os usuários precisam consentir com as permissões de API somente se o aplicativo de bot estiver registrado em um locatário diferente.
Selecione Adicionar uma permissão.
A página solicitar permissão de API é exibida:
Selecione Microsoft Graph.
Selecione Permissões delegadas.
Selecione a permissão User.Read na lista suspensa Usuário.
Selecione Adicionar permissões.
Para atualizar o manifesto
No painel esquerdo, selecione Manifesto.
Verifique se o item de configuração está definido como "accessTokenAcceptedVersion": 2. Caso contrário, altere seu valor para 2 e selecione Salvar.
Observação
Se você já estiver testando seu bot no Teams, deverá sair deste aplicativo e do Teams. Em seguida, entre novamente para ver essa alteração.
Para configurar a conexão de serviço de Bot
Na página Configuração, selecione Adicionar Configurações de Conexão OAuth.
Na página Nova Configuração de Conexão, insira os seguintes detalhes:
Campo Valor ou descrição Nome Insira o nome da nova configuração de conexão. Você pode usar o nome nas configurações do código do serviço de bot. Service Provider Selecione O Azure Active Directory V2. ID do cliente Salvo anteriormente como sua ID de Aplicativo da Microsoft. Segredo do cliente Salvo anteriormente como Valor da ID do segredo do cliente. URL do Exchange de Tokens Use a URL da ID do Aplicativo obtida anteriormente ao expor o ponto de extremidade da API. ID do locatário Insira comum. Scopes Insira User.Read e também adicione todos os Escopos necessários ao especificar permissões para APIs downstream. Selecione Salvar.
Selecione Aplicar.
Agora você configurou o SSO para seu bot.
Configurar e executar o exemplo de bot
Abra o Visual Studio.
Selecione Clonar um repositório.
No local do repositório, insira
https://github.com/OfficeDev/Microsoft-Teams-Samples.git. Certifique-se de observar o caminho em que o repositório é clonado.Navegue até o projeto > /solução de > abertura de arquivo.
Selecione o arquivo BotSSOCSharp.csproj csharp_dotnetcore pasta.
Abra o arquivo appsettings.json .
Atualize a configuração de appsettings.json para que o bot use e
MicrosoftAppIdMicrosoftAppPassword. Use o nome da conexão OAuth como o Nome da Conexão.Observação
Você pode obter a partir
MicrosoftAppIdda página configuração do bot. OMicrosoftAppPasswordvalor da ID de segredo do cliente que você salvou anteriormente no Azure.
Selecione F5 para executar o projeto.
Selecione Sim se a caixa de diálogo a seguir for exibida:
Uma página da Web é aberta com uma mensagem que o Bot está pronto.
Solução de Problemas
Se você receber o erro Não é possível localizar o pacote, siga estas etapas:
- Vá para Configurações do Gerenciador > de Pacotes do Gerenciador de Pacotes > nuGet de ferramentas.
- Na janela Opções exibida, selecione Fontes de Pacote do Gerenciador de Pacotes > nuGet .
- Selecione Adicionar.
- Em Nome, insira
nuget.orge em Origem, insirahttps://api.nuget.org/v3/index.json. - Selecione Atualizar e OK.
- Recompile seu projeto.
Configurar e executar o aplicativo Teams
No Visual Studio, abra a pasta appPackage .
Abra o arquivo manifest.json .
Substitua todas as ocorrências de {TODO: MicrosoftAppId} pela ID do aplicativo Microsoft do bot.
No repositório clonado, navegue até bot-conversation-sso-quickstart > csharp_dotnetcore > pasta appPackage .
Crie um .zip com os seguintes arquivos que estão presentes na pasta Manifesto :
- manifest.json
- icon-outline.png
- icon-color.png
Vá para o cliente do Teams.
Selecione Repositório.
Selecione Gerenciar seus aplicativos.
Selecione Fazer o upload de um aplicativo personalizado.
Selecione Abrir para carregar .zip arquivo que você criou na pasta Manifesto .
Selecione Adicionar para adicionar o bot de conversa ao chat.
Você pode interagir com o bot enviando uma mensagem. O bot troca um token de 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 solicita consentimento pela primeira vez.
Selecione Continuar para conceder permissões ao cliente do Teams para acessar o bot.
Observação
Agora você configurou o SSO com seu aplicativo de bot e é a única vez que você precisará dar consentimento.
Para dispositivo móvel, selecione Aceitar permissões solicitadas.
Observação
Agora você configurou o SSO com seu aplicativo de bot no celular e é a única vez que você terá que dar consentimento.
Desafio completo
Você conseguiu algo assim?
Parabéns!
Você concluiu o tutorial para começar a criar um bot com autenticação de SSO.
Tem algum problema com essa seção? Se tiver, envie seus comentários para que possamos melhorar esta seção.