Adicionar autenticação de usuário final a um copiloto

Importante

As capacidades e os recursos do Power Virtual Agents agora fazem parte do Microsoft Copilot Studio após investimentos significativos em IA generativa e integrações aprimoradas no Microsoft Copilot.

Alguns artigos e capturas de tela podem fazer referência ao Power Virtual Agents enquanto atualizamos a documentação e o conteúdo do treinamento.

Você pode habilitar a autenticação do usuário diretamente de uma conversa do copiloto. A autenticação do usuário significa que você pode obter as propriedades básicas de um usuário, como nome e ID em variáveis, mas também solicitar que um usuário faça logon usando um nó de autenticação, recupere um token de usuário para esse usuário e use esse token para recuperar as informações do usuário por meio de um sistema de back-end.

Observação

Copilotos criados no aplicativo Web e, no Microsoft Teams, acompanham autenticação pré-configurada para usar a autenticação Somente para Teams e Power Apps.

Você também pode configurar o logon único (SSO) para que seus usuários não precisem fazer logon manualmente. Para obter mais informações, consulte Configurar SSO para a Web.

Pré-requisitos

• Usar variáveis
• Configurar a autenticação de usuário final.

Aplicativo Web

Adicione a autenticação do usuário a um tópico para permitir que os clientes entrem diretamente em uma conversa. Você pode personalizar a conversa com as variáveis do usuário e acessar sistemas de back-end em nome do usuário.

Configurar autenticação manual com o Microsoft Entra ID

Você precisa configurar a autenticação do usuário com Microsoft Entra ID antes de poder usar a autenticação em seus tópicos.

1. Siga as instruções em Configurar autenticação do usuário com o Microsoft Entra ID.
2. Retorne a este artigo.

Adicionar a autenticação do usuário com o tópico do sistema Entrar

Quando você cria um copiloto, o Microsoft Copilot Studio adiciona automaticamente um tópico do sistema chamado Entrar. Para usá-lo, você deve definir a autenticação do copiloto como manual e exigir que os usuários entrem. Quando um cliente inicia uma conversa com o copiloto, o tópico Entrar é disparado e solicita que o usuário entre. Você pode personalizar o tópico Entrar conforme apropriado para seu copiloto.

1. No menu de navegação, em Configurações, selecione Segurança.

2. Selecione o bloco Autenticação.

3. Selecione Manual (para site personalizado) e selecione Exigir que os usuários façam login.

   

   

Adicionar autenticação de usuário com um tópico personalizado

O tópico Entrar autentica o usuário no início da conversa. Para permitir que o usuário faça login posteriormente, você pode adicionar um nó Autenticar a qualquer tópico personalizado.

Quando os clientes inserem o nome de usuário e a senha, eles poderão ser solicitados a inserir um código de validação. Depois que fizerem login, eles não serão solicitados novamente, mesmo que cheguem até outro nó Autenticar.

1. No menu de navegação, em Configurações, selecione Segurança.

2. Selecione o bloco Autenticação.

3. Desative Exigir que os usuários entrem.

4. No menu de navegação superior, selecione Tópicos e, em seguida, selecione o tópico para o qual você adicionar a autenticação.

5. Selecionar Adicionar nó (+), selecione Chamar uma ação e, em seguida, selecione Autenticar.

6. Teste seu tópico com um usuário configurado com seu provedor de identidade.

Gorjeta

É importante que você crie caminhos para login bem-sucedido e falha no login. Pode haver falha no login por vários motivos, incluindo erros com a experiência de entrada do provedor de identidade.

Variáveis de autenticação

Depois de configurar a autenticação do usuário para o copiloto, você poderá usar as variáveis de autenticação nos tópicos. A tabela a seguir compara a disponibilidade dessas variáveis com base na opção de autenticação que você escolheu.

