Adicione autenticação de usuário a um tópico para permitir que seus clientes entrem diretamente na conversa. Em seguida, você pode personalizar a conversa com variáveis de usuário e acessar sistemas back-end em nome do usuário.
Você precisa configurar a autenticação do usuário com o Microsoft Entra ID antes de poder usar a autenticação em seus tópicos.
Siga as instruções em Configurar a autenticação do usuário com o Microsoft Entra ID.
Adicionar autenticação de utilizador com o tópico de sistema Iniciar sessão
Quando você cria um agente, o Copilot Studio adiciona automaticamente um tópico do sistema chamado Entrar. Para usá-lo, você deve definir a autenticação do agente como manual e exigir que os usuários entrem. Quando um cliente inicia uma conversa com o agente, o tópico Entrar é acionado e solicita que o usuário faça login. Você pode personalizar o tópico Entrar conforme apropriado para seu agente.
Importante
Recomendamos 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 ou fluxos, ou outros métodos de autenticação.
- Abra seu agente no Copilot Studio, selecione Configurações na parte superior da página e, em seguida, selecione Segurança.
- Selecione Autenticação.
- Selecione Autenticar manualmente e, em seguida, selecione Exigir que os utilizadores iniciem sessão.
-
Configure todos os campos de autenticação manual, conforme necessário.
- Selecione Guardar.
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 utilizador inicie sessão mais tarde, pode adicionar um nó Autenticar a qualquer tópico personalizado.
Quando os clientes inserem seu nome de usuário e senha, eles podem ser solicitados a inserir um código de validação. Depois de entrarem, não lhes é pedido novamente, mesmo que alcancem outro nó Autenticar .
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.
Selecione Autenticar manualmente e desmarque a caixa de seleção Exigir que os usuários entrem .
Configure todos os campos de autenticação manual, conforme necessário.
Selecione Guardar.
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.
Sugestão
É importante que crie caminhos para um início de sessão bem-sucedido e em caso de falha no início de sessão. Um login pode falhar 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 agente, 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 escolhida.
Para obter mais informações sobre variáveis, consulte Visão geral de variáveis.
| Variável de autenticação |
Sem autenticação |
Autenticar com a Microsoft |
Autenticar manualmente |
|
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
Advertência
Não é garantido que essa variável contenha um valor. Teste com um usuário do seu provedor de identidade para garantir que o tópico funcione corretamente.
A User.DisplayName variável contém o nome de exibição armazenado no provedor de identidade. Use essa variável para cumprimentar ou se referir ao usuário sem que ele precise dar explicitamente seu nome ao agente, tornando a conversa mais personalizada.
O Copilot Studio define automaticamente o valor de User.DisplayName a partir da declaração de name fornecida pelo provedor de identidade, desde que o escopo de profile tenha sido definido quando a autenticação manual foi configurada. Para obter mais informações sobre escopo, consulte Configurar a autenticação do usuário com o Microsoft Entra ID.
User.Id
Advertência
Não é garantido que essa variável contenha um valor. Teste com um usuário do seu provedor de identidade para garantir que o tópico funcione corretamente.
A User.Id variável contém o ID do usuário armazenado no provedor de identidade. Use essa variável em fluxos do Power Automate para chamar APIs que usam o UserID como um valor.
O Copilot Studio define automaticamente o valor de User.DisplayName da afirmação sub fornecida pelo fornecedor de identidade.
Utilizador.EstáLogado
User.IsLoggedIn é uma variável booleana que armazena o status de entrada do usuário. Um valor de true indica que o utilizador está conectado. 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 ou para buscar informações do usuário somente se o usuário estiver conectado.
User.AccessToken
Advertência
Certifique-se de que está a passar a User.AccessToken variável apenas para fontes fidedignas. Ele contém informações de autenticação do usuário, que, se comprometidas, podem prejudicar o usuário.
A User.AccessToken variável contém o token do usuário, obtido depois que o usuário está conectado. Você pode passar essa variável para os fluxos do Power Automate para que eles possam se conectar a APIs de back-end e buscar informações do usuário, ou para executar ações em nome do usuário.
Não use User.AccessToken em nós de mensagem ou em fluxos nos quais você não confia.
SignInReason
SignInReason é uma variável de tipo de escolha que indica quando o usuário deve entrar. Tem dois valores possíveis:
SignInRequired indica que o usuário deve entrar no início da conversa usando o tópico Entrar no sistema.
Requer que os utilizadores a iniciar sessão devem estar ativados.
Initializer Indica que, quando um usuário não está conectado e chega a um ponto da conversa que usa variáveis de autenticação, ele é solicitado a entrar.
Variáveis de autenticação
Se o agente estiver configurado com as opções de autenticação Autenticar com a Microsoft ou Manual, terá um conjunto de variáveis de autenticação disponíveis nos seus tópicos. Para obter mais informações sobre como configurar a autenticação em seu agente, consulte Configurar a autenticação do usuário no Copilot Studio.
A tabela a seguir compara a disponibilidade da variável de autenticação pela 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 User.DisplayName variável contém o nome de exibição do usuário armazenado no provedor de identidade. Você pode usar essa variável para cumprimentar ou se referir ao cliente sem que ele tenha que dizer explicitamente ao agente, tornando-o mais personalizado.
Este valor de campo é obtido da afirmação name do Microsoft Entra ID. Para provedores OAuth, esse valor é armazenado na name declaração. O Copilot Studio extrai automaticamente esse campo para a variável, portanto, certifique-se de ter profile como parte da configuração do escopo de autenticação.
Variável UserID
A User.Id variável contém o ID do usuário armazenado no provedor de identidade. Os fluxos do Power Automate podem usar esse valor para chamar APIs que usam o UserID como um valor.
Este valor de campo é obtido da afirmação sub do Microsoft Entra ID. Para provedores OAuth, esse valor é armazenado na sub declaração. O Copilot Studio extrai automaticamente este campo para a variável.
Advertência
As User.DisplayName variáveis e User.Id podem não ser preenchidas e, em vez disso, essas variáveis podem ser cadeias de caracteres vazias, dependendo da configuração do usuário no provedor de identidade. Teste com um usuário do seu provedor de identificação para garantir que seus tópicos funcionem corretamente, mesmo que essas variáveis estejam vazias.
Variável IsLoggedIn
A User.IsLoggedIn variável indica se o usuário está conectado (como resultado de entrar ou já estar conectado, também conhecido como caminho de sucesso de logon) ou não está conectado (o que resultaria no caminho de falha de logon).
User.IsLoggedIn é uma variável booleana que contém 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 para buscar oportunisticamente informações do usuário somente se o usuário estiver conectado.
Variável User.AccessToken
A User.AccessToken variável contém o token do usuário, obtido depois que o usuário está conectado. Você pode passar essa variável para os fluxos do Power Automate para que eles possam se conectar a APIs de back-end e buscar as informações do usuário, ou para executar ações em nome do usuário.
Advertência
Certifique-se de que está a passar a User.AccessToken variável apenas para fontes fidedignas. 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 de 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 User.DisplayName variáveis e User.Id . No entanto, ao testar tópicos que usam autenticação, convém usar outros valores para essas variáveis (ou até mesmo um valor em branco).
Por exemplo, talvez você queira testar como 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 só se aplicam ao painel Bot de teste ; Não é possível usá-los em um agente publicado implantado em um canal.
Insira o comando desejado no painel Test bot exatamente como faria se estivesse conversando normalmente com o agente. Você receberá uma mensagem de confirmação do agente se for bem-sucedido. Se o agente não usar autenticação, você receberá um erro.
Se você redefinir o painel do bot de teste (ou fizer alterações em um tópico que façam com que o bot de teste seja redefinido automaticamente), precisará 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, não é possível preencher a User.Id variável com um valor personalizado (que não seja um valor vazio ou em branco).
Autenticação ao usar "Autenticar com a Microsoft"
Se a opção de autenticação estiver definida como Autenticar com a Microsoft, não será necessário adicionar explicitamente a autenticação aos tópicos. Nessa configuração, qualquer usuário no Microsoft Teams entra automaticamente por meio de suas credenciais do Teams e não precisa entrar explicitamente com um cartão de autenticação. Se a opção de autenticação estiver definida como Manual, você deverá adicionar um nó Autenticar (mesmo para o canal do Teams).
Observação
Se a opção de autenticação estiver definida como Autenticar com a Microsoft, não será possível adicionar explicitamente a autenticação aos tópicos.
Adicionar autenticação de usuário a um tópico
O nó Autenticar solicita que um utilizador inicie sessão com um cartão de início de sessão. Depois de um utilizador ter iniciado sessão, não haverá qualquer pedido novamente, mesmo que alcance outro nó Autenticar.
Depois que o usuário insere seu nome de usuário e senha no prompt (hospedado pelo provedor de identidade), ele pode ser solicitado a inserir um código de validação, dependendo do canal. Alguns canais, como o Microsoft Teams, não exigem um código de validação do usuário.
Quando o agente tiver o SSO configurado, o usuário não será solicitado a entrar.
Para adicionar um nó Autenticar ao seu tópico:
Vá para a página Tópicos do agente que você deseja editar.
Abra o tópico ao qual você deseja adicionar o modelo de autenticação.
Observação
Se o agente estiver ligado ao Serviço de Atendimento ao Cliente do Dynamics 365, o nó de Autenticação não deve fazer parte do caminho de conversa que o agente segue ao cumprimentar inicialmente os utilizadores; caso contrário, o cartão de início de sessão será mostrado duas vezes. Em vez disso, você deve adicionar o nó Autenticar a outro tópico que é acionado por uma resposta do usuário.
Selecione Adicionar nó (+) para adicionar um nó de mensagem. Insira o que o agente deve dizer para indicar que uma experiência de logon está prestes a ocorrer.
Por baixo do nó de mensagem, selecione Adicionar nó (+), selecione Chamar um ação e, em seguida, selecione Autenticar.
Observação
O nó Autenticar só está disponível no selecionador de ações no final de uma árvore de diálogo (como nó de folha). Ele não pode ser adicionado no meio de uma caixa de diálogo. Uma vez adicionado, outros nós podem ser adicionados abaixo dele.
Estes nós são apresentados automaticamente: um nó principal Autenticar, seguido de nós para um caminho de êxito e um caminho de falha.
Utilização de User.AccessToken sem um nó Autenticar
As User.IsLoggedIn variáveis e User.AccessToken estão disponíveis mesmo se você não usar o modelo fornecido pela entrada do menu Chamar uma ação . Se passares a User.AccessToken variável sem primeiro fazer com que o utilizador passe pelo nó Autenticar, serás solicitado a iniciar sessão nessa etapa.
Passar a User.AccessToken variável pode ser útil se você sempre espera 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.
Observação
Se o utilizador terminar sessão a meio de uma conversa, é-lhe pedido que inicie sessão novamente se o tópico chegar a um nó que utiliza a variável User.AccessToken.
Caminho de sucesso
O caminho do êxito equivale a User.IsLoggedIn = True e indica quando o utilizador inicia sessão com êxito.
Se você tiver uma lógica que usa a User.AccessToken variável (por exemplo, para se conectar a um sistema back-end usando um fluxo para recuperar as informações de um usuário), ela deve seguir esse caminho.
Caminho de falha
O caminho de 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 queira para tratar este caso. Como exemplo, há opções para tentar novamente ou escalar para um agente ao vivo. Personalize as ações do caminho de falha para o seu cenário e utilização específicos.
Testando 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 de falha de início de sessão são exercidos. Ao fazer isto, não há surpresas se o utilizador não conseguir iniciar sessão ou se houver um erro com a experiência de início de sessão do fornecedor de identidade.