Configurar o logon único com o Microsoft Entra ID

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.

O Copilot Studio suporta logon único (SSO). O SSO permite que os copilotos em seu conectem os clientes se eles já estiverem conectados na página ou aplicativo em que o copiloto está implantado.

Pré-requisitos

• Habilitar autenticação de usuário final com o Microsoft Entra ID.
  O SSO é compatível somente com o Microsoft Entra ID. Outros tipos de conta, como conta Microsoft ou outras contas OAuth, não são compatíveis.
• Adicionar um tópico de autenticação ao copiloto.
• Usar uma tela personalizada.

Por exemplo, o copiloto está hospedado na intranet corporativa ou em um aplicativo ao qual o usuário já está conectado.

Há quatro etapas principais para configurar o SSO para o Copilot Studio:

1. Criar um registro de aplicativo no Microsoft Entra ID para sua tela personalizada.

2. Defina um escopo personalizado para seu copiloto.

3. Configurar autenticação no Copilot Studio para habilitar SSO.

4. Configurar seu código HTML de tela personalizada para habilitar SSO.

Importante

Atualmente, o SSO não é compatível quando um copiloto foi:

• Publicado em um site do SharePoint.
• Publicado em um portal do Power Apps.

Canais compatíveis

A tabela a seguir detalha os canais compatíveis com o SSO no momento. Você pode sugerir suporte para tipos de canais adicionais no fórum de ideias do Microsoft Copilot Studio.

Canal	Compatível
Canais do Serviço de Bot do Azure	Incompatível
Site personalizado	Compatível
Site de demonstração	Incompatível
Facebook	Incompatível
Microsoft Teams1	Compatível
Aplicativo móvel	Incompatível
Omnichannel para Customer Service2	Compatível

¹ Se também tiver o canal do Teams habilitado, você precisará seguir as instruções de configuração na documentação Configurar o SSO para o canal do Teams. A falha ao definir as configurações de SSO do Teams conforme instruído nesta página fará com que seus usuários sempre falhem na autenticação ao usar o canal do Teams.

² Apenas o canal de chat ao vivo é compatível. Para obter mais informações, consulte Configurar entrega para o Dynamics 365 Customer Service.

Aplicativo Web

Criar registros de aplicativo para seu site personalizado

Para habilitar o SSO, você precisa criar dois registros de aplicativo separados:

• Um registro de aplicativo de autenticação, que permite a autenticação de usuário do Microsoft Entra ID para seu copiloto
• Um registro de aplicativo de tela, que habilita o SSO para sua página da Web personalizada

Não recomendamos reutilizar o mesmo registro de aplicativo para seu copiloto e seu site personalizado, por motivos de segurança.

1. Siga as instruções em Configurar autenticação do usuário com o Microsoft Entra ID para criar um registro de aplicativo de autenticação.
2. Siga as mesmas instruções novamente para criar um segundo registro de aplicativo, que serve como seu registro de aplicativo de tela.
3. Retorne a este artigo.

Configurar o registro do aplicativo de tela

1. Após criar seu registro de aplicativo de tela, acesse Autenticação e selecione Adicionar uma plataforma.

2. Em Configurações da plataforma, selecione Adicionar uma plataforma e Web.

3. Em Redirecionar URIs, insira a URL da sua página da Web, por exemplo, http://contoso.com/index.html.

   

4. Na seção Concessão implícita e fluxos híbridos, ative as opções Tokens de acesso (usados para fluxos implícitos) e Tokens de ID (usados para fluxos implícitos e híbridos).

5. Selecione Configurar.

Encontrar a URL do ponto de extremidade do token do copiloto

1. No, Copilot Studio, acesse as Configurações e selecione Canais.

2. Selecione Aplicativo móvel.

3. Em Ponto de extremidade do token, selecione Copiar.

   

Configure o SSO em sua página da Web

Use o código fornecido no Repositório do GitHub do Copilot Studio para criar uma página da Web para o URL de redirecionamento. Copie o código do repositório do GitHub e modifique-o usando as instruções abaixo.

1. Acesse a página Visão geral no portal do Azure e copie o ID do aplicativo (cliente) e o ID do diretório (locatário) a partir do registro do seu aplicativo de tela.

   