Variável de autenticação	Sem autenticação	Somente para o Teams e o Power Apps	Manual
User.DisplayName	não disponível	disponível	disponível
User.FirstName	não disponível	disponível	disponível
User.LastName	não disponível	disponível	disponível
User.PrincipalName	não disponível	disponível	disponível
User.Email	não disponível	disponível	disponível
User.Id	não disponível	disponível	disponível
User.IsLoggedIn	não disponível	disponível	disponível
User.AccessToken	não disponível	não disponível	disponível
SignInReason	não disponível	disponível	disponível

User.DisplayName

Aviso

Não há garantia de que esta variável contenha um valor. Teste com um usuário do seu provedor de identidade para garantir que seu tópico funcione corretamente.

A variável User.DisplayName contém o nome de exibição que é armazenado no provedor de identidade. Use essa variável para saudar ou consultar o usuário final sem que ele tenha que fornecer seu nome explicitamente ao copiloto, tornando a conversa mais personalizada.

O Microsoft Copilot Studio define automaticamente o valor de User.DisplayName da reivindicação name fornecida pelo provedor de identidade, desde que o escopo profile tenha sido definido quando a autenticação manual foi configurada. Para obter mais informações sobre o escopo, consulte Configurar autenticação de usuário com o Microsoft Entra ID.

User.Id

Aviso

Não há garantia de que esta variável contenha um valor. Teste com um usuário do seu provedor de identidade para garantir que seu tópico funcione corretamente.

A variável User.Id contém o ID do usuário que está armazenado no provedor de identidade. Use essa variável em fluxos do Power Automate para chamar APIs que usam a UserID como um valor.

O Microsoft Copilot Studio define automaticamente o valor de User.DisplayName com base na declaração sub do provedor de identidade.

User.IsLoggedIn

User.IsLoggedIn é uma variável do tipo booliano que armazena o status de entrada do usuário. Um valor true indica que o usuário está conectado. Você pode usar essa variável para criar lógica de ramificação nos seus tópicos que verifica se há uma entrada com êxito ou buscar informações do usuário somente se o usuário estiver conectado.

User.AccessToken

Aviso

Certifique-se de passar a variável User.AccessToken apenas para fontes confiáveis. Ele contém informações de autenticação do usuário que, se comprometidas, podem prejudicar o usuário.

A variável User.AccessToken contém o token do usuário, obtido após a entrada do usuário. Você pode passar essa variável para fluxos do Power Automate para que eles possam se conectar a APIs de back-end e buscar informações do usuário ou executar ações em nome do usuário.

Não use User.AccessToken dentro dos nós Mensagem ou em fluxos nos quais você não confia.

SignInReason

SignInReason é uma variável do tipo escolha que indica quando o usuário deve entrar. Ela tem dois possíveis valores:

• SignInRequired indica que o usuário deve entrar no início da conversa usando o tópico do sistema Entrar. Exigir que os usuários entrem deve ser ativado.

• Initializer indica que, se o usuário ainda não tiver entrado e chegar a um ponto na conversa que use variáveis de autenticação, ele será solicitado a entrar.

Clássico

Variáveis de autenticação

Se o bot estiver configurado com as opções de autenticação Somente para Teams e Power Apps ou Manual, você terá um conjunto de variáveis da autenticação disponíveis nos tópicos. Verifique a documentação de configuração de autenticação para obter mais informações sobre como configurar a autenticação em seu bot.

A tabela a seguir compara a disponibilidade da variável de autenticação por opção de configuração de autenticação:

Variável de autenticação	Sem autenticação	Somente para o Teams e o Power Apps	Manual
UserDisplayName	❌	✔️	✔️
UserID	❌	✔️	✔️
IsLoggedIn	❌	❌	✔️
AuthToken	❌	❌	✔️

Variável UserDisplayName

A variável UserDisplayName contém o nome de exibição do usuário armazenado no provedor de identidade. Você pode usar essa variável para saudar ou consultar o usuário final sem que ele tenha que manifestar isso explicitamente ao bot, tornando-o mais personalizado.

Esse valor de campo é obtido por meio da declaração do Microsoft Entra ID name. Para provedores OAuth, esse é o valor armazenado na declaração name. Como o Microsoft Copilot Studio extrai automaticamente esse campo para a variável, certifique-se de ter profile como parte de sua configuração de escopo de autenticação.

