Adicionar autenticação aos tópicos

É necessário configurar a autenticação do utilizador com o Microsoft Entra ID antes de poder usar a autenticação nos seus tópicos.

Siga as instruções em Configurar autenticação do utilizador com o Microsoft Entra ID.

Adicionar autenticação de utilizador com o tópico de sistema Iniciar sessão

Quando cria um agente, o Copilot Studio adiciona automaticamente um tópico do sistema chamado Iniciar sessão. Para utilizá-lo, deve definir a autenticação do seu agente para o modo manual e exigir que os utilizadores iniciem sessão. Quando um cliente inicia uma conversa com o agente, o tópico Iniciar sessão é acionado e pede ao utilizador que inicie sessão. Pode personalizar o tópico Iniciar sessão conforme apropriado para o seu agente.

1. Abra o seu agente no Copilot Studio, selecione Definições no topo da página e, em seguida, selecione Segurança.
2. Selecione Autenticação.
3. Selecione Autenticar manualmente e, em seguida, selecione Exigir que os utilizadores iniciem sessão.
4. Configure todos os campos de autenticação manual, conforme necessário.
5. Selecione Guardar.

Adicionar autenticação de utilizador com um tópico personalizado

O tópico Iniciar sessão autentica o utilizador 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 utilizadores introduzem o nome de utilizador e a palavra-passe, pode ser-lhes pedido que introduzam um código de validação. Depois de entrarem, não lhes é pedido novamente, mesmo que alcancem outro nó Autenticar .

1. Selecione Definições no topo da página e, em seguida, selecione Segurança.

2. Selecione o mosaico Autenticação.

   Nota

   Deve selecionar Autenticar manualmente para adicionar autenticação de utilizador a um tópico personalizado.

3. Selecione Autenticar manualmente e desmarque a caixa de verificação Exigir que os utilizadores iniciem sessão.

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

5. Selecione Guardar.

6. Selecione Tópicos no topo da página.

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

8. Teste o seu tópico com um utilizador configurado com o seu fornecedor de identidade.

Se a sua opção de autenticação estiver definida para Autenticar com a Microsoft, não precisa de adicionar explicitamente autenticação aos seus tópicos. Nesta configuração, qualquer utilizador no Microsoft Teams inicia sessão automaticamente com as respetivas credenciais do Teams e não precisa de iniciar sessão explicitamente com um cartão de autenticação. Se a sua opção de autenticação estiver definida como Manual, então tem de adicionar um nó Autenticar (mesmo para o canal Teams).

Adicionar autenticação de utilizador a um tópico

O nó Autenticar pede ao utilizador que inicie sessão com um cartão de início de sessão. Depois de um utilizador iniciar sessão, não haverá qualquer pedido novamente, mesmo que alcance outro nó Autenticar.

Depois de o utilizador introduzir o respetivo nome de utilizador e palavra-passe no pedido (alojado pelo fornecedor de identidade), poderá ser solicitado que introduza um código de validação, consoante o canal. Alguns canais, como o Microsoft Teams, não exigem um código de validação do utilizador.

Quando o agente tem SSO configurado, não é pedido ao utilizador que inicie sessão.

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

1. Vá para a página Tópicos para o agente que pretende editar.

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

   Nota

   Se o seu agente estiver ligado ao Dynamics 365 Customer Service, o nó de Autenticação não pode fazer parte do caminho de conversação que o agente segue ao cumprimentar inicialmente os utilizadores; caso contrário, o cartão de início de sessão é mostrado duas vezes. Em vez disso, adicione o nó Autenticar a outro tópico que uma resposta do utilizador aciona.

3. Selecione Adicionar nó (+) para adicionar um nó de mensagem. Introduza aquilo que o agente deve dizer para indicar que está prestes a acontecer uma experiência de início de sessão.

4. Por baixo do nó de mensagem, selecione Adicionar nó (+), selecione Chamar um ação e, em seguida, selecione Autenticar.

   

   Nota

   O nó Autenticar só está disponível no selecionador de ações no final de uma árvore de diálogo (como nó de folha). Não pode adicioná-lo no meio de um diálogo. Uma vez adicionado, pode adicionar outros nós abaixo.

   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 variáveis User.IsLoggedIn e User.AccessToken estão disponíveis mesmo que não utilize o modelo fornecido pela entrada de menu Chamar uma ação. Se transmitir a variável User.AccessToken sem primeiro o utilizador passar pelo nó Autenticar, é pedido ao utilizador que inicie sessão nesse passo.

Transmitir a variável User.AccessToken pode ser útil se espera sempre que o utilizador tenha sessão iniciada ou se o seu utilizador estiver a ser redirecionado de um tópico diferente. Utilize o modelo fornecido pela entrada Chamar uma ação para tratar os casos em que o utilizador não inicia sessão.

Caminho de êxito

O caminho do sucesso corresponde a User.IsLoggedIn = True e indica quando o utilizador inicia sessão com êxito.

Se tiver uma lógica que utilize a variável User.AccessToken (por exemplo, para ligar a um sistema back-end através de um fluxo para obter as informações de um utilizador), coloque-o por baixo deste caminho.

Caminho de falha

O caminho de falha corresponde a qualquer condição diferente de IsLoggedIn = True. Na maioria dos casos, o caminho de falha ocorre porque o utilizador não conseguiu iniciar sessão, utilizou a palavra-passe errada ou cancelou a experiência de início de sessão.

Adicione qualquer lógica que pretenda que trate deste caso. Como exemplo, existem opções para voltar a tentar ou para escalar para um agente em direto. Personalize as ações do caminho de falha para o seu cenário e utilização específicos.

Testar o seu tópico

