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

Você precisa configurar a autenticação do usuário com o Microsoft Entra ID antes de 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 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 é desencadeado e solicita que o usuário entre. Você pode personalizar o tópico Entrar conforme apropriado para seu agente.

1. Abra o agente no Copilot Studio e selecione Configurações na parte superior da página e depois escolha Segurança.
2. Selecione Autenticação.
3. Selecione Autenticar manualmente e, em seguida, selecione Exigir que os usuários entrem.
4. Configure todos os campos de autenticação manual, conforme necessário.
5. 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 entre 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 de entrarem, não serão novamente solicitados, mesmo que atinjam outro nó Autenticar.

1. Selecione Configurações na parte superior da página e, em seguida, selecione Segurança.

2. 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.

3. Selecione Autenticar manualmente e desmarque a caixa de seleção Exigir que os usuários entrem.

4. Configure todos os campos de autenticação manual, conforme necessário.

5. Selecione Salvar.

6. Selecione Tópicos na parte superior da página.

7. Selecione Adicionar nó ( ) >Avançado>Autenticar.

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

Se sua opção de autenticação estiver definida como Autenticar com a Microsoft, não será necessário adicionar a 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, será necessário adicionar um nó Autenticar (mesmo para o canal do Teams).

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

O nó Autenticar solicita que um usuário entre com um cartão de entrada. Depois que um usuário entra, não será solicitado que entre novamente, mesmo que acesse outro nó Autenticar.

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

Quando seu agente tem SSO configurado, o usuário não é solicitado a fazer login.

Para adicionar um nó Autenticar em seu tópico:

1. Acesse a página Tópicos do agente que deseja editar.

2. Abra o tópico ao qual deseja adicionar o modelo de autenticação.

   Observação

   Se o seu agente estiver conectado ao Dynamics 365 Customer Service, o nó de autenticação não pode fazer parte do caminho de conversa que o agente segue ao cumprimentar os usuários pela primeira vez; caso contrário, o cartão de login será exibido duas vezes. Em vez disso, adicione o nó Autenticar a outro tópico que a resposta de um usuário dispara.

3. Selecione Adicionar nó (+) para adicionar um nó de mensagem. Digite o que o agente 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.

   

   Observação

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

   Novos nós aparecem automaticamente: um nó pai Autenticar, seguido por nós para um caminho de sucesso e um caminho de falha.

Uso de User.AccessToken sem um nó Autenticar

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 com que o usuário passe pelo nó Autenticar, o usuário será solicitado a entrar nessa etapa.

Passar a variável User.AccessToken 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. Use o modelo fornecido pela entrada Chamar uma ação para manipular casos em que o usuário não consegue entrar.

Caminho de êxito

O caminho de êxito corresponde a User.IsLoggedIn = True e é levado em conta quando o usuário entrou com êxito.

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 as informações de um usuário), coloque-a nesse caminho.

Caminho de falha

O caminho da falha corresponde 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, utilizou a senha errada ou cancelou a experiência de entrada.

Adicione qualquer lógica que você deseja manipular nesse caso. Como exemplo, há 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

Não se esqueça de testar o tópico usando um usuário real configurado no provedor de identidade. Certifique-se de que tanto os caminhos de sucesso quanto de falha do login sejam testados. Ao fazer isso, não haverá surpresas se o usuário não conseguir fazer login ou se houver um erro com o processo de login do provedor de identidade.

Ao configurar a autenticação do usuário para o agente, você pode usar 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 escolhida por você.

User.DisplayName

A variável User.DisplayName contém o nome de exibição 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 agente, tornando a conversa mais personalizada.

O Copilot Studio define automaticamente o valor de User.DisplayName da declaração name fornecida pelo provedor de identidade, desde que o escopo profile seja definido quando a autenticação manual seja configurada. Saiba mais em Configurar autenticação do usuário com o Microsoft Entra ID.

User.Id

A variável User.Id contém a ID do usuário armazenada no provedor de identidade. 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 booliana 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

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 de 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. A opção Exigir que os usuários entrem deve estar ativada.

• Initializer indica que, quando um usuário não está conectado e chega a um ponto na conversa que usa variáveis de autenticação, é solicitado que ele entre no sistema.

Se configurar o agente 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. Saiba mais em 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 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 cliente sem que ele tenha que manifestar isso explicitamente ao agente, tornando-o mais personalizado.

Esse valor de campo é obtido por meio da declaração do Microsoft Entra ID name. Para provedores OAuth, esse valor é armazenado na declaração name. 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. Os fluxos do Power Automate podem usar este valor 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 valor é armazenado na declaração sub. O Copilot Studio extrai automaticamente esse campo para a variável.

Variável IsLoggedIn

O User.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).

User.IsLoggedIn é uma variável booliana 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 User.AccessToken

A variável User.AccessToken contém o token do usuário, obtido após a entrada do usuário. Passe 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.

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 atualmente conectado 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 não se aplicam somente ao painel Bot de teste; você não pode usá-los em um agente 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 agente. Você receberá uma mensagem de confirmação do agente se for bem-sucedido. Se o seu agente 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.