Variável UserID

A variável UserID contém a ID do usuário armazenado no provedor de identidade. Esse valor pode ser usado pelos fluxos do Power Automate para chamar APIs que usam a UserID como um valor. Esse valor de campo é obtido por meio da declaração do Microsoft Entra ID sub. Para provedores OAuth, esse é o valor armazenado na declaração sub. O Microsoft Copilot Studio extrai automaticamente esse campo para a variável.

Aviso

As variáveis UserDisplayName e UserID não têm garantia de preenchimento e podem ser cadeias de caracteres vazias dependendo da configuração do usuário no provedor de identidade. Teste com um usuário de seu provedor de identificação para garantir que seus tópicos funcionem corretamente, mesmo se essas variáveis estiverem vazias.

Variável IsLoggedIn

O IsLoggedIn variável indica se o usuário está conectado (seja como resultado de entrar ou de já estar conectado, também conhecido como caminho de logon com êxito) ou não conectado (o que resultaria no caminho de falha de logon).

IsLoggedIn é uma variável do tipo booliano que contém o status de entrada do usuário. Você pode usar essa variável para criar lógica de ramificação em seus tópicos que verifica se há uma entrada bem-sucedida (por exemplo, no modelo já fornecido como parte da adição do nó Autenticar) ou buscar oportunamente informações do usuário apenas se o usuário estiver conectado.

Variável AuthToken

A variável AuthToken contém o token do usuário, obtido após a entrada do usuário. Você pode passar essa variável para fluxos do Power Automate para que eles possam se conectar a APIs de back-end e buscar as informações do usuário ou executar ações em nome do usuário.

Aviso

Certifique-se de passar a variável AuthToken apenas para fontes confiáveis. Ele contém informações de autenticação do usuário que, se comprometidas, podem prejudicar o usuário.

Não use AuthToken dentro de nós Mensagem ou em fluxos nos quais você não confia.

Testando variáveis de autenticação

Por padrão, o painel Bot de teste usará a conta do usuário atualmente conectado para preencher as variáveis UserDisplayName eUserID. No entanto, ao testar tópicos que usam autenticação, você tem a opção de usar outros valores para essas variáveis (ou até mesmo um valor em branco).

Por exemplo, você pode querer testar como os caracteres especiais são usados ou o que acontece se a variável estiver vazia.

Isso se aplica apenas ao painel Bot de teste; você não pode usar os comandos descritos nesta seção em um bot publicado implantado em um canal.

A tabela a seguir lista os comandos que preencherão essas variáveis. Digite o comando no painel Bot de teste da mesma forma que faria se estivesse conversando normalmente com o bot. Você receberá uma mensagem de confirmação do bot se for bem-sucedido. Se o seu bot não usar autenticação, você receberá um erro.

Se você redefinir o painel Bot de teste (ou fizer alterações em um tópico que faça o Bot de teste ser redefinido automaticamente), precisará enviar os comandos novamente.

Variável	Comando de valor personalizado	Comando de valor vazio (em branco)
UserDisplayName	/debug set bot.UserDisplayName "Value"	/debug set bot.UserDisplayName ""
UserID	Não disponível	/debug set bot.UserID ""

Importante

Você não pode preencher a variável UserID com um valor personalizado (diferente de um valor vazio ou em branco) devido a razões de segurança.

Autenticação ao usar a configuração "Somente para Teams e Power Apps"

Se a opção de autenticação estiver definida como Somente para Teams e Power Apps, você não precisará adicionar explicitamente autenticação aos tópicos. Nessa configuração, qualquer usuário no Microsoft Teams é conectado automaticamente por meio de suas credenciais do Teams e não precisa entrar explicitamente com um cartão de autenticação. Se sua opção de autenticação estiver definida como Manual, você precisará adicionar o nó de autenticação (mesmo para o canal do Teams).

Observação

Se opção de autenticação estiver definida como Somente para Teams e Power Apps, você não terá a opção de adicionar explicitamente autenticação aos tópicos.

Adicionar autenticação de usuário a um tópico

O nó Autenticar solicitará que um usuário faça logon com um cartão de entrada. Se um usuário já estiver conectado, ele não receberá a solicitação novamente, mesmo que chegue a outro nó Autenticar.

Depois que o usuário digitar seu nome de usuário e senha no prompt (hospedado pelo provedor de identidade), poderá ser solicitado que você digite um código de validação, dependendo do canal. Alguns canais, como o Microsoft Teams, não exigem que o usuário insira um código de validação.

Quando o bot tiver um SSO configurado, o usuário não será solicitado a fazer logon.

Como adicionar um nó Autenticar ao seu tópico:

1. Acesse a página Tópicos do bot que você deseja editar.

2. Abra a Tela de criação do tópico ao qual você deseja adicionar o modelo de autenticação.

   Nota

   Se o bot estiver conectado ao Dynamics 365 Customer Service, o nó Autenticação não poderá fazer parte do caminho da conversa que o bot seguir quando realizar a saudação inicial aos usuários; caso contrário, o cartão de entrada será mostrado duas vezes. Em vez disso, é necessário adicionar o nó Autenticar a outro tópico que é disparado por uma resposta do usuário.

3. Selecione Adicionar nó (+) para adicionar um nó de mensagem. Digite o que o bot deve dizer para indicar que uma experiência de entrada está prestes a ocorrer.

   

4. Abaixo do nó da mensagem, selecione Adicionar nó (+), selecione Chamar uma ação e Autenticar.

   

   Nota

   O nó Autenticar está disponível somente no seletor de ações no final de uma árvore de diálogo (como um nó folha). Não é possível adicioná-lo no meio de um diálogo. Depois de adicioná-lo, é possível adicionar outros nós abaixo dele.

5. Uma vez selecionado, vários novos nós serão adicionados automaticamente. Esses nós incluem um nó pai Autenticar, seguido por nós para um caminho de sucesso e um de falha.

   

Uso de AuthToken sem um nó Autenticar

As variáveis IsLoggedIn e AuthToken estão disponíveis, mesmo se você não usar o modelo fornecido pela entrada de menu Chamar uma ação. Se você passar a variável AuthToken sem primeiro fazer com que o usuário passe pelo nó Autenticar, o usuário será solicitado a entrar nessa etapa.

Passar a variável AuthToken pode ser útil se você sempre esperar que o usuário esteja conectado ou se o usuário estiver sendo redirecionado de um tópico diferente. Sugerimos que você use o modelo fornecido pela entrada Chamar uma ação para tratar casos em que o usuário não consegue entrar.

Nota

Se o usuário sair no meio de uma conversa, será solicitado que você entre novamente se o tópico chegar a um nó que usa a variável AuthToken.

Caminho de êxito

O caminho de êxito equivale a onde IsLoggedIn = True e contas para quando o usuário entrou com êxito (ou já estava conectado).

Se você tiver uma lógica que use a variável AuthToken (por exemplo, para conectar-se a um sistema de back-end usando um fluxo para recuperar as informações de um usuário), ela deverá seguir esse caminho.

Caminho de falha

O caminho da falha equivale a qualquer condição diferente de IsLoggedIn = True. Na maioria dos casos, o caminho de falha ocorre porque o usuário não conseguiu entrar, usou a senha errada ou cancelou a experiência de entrada.

Adicione qualquer lógica que você queira tratar neste caso. Como exemplo, fornecemos opções para tentar novamente ou escalonar para um agente humano. Personalize as ações do caminho de falha para seu uso e cenário específicos.

Como testar seu tópico

Certifique-se de testar seu tópico usando um usuário real configurado em seu provedor de identidade. Verifique se os caminhos de êxito e falha de entrada são exercitados, para que não haja surpresas se o usuário não entrar ou se houver um erro na experiência de entrada do provedor de identidade.

Tópicos relacionados

Você também pode configurar o logon único (SSO) para que seus usuários não precisem fazer logon manualmente. Para obter mais informações, consulte Configurar SSO para a Web.