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.
Você precisa configurar a autenticação do usuário com Microsoft Entra ID antes de poder usar a autenticação em seus tópicos.
Siga as instruções em Configurar autenticação do usuário com o Microsoft Entra ID.
Adicionar a autenticação do usuário com o tópico do sistema Entrar
Quando você cria um copiloto, o 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 é desencadeado e solicita que o usuário entre. Você pode personalizar o tópico Entrar conforme apropriado para seu copiloto.
Importante
É recomendável que o tópico Entrar seja usado apenas para fornecer o método de autenticação fornecido pelo Copilot Studio. Ele não deve ser modificado para chamar quaisquer outras ações, fluxos ou outros métodos de autenticação.
Abra seu copiloto no Copilot Studio, selecione Configurações na parte superior da página e selecione Segurança.
Selecione Autenticação.
Selecione Autenticar manualmente e, em seguida, selecione Exigir que os usuários entrem.
Configure todos os campos de autenticação manual, conforme necessário.
Selecione Salvar.
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. Após efetuarem login, eles não serão solicitados novamente, mesmo que alcancem outro nó de autenticação.
Selecione Configurações na parte superior da página e, em seguida, selecione Segurança.
Selecione o bloco Autenticação.
Observação
Você deve selecionar Autenticar manualmente para adicionar a autenticação do usuário a um tópico personalizado.
Desmarque a caixa de seleção Exigir que os usuários entrem.
Configure todos os campos de autenticação manual, conforme necessário.
Selecione Salvar.
Selecione Tópicos na parte superior da página.
Selecione Adicionar nó (
) >Avançado>Autenticar.
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
Ao configurar a autenticação do usuário para seu copiloto, você pode usar variáveis de autenticação em seus tópicos. A tabela a seguir compara a disponibilidade dessas variáveis com base na opção de autenticação que você escolheu.
Para obter mais informações sobre variáveis, consulte Trabalhar com variáveis.
| Variável de autenticação |
Sem autenticação |
Autenticar com a Microsoft |
Autenticar manualmente |
| Usuário.NomeDeExibição |
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 |
| Usuário.EstáLogado |
Não disponível |
Disponível |
Disponível |
| Usuário.AccessToken |
Não disponível |
Não disponível |
Disponível |
| Motivo do SignIn |
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 contém o nome de exibição armazenado no provedor de identidade. User.DisplayName 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 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 contém o ID do usuário armazenado no provedor de identidade. User.Id Use essa variável em fluxos do Power Automate para chamar APIs que usam a UserID como um valor.
O 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 booliano que armazena o status de login 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 efetuar login. Ela tem dois possíveis valores:
SignInRequired indica que o usuário deve efetuar login no início da conversa usando o log in tópico do sistema. Exigir que os usuários efetuem login deve estar ativado.
Initializer indica que quando um usuário não está logado e chega a um ponto na conversa que usa variáveis de autenticação, ele é solicitado a efetuar login.
Variáveis de autenticação
Se o seu copiloto estiver configurado com as opções de autenticação Autenticar com a Microsoft ou Manual , você terá um conjunto de variáveis de autenticação disponíveis em seus tópicos. Para obter mais informações sobre como configurar autenticação em seu copiloto, consulte Configurar autenticação do usuário no Copilot Studio.
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 |
Autenticar com a Microsoft |
Manual |
User.DisplayName |
❌ |
✔️ |
✔️ |
User.Id |
❌ |
✔️ |
✔️ |
User.IsLoggedIn |
❌ |
❌ |
✔️ |
User.AccessToken |
❌ |
❌ |
✔️ |
Variável UserDisplayName
A variável User.DisplayName 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 copiloto, tornando-o mais personalizado.
Esse valor de campo é obtido por meio da declaração do Microsoft Entra ID name. Para OAuth provedores, esse valor é armazenado na name reivindicação. Como o 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 User.Id contém a ID do usuário armazenado no provedor de identidade. Power Automate os fluxos podem usar esse valor para chamar APIs que usam o UserID como valor.
Esse valor de campo é obtido por meio da declaração do Microsoft Entra ID sub. Para OAuth provedores, esse valor é armazenado na sub reivindicação. O Copilot Studio extrai automaticamente esse campo para a variável.
Aviso
Não há garantia de que as variáveis User.DisplayName e User.Id sejam preenchidas e podem ser strings 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
A variável indica se o usuário está logado (seja como resultado do login ou já estando logado, também conhecido como caminho de sucesso do login) ou não logado (o que resultaria no caminho de falha do login). User.IsLoggedIn
User.IsLoggedIn é uma variável booliano contendo o status de login 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 User.AccessToken
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 as informações do usuário ou executar ações em nome do usuário.
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.
Não use User.AccessToken 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 usa a conta do usuário conectado no momento para preencher as variáveis User.DisplayName e User.Id . 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.
A tabela a seguir lista os comandos para preencher essas variáveis. Esses comandos se aplicam somente ao painel Bot de teste ; você não pode usá-los em um copiloto publicado implantado em um canal.
Digite o comando desejado no painel Bot de teste da mesma forma que faria se estivesse conversando normalmente com o copiloto. Você receberá uma mensagem de confirmação do copiloto se tiver êxito. Se o seu copiloto não usar autenticação, você receberá um erro.
Se você redefinir o painel There (ou fizer alterações em um tópico que façam com que o There seja redefinido automaticamente), será necessário enviar os comandos novamente.
| Variável |
Comando de valor personalizado |
Comando de valor vazio (em branco) |
User.DisplayName |
/debug set bot.UserDisplayName "Value" |
/debug set bot.UserDisplayName "" |
User.Id |
Não disponível |
/debug set bot.UserID "" |
Importante
Por motivos de segurança, você não pode preencher a variável User.Id com um valor personalizado (exceto um valor vazio ou em branco).
Autenticação ao usar "Autenticar com a Microsoft"
Se sua opção de autenticação estiver definida como Autenticar com a Microsoft, você não precisará adicionar autenticação explicitamente aos seus 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ê deverá adicionar um nó Autenticar (mesmo para o canal Teams).
Observação
Se sua opção de autenticação estiver definida como Autenticar com a Microsoft, você não terá a opção de adicionar autenticação explicitamente aos seus tópicos.
Adicionar autenticação de usuário a um tópico
O nó Authenticate solicita que o usuário efetue login com um login cartão. Depois que um usuário efetua login, ele não é solicitado novamente, mesmo que alcance outro nó de autenticação.
Depois que o usuário digitar seu nome de usuário e senha na solicitação (hospedada pelo provedor de identidade), você poderá ser solicitado a inserir um código de validação, dependendo do canal. Alguns canais, como Microsoft Teams, não exigem um código de validação do usuário.
Quando o copiloto tiver SSO configurado, o usuário não será solicitado a entrar.
Para adicionar um nó Authenticate ao seu tópico:
Acesse a página Tópicos do copiloto que você deseja editar.
Abra o tópico ao qual você deseja adicionar o modelo de autenticação.
Observação
Se o copiloto estiver conectado ao Dynamics 365 Customer Service, o nó de Autenticação não poderá fazer parte do caminho da conversa que o copiloto seguirá quando saudar os usuários inicialmente. Caso contrário, o cartão de entrada será exibido duas vezes. Em vez disso, você deve adicionar o nó Authenticate a outro tópico que é acionado por um usuário resposta.
Selecione Adicionar nó (+) para adicionar um nó de mensagem. Insira o que o copiloto deve dizer para indicar que uma experiência de entrada está prestes a ocorrer.
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.
Novos nós aparecem automaticamente: um nó pai Authenticate , seguido por nós para um caminho de sucesso e um caminho de falha.
Uso de User.AccessToken sem um nó Authenticate
As variáveis User.IsLoggedIn e User.AccessToken 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 User.AccessToken sem primeiro fazer o usuário passar pelo nó Autenticar , o usuário será solicitado a efetuar login naquele etapa.
Passar a variável User.AccessToken pode ser útil se você sempre espera que o usuário esteja logado, ou se seu 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, ele será solicitado a efetuar login novamente se o tópico chegar a um nó que usa a variável User.AccessToken .
Caminho de êxito
O caminho do sucesso equivale a onde User.IsLoggedIn = True e é responsável por quando o usuário efetuou login com sucesso (ou já estava conectado).
Se você tiver uma lógica que use a variável User.AccessToken (por exemplo, para se conectar a um sistema de back-end usando um fluxo para recuperar informações de um usuário), ela deve seguir este caminho.
Caminho de falha
O caminho da falha equivale a qualquer condição diferente de IsLoggedIn = True. Na maioria dos casos, o caminho da falha ocorre porque o usuário não conseguiu efetuar login, usou a senha errada ou cancelou a experiência de login.
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. Certifique-se de que os caminhos de sucesso e falha de login sejam exercidos, para que There não seja nenhuma surpresa se o usuário não conseguir fazer login ou se houver um erro na experiência de login do provedor de identidade.