Certifique-se de que testa o seu tópico com um utilizador real configurado no seu fornecedor 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.

Quando configura a autenticação do utilizador para o seu agente, pode usar variáveis de autenticação nos seus tópicos. A tabela seguinte compara a disponibilidade destas variáveis com base na opção de autenticação que escolheu.

User.DisplayName

A variável User.DisplayName contém o nome a apresentar armazenado no fornecedor de identidade. Use esta variável para cumprimentar ou referir-se ao utilizador sem que este tenha de dar explicitamente o nome ao agente, tornando a conversa mais personalizada.

O Copilot Studio define automaticamente o valor de User.DisplayName com base na declaração name fornecida pelo fornecedor de identidade, desde que o âmbito profile foi definido durante a configuração manual da autenticação. Saiba mais em Configurar a autenticação do utilizador com Microsoft Entra ID.

User.Id

A variável User.Id contém o ID de utilizador armazenado no fornecedor de identidade. Utilize esta variável em fluxos do Power Automate para chamar APIs que recebem o UserID como valor.

O Copilot Studio define automaticamente o valor de User.DisplayName da afirmação sub fornecida pelo fornecedor de identidade.

User.IsLoggedIn

User.IsLoggedIn é uma variável booleana que armazena o estado de início de sessão do utilizador. Um valor de true indica que o utilizador iniciou sessão. Pode utilizar esta variável para criar lógica de ramificação nos seus tópicos que verifica se o início de sessão foi bem-sucedido ou para obter informações do utilizador apenas caso este tenha iniciado sessão.

User.AccessToken

A variável User.AccessToken contém o token do utilizador, obtido depois de o utilizador iniciar sessão. Pode transmitir esta variável para os fluxos do Power Automate para poderem ligar-se às APIs de back-end e obter as informações do utilizador, ou tomar medidas em nome do utilizador.

Não utilize User.AccessToken nos nós de Mensagem ou em fluxos em que não confia.

SignInReason

SignInReason é uma variável de seleção que indica o momento em que o utilizador deve iniciar sessão. Existem dois valores possíveis:

• SignInRequired indica que o utilizador deve iniciar sessão no início da conversa ao usar o tópico do sistema Iniciar sessão . Requer que os utilizadores a iniciar sessão devem estar ativados.

• Initializer indica que, quando um utilizador não iniciou sessão e chega a um ponto da conversa que utiliza variáveis de autenticação, é-lhe pedido que inicie sessão.

Se configurar o seu agente com a autenticação Autenticar com a Microsoft ou Manual, terá um conjunto de variáveis de autenticação disponíveis nos seus tópicos. Saiba mais em Configurar a autenticação de utilizador no Copilot Studio.

A tabela seguinte compara a disponibilidade das variáveis de autenticação por opção de configuração de autenticação:

Variável UserDisplayName

A variável User.DisplayName contém o nome a apresentar do utilizador armazenado no fornecedor de identidade. Pode utilizar esta variável para cumprimentar ou referir-se ao cliente sem que este tenha de fornecer explicitamente essa informação ao agente, tornando a experiência mais personalizada.

Este valor de campo é obtido da afirmação name do Microsoft Entra ID. Para fornecedores de OAuth, este valor é armazenado na afirmação name. O Copilot Studio extrai automaticamente este campo para a variável, por isso certifique-se de que o profile faz parte da configuração do âmbito de autenticação.

Variável UserID

A variável User.Id contém o ID do utilizador armazenado no fornecedor de identidade. Os fluxos do Power Automate podem usar este valor para chamar APIs que recebem o UserID como um valor. Este valor de campo é obtido da afirmação sub do Microsoft Entra ID. Para fornecedores de OAuth, este valor é armazenado na afirmação sub. O Copilot Studio extrai automaticamente este campo para a variável.

Variável IsLoggedIn

A variável User.IsLoggedIn indica se o utilizador tem sessão iniciada (seja como resultado de iniciar sessão ou já com sessão iniciada, também conhecido como o caminho de sucesso de início de sessão) ou não tem sessão iniciada (o que resultaria no caminho de falha de início de sessão).

User.IsLoggedIn é uma variável booleana que contém o estado de início de sessão do utilizador. Pode utilizar esta variável para criar uma lógica de ramificação nos seus tópicos que verifique um início de sessão com êxito (por exemplo, no modelo já fornecido como parte de adicionar o nó Autenticar) ou para obter oportunisticamente informações do utilizador, apenas se o utilizador tiver sessão iniciada.

Variável User.AccessToken

A variável User.AccessToken contém o token do utilizador, obtido depois de o utilizador iniciar sessão. Transmita esta variável para os fluxos do Power Automate para poderem ligar-se às APIs de back-end e obter as informações do utilizador, ou tomar medidas em nome do utilizador.

Não utilize User.AccessToken dentro de nós de Mensagem ou em fluxos em que não confia.

Teste de variáveis de autenticação

Por predefinição, o painel Bot de teste utiliza a conta do utilizador que iniciou sessão para preencher as variáveis User.DisplayName e User.Id. No entanto, ao testar tópicos que usam autenticação, pode querer usar outros valores para essas variáveis (ou até um valor vazio).

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

A tabela seguinte lista os comandos para preencher estas variáveis. Estes comandos aplicam-se apenas ao painel do Bot de teste; não pode usá-los num agente publicado implementado num canal.

Introduza o comando pretendido no painel Bot de teste, tal como faria se estivesse a conversar com o agente. Se for bem-sucedido, recebe uma mensagem de confirmação do agente. Se o seu agente não utilizar autenticação, receberá um erro.

Se repuser o painel Bot de teste (ou fizer alterações a um tópico que provoque a reposição do Bot de teste automaticamente), terá de enviar novamente os comandos.