2. Para configurar o Microsoft Authentication Library (MSAL):

   • Atribua clientId para a sua ID do aplicativo (cliente).
   • Atribua authority para https://login.microsoftonline.com/ e adicione a sua ID do diretório (locatário) até o fim.

   Por exemplo:

   var clientApplication;
       (function (){
       var msalConfig = {
           auth: {
               clientId: '692e92c7-xxxx-4060-76d3-b381798f4d9c',
               authority: 'https://login.microsoftonline.com/7ef988bf-xxxx-51af-01ab-2d7fd011db47'     
           },
   

3. Defina a variável theURL para o URL do ponto de extremidade do token que você copiou anteriormente. Por exemplo:

   (async function main() {
   
       var theURL = "https://1c0.0.environment.api.powerplatform.com/powervirtualagents/bots/5a099fd/directline/token?api-version=2022-03-01-preview"
   

4. Edite o valor de userId para incluir um prefixo personalizado. Por exemplo:

   var userId = clientApplication.account?.accountIdentifier != null ? 
           ("My-custom-prefix" + clientApplication.account.accountIdentifier).substr(0, 64) 
           : (Math.random().toString() + Date.now().toString()).substr(0,64);
   

5. Salve suas alterações.

Teste seu copiloto usando sua página da Web

1. Abra sua página da Web em seu navegador.

2. Selecione Logon.

   

   Observação

   Se o seu navegador bloquear pop-ups ou se você estiver usando uma janela de navegação anônima ou privada, você precisará fazer login. Caso contrário, o logon é concluído usando um código de validação.

   Uma nova guia do navegador é aberta.

3. Alterne para a nova guia e copie o código de validação.

4. Volte para a guia com o copiloto e cole o código de validação na conversa do copiloto.

Artigos relacionados

• Registro do Azure App

Clássico

Visão geral técnica

A ilustração a seguir mostra como um usuário é conectado sem ver um prompt de logon (SSO) no Copilot Studio:

1. O usuário do copiloto digita uma frase que dispara um tópico de credenciais. O tópico de credenciais foi criado para conectar o usuário e usar o token autenticado (variável AuthToken) do usuário.

2. O Copilot Studio envia um prompt de logon para permitir que o usuário entre com seu provedor de identidade configurado.

3. A tela personalizada do copiloto intercepta o prompt de entrada e solicita um token OBO (em nome de) do Microsoft Entra ID. A tela envia o token para o copiloto.

4. Ao receber o token OBO, o copiloto troca o token OBO por um "token de acesso" e preenche a variável AuthToken usando o valor do token de acesso. A variável IsLoggedIn também é definida nesse momento.

Criar um registro de aplicativo no Microsoft Entra ID para sua tela personalizada

Para habilitar o SSO, você precisará de dois registros de aplicativo separados:

• Um para seu copiloto para habilitar a autenticação do usuário com o Microsoft Entra ID.
• Um para sua tela personalizada para habilitar o SSO.

Importante

Você não pode reutilizar o mesmo registro de aplicativo para autenticação de usuário do copiloto e sua tela personalizada.

Criar um registro de aplicativo para a tela do copiloto

1. Entre no Portal do Azure.

2. Acesse Registros de aplicativo selecionando o ícone ou pesquisando na barra de pesquisa superior.

   

3. Selecione Novo registro.

   

4. Insira um nome para o registro. Pode ser útil usar o nome do copiloto cuja tela você está registrando, e incluir "tela" para ajudar a diferenciá-lo do registro do aplicativo para autenticação.

   Por exemplo, se o nome do seu copiloto for "Ajuda de vendas do Contoso", você poderá nomear o registro do aplicativo como "TeladeVendasdoContoso", ou algo semelhante.

5. Selecione o tipo de conta em Tipos de conta com suporte. Recomendamos que você selecione Contas em qualquer diretório organizacional (Qualquer diretório do Microsoft Entra ID - Multilocatário) e contas pessoais da Microsoft (por exemplo, Skype, Xbox).

6. Deixe a seção URI de Redirecionamento em branco por enquanto, pois você inserirá essas informações nas próximas etapas. Selecione Registrar.

   

7. Após a conclusão do registro, ele abre na página Visão geral. Acesse Manifesto. Confirme se accessTokenAcceptedVersion está definido como 2. Se não estiver, altere para 2 e selecione Salvar.

Adicionar a URL de redirecionamento

1. Com o registro aberto, acesse Autenticação e selecione Adicionar uma plataforma.

   

2. Na folha configurar plataformas, selecione Web.

   

3. Em URIs de Redirecionamento, adicione a URL completa à página em que sua tela de conversa está hospedada. Na seção Concessão implícita, marque as caixas de seleção Tokens de Identificação e Tokens de Acesso.

4. Selecione Configurar para confirmar as alterações.

   

5. Acesse Permissões da API. Selecione Conceder consentimento de administração para <seu nome de locatário> e, em seguida, Sim.

   Importante

   Para evitar que os usuários tenham que dar consentimento em cada aplicativo, um Administrador global, um Administrador de aplicativos ou um Administrador de aplicativos de nuvem deve conceder consentimento para todo o locatário aos registros do seu aplicativo.

   

Defina um escopo personalizado para seu copiloto

Defina um escopo personalizado expondo uma API para o registro do aplicativo de tela dentro do registro do aplicativo de autenticação. Escopos permitem determinar funções de usuário e administrador, além de direitos de acesso.

Essa etapa cria uma relação de confiança entre o registro do aplicativo de autenticação a ser autenticado e o registro do aplicativo para a tela personalizada.

1. Abra o registro do aplicativo que você criou quando configurou a autenticação.

2. Acesse Permissões da API e verifique se as permissões corretas foram adicionadas ao seu copiloto. Selecione Conceder consentimento de administração para <seu nome de locatário> e, em seguida, Sim.

   Importante

   Para evitar que os usuários tenham que dar consentimento em cada aplicativo, um Administrador global, um Administrador de aplicativos ou um Administrador de aplicativos de nuvem deve conceder consentimento para todo o locatário aos registros do seu aplicativo.

3. Acesse Expor uma API e selecione Adicionar um escopo.

   

4. Insira um nome para o escopo, junto com as informações de exibição que devem ser mostradas aos usuários quando eles acessam a tela de SSO. Selecione Adicionar escopo.

   

5. Selecione Adicionar um aplicativo cliente.

6. Insira o ID do aplicativo (cliente) da página Visão geral para o registro do aplicativo de tela no campo ID do cliente. Marque a caixa de seleção do escopo listado que você criou.

7. Selecione Adicionar aplicativo.

Configurar autenticação mo Copilot Studio para habilitar o SSO

A URL de troca de tokens na página de configuração de autenticação do Copilot Studio é usada para trocar o token OBO pelo token de acesso solicitado por meio da estrutura do bot.

O Copilot Studio chama o Microsoft Entra ID para executar a troca real.

1. Entre no Copilot Studio.

2. Confirme se você selecionou o copiloto para o qual deseja habilitar a autenticação, selecionando o ícone do copiloto no menu superior e escolhendo o copiloto correto.

3. No menu de navegação, em Configurações, selecione Segurança. Em seguida, selecione o cartão Autenticação.

   

4. Insira o URI de escopo completo da folha Expor uma API para o registro do aplicativo de autenticação do copiloto no campo URL de troca de token. A URI do canal está no formato de api://1234-4567/scope.name.

   

   

5. Selecione Salvar e publique o conteúdo do copiloto.

Configurar seu código HTML de tela personalizada para habilitar o SSO

Atualize a página de tela personalizada em que o copiloto está localizado para interceptar a solicitação do cartão de logon e trocar o token OBO.

1. Configure a Microsoft Authentication Library (MSAL) adicionando o código a seguir em um rótulo de <script> na sua seção <head>.

2. Atualize o clientId com o ID do aplicativo (cliente) para o registro do aplicativo de tela. Substitua <Directory ID> pelo ID do diretório (locatário). Você obtém esses IDs na página Visão geral do registro do aplicativo de tela.

   

   <head>
    <script>
      var clientApplication;
        (function () {
          var msalConfig = {
              auth: {
                clientId: '<Client ID [CanvasClientId]>',
                authority: 'https://login.microsoftonline.com/<Directory ID>'
              },
              cache: {
                cacheLocation: 'localStorage',
                storeAuthStateInCookie: false
              }
          };
          if (!clientApplication) {
            clientApplication = new Msal.UserAgentApplication(msalConfig);
          }
        } ());
    </script>
   </head>
   

3. Insira o seguinte <script> na seção <body>. Esse script chama um método para recuperar o resourceUrl e trocar seu token atual por um token solicitado pelo prompt do OAuth.

   <script>
   function getOAuthCardResourceUri(activity) {
     if (activity &&
          activity.attachments &&
          activity.attachments[0] &&
          activity.attachments[0].contentType === 'application/vnd.microsoft.card.oauth' &&
          activity.attachments[0].content.tokenExchangeResource) {
            // asking for token exchange with Microsoft Entra ID
            return activity.attachments[0].content.tokenExchangeResource.uri;
      }
   }
   
   function exchangeTokenAsync(resourceUri) {
     let user = clientApplication.getAccount();
      if (user) {
        let requestObj = {
          scopes: [resourceUri]
        };
        return clientApplication.acquireTokenSilent(requestObj)
          .then(function (tokenResponse) {
            return tokenResponse.accessToken;
            })
            .catch(function (error) {
              console.log(error);
            });
            }
            else {
            return Promise.resolve(null);
      }
   }
   </script>
   

4. Insira o seguinte <script> na seção <body>. No do método main, esse código adiciona uma condicional ao seu store, com o identificador exclusivo do seu copiloto. Ele também gera um ID exclusivo como sia variável de userId.

5. Atualize <COPILOT ID> com o ID do seu copiloto. Você pode ver o ID do seu copiloto acessando a guia Canais do copiloto que você está usando, e selecionando Aplicativo móvel no portal do Copilot Studio.

   

   <script>
       (async function main() {
   
           // Add your COPILOT ID below 
           var BOT_ID = "<BOT ID>";
           var theURL = "https://powerva.microsoft.com/api/botmanagement/v1/directline/directlinetoken?botId=" + BOT_ID;
   
           const {
               token
           } = await fetchJSON(theURL);
   
           var directline = await fetchJSON(regionalChannelSettingsURL).then(res=> res.channelUrlsById.directline); 
   
           const directLine = window.WebChat.createDirectLine({
               domain: `${directline}v3/directline`,
               token
           });
   
           var userID = clientApplication.account?.accountIdentifier != null ?
               ("Your-customized-prefix-max-20-characters" + clientApplication.account.accountIdentifier).substr(0, 64) :
               (Math.random().toString() + Date.now().toString()).substr(0, 64); // Make sure this will not exceed 64 characters 
           const store = WebChat.createStore({}, ({
               dispatch
           }) => next => action => {
               const {
                   type
               } = action;
               if (action.type === 'DIRECT_LINE/CONNECT_FULFILLED') {
                   dispatch({
                       type: 'WEB_CHAT/SEND_EVENT',
                       payload: {
                           name: 'startConversation',
                           type: 'event',
                           value: {
                               text: "hello"
                           }
                       }
                   });
                   return next(action);
               }
               if (action.type === 'DIRECT_LINE/INCOMING_ACTIVITY') {
                   const activity = action.payload.activity;
                   let resourceUri;
                   if (activity.from && activity.from.role === 'bot' &&
                       (resourceUri = getOAuthCardResourceUri(activity))) {
                       exchangeTokenAsync(resourceUri).then(function(token) {
                           if (token) {
                               directLine.postActivity({
                                   type: 'invoke',
                                   name: 'signin/tokenExchange',
                                   value: {
                                       id: activity.attachments[0].content.tokenExchangeResource.id,
                                       connectionName: activity.attachments[0].content.connectionName,
                                       token,
                                   },
                                   "from": {
                                       id: userID,
                                       name: clientApplication.account.name,
                                       role: "user"
                                   }
                               }).subscribe(
                                   id => {
                                       if (id === 'retry') {
                                           // copilot was not able to handle the invoke, so display the oauthCard
                                           return next(action);
                                       }
                                       // else: tokenexchange successful and we do not display the oauthCard
                                   },
                                   error => {
                                       // an error occurred to display the oauthCard
                                       return next(action);
                                   }
                               );
                               return;
                           } else
                               return next(action);
                       });
                   } else
                       return next(action);
               } else
                   return next(action);
           });
   
           const styleOptions = {
   
               // Add styleOptions to customize Web Chat canvas
               hideUploadButton: true
           };
   
           window.WebChat.renderWebChat({
                   directLine: directLine,
                   store,
                   userID: userID,
                   styleOptions
               },
               document.getElementById('webchat')
           );
       })().catch(err => console.error("An error occurred: " + err));
   </script>
   

Exemplo de código completo

Para obter mais informações, você pode encontrar o exemplo de código completo, com os scripts condicionais da loja e MSAL já inclusos no nosso repositório GitHub.