Configurar a autenticação OBO para conectores personalizados

Os conectores personalizados com autenticação Microsoft Entra ID podem suportar a autenticação "On-Behalf-Of" (OBO). A autenticação OBO permite uma experiência de utilizador totalmente integrada nas conversações de agentes.

Quando o agente utiliza a autenticação OBO para um conector, o agente pede ao utilizador que lhe conceda permissão para aceder a recursos e realizar ações em nome do utilizador. O utilizador pode escolher permitir ou negar esta permissão.

Assim que o utilizador concede permissão, o agente pode aceder ao serviço de forma transparente em nome do utilizador.

Passos para configurar a autenticação OBO com Microsoft Entra ID

Para ativar a autenticação OBO para um conector personalizado utilizando o Microsoft Entra ID, conclua os seguintes passos:

1. (Opcional) Crie um registo de aplicação de serviço para a sua API personalizada ou servidor MCP (Model Context Protocol). Só é necessário efetuar este passo se estiver a aceder a uma API ou serviço personalizados. Não é necessário criar um novo registo de aplicação de serviço para um serviço Microsoft como Microsoft Graph.

2. Crie um registo de aplicação de conector, adicione um âmbito personalizado e configure permissões.

3. Configure a autenticação para o seu conector personalizado.

4. Partilhe o conector personalizado com utilizadores finais.

Passo 1 (Opcional): Criar um registo de aplicação de serviço para a sua API personalizada ou servidor MCP

Se o seu conector personalizado precisar de aceder a uma API personalizada ou a um servidor MCP que valide tokens do Microsoft Entra ID, é necessário criar um registo de aplicação para representar o serviço.

1. Navegue até Registos de aplicações no Portal do Azure.

2. Selecione Novo registo.

3. Introduza um nome para o registo da sua aplicação (por exemplo, "HR API Hub").

4. Para Tipos de conta suportados, selecione os tipos de conta suportados adequados ao seu cenário.

5. Selecione Registar.

6. Depois de criar o registo da aplicação, aceda a Expor uma API.

7. Selecione Adicionar âmbito.

8. Se lhe for pedido, defina o ID da aplicação (pode aceitar a predefinição).

9. Introduza os detalhes do âmbito:

   • Nome do âmbito: introduza um nome para o âmbito (por exemplo, employee.read).
   • Quem pode consentir: selecione a opção adequada para o seu cenário.
   • Nome de exibição para consentimento do administrador: introduza um nome a apresentar.
   • Descrição do consentimento do administrador: introduza uma descrição.
   • Estado: Selecione Ativado.

10. Selecione Adicionar escopo.

Passo 2: Criar um registo de aplicação de conector e configurar permissões

Criar um registo de aplicação para o seu conector personalizado

Crie um registo de aplicação que represente o seu conector personalizado e configure as permissões delegadas necessárias.

1. Navegue até Registos de aplicações no Portal do Azure.

2. Selecione Novo registo.

3. Introduza um nome para o registo da aplicação (por exemplo, "Conector de API de RH" ou "Conector de Ficheiros do Graph").

4. Em Tipos de conta suportados, selecione Contas só neste diretório organizacional (Inquilino único). Não adicione um URI de redirecionamento neste momento. Configure o URI de redirecionamento mais tarde ao criar o conector personalizado.

5. Selecione Registar.

6. Depois de criar o registo da aplicação, navegue para Permissões da API.

7. Selecione Adicionar uma permissão.

8. Configure permissões com base no seu cenário:

   • Para APIs personalizadas:
     1. Selecione APIs que a minha organização utiliza
     2. Procure o ID da Aplicação (cliente) do registo da sua aplicação de serviço no Passo 1 e selecione-o.
     3. Selecione Permissões delegadas e selecione o âmbito que criou para o serviço (por exemplo, employee.read).
   • Para serviços Microsoft:
     1. Selecione APIs Microsoft.
     2. Selecione o serviço (por exemplo, Microsoft Graph).
     3. Selecione Permissões delegadas.
     4. Selecione as permissões apropriadas (por exemplo, Files.Read.All).

9. Selecione Adicionar permissões.

10. Selecione Conceder consentimento do administrador para a [sua organização] e confirme quando lhe for pedido.

Criar um segredo do cliente

1. No registo da sua aplicação de conector, navegue até Certificados e segredos.

2. Selecione Novo segredo do cliente.

3. Introduza uma descrição para o segredo (por exemplo, "Segredo do conector").

4. Selecione um período de expiração com base nas políticas de segurança da sua organização.

5. Selecione Adicionar.

6. Copie imediatamente o Valor do segredo.

Expor uma API e autorizar o principal de serviço das Ligações de API do Azure

Para ativar a autenticação OBO, é necessário tornar uma API disponível no registo da aplicação do conector e autenticar o principal de serviço do Azure API Connections.

1. No registo da aplicação do conector, vá para Publicar uma API.

2. Selecione Adicionar âmbito.

3. Se lhe for pedido, defina o ID da aplicação (pode aceitar a predefinição).

4. Introduza os detalhes do âmbito:

   • Nome do âmbito: introduza um nome para o âmbito (por exemplo, access_as_user).
   • Quem pode consentir: selecione Administradores e utilizadores.
   • Nome de exibição para consentimento do administrador: introduza um nome de exibição (por exemplo, "Permitir que as conexões API do Azure obtenham tokens em nome dos utilizadores").
   • Descrição do consentimento do administrador: introduza uma descrição (por exemplo, "Permite que o serviço Ligações API do Azure obtenha tokens em nome do utilizador").
   • Nome a apresentar para consentimento do utilizador: Introduza um nome a apresentar (por exemplo, "Permitir que o conector atue em nome do utilizador").
   • Descrição do consentimento do utilizador: introduza uma descrição (por exemplo, "Permite que o serviço Ligações API do Azure obtenha tokens e aceda a recursos em seu nome").
   • Estado: Selecione Ativado.

5. Selecione Adicionar escopo.

6. Na secção Aplicações cliente autorizadas, selecione Adicionar uma aplicação cliente.

7. Introduza o ID de cliente para o principal de serviço Ligações API do Microsoft Azure: fe053c5f-3692-4f14-aef2-ee34fc081cae.

8. Selecione o âmbito que criou.

9. Selecione Adicionar aplicativo.

É necessário autorizar o principal de serviço Ligações API do Azure a iniciar sessão em nome dos utilizadores. Sem esta configuração, os utilizadores teriam de iniciar sessão explicitamente sempre que utilizassem o conector.

Esta configuração permite que o serviço Ligações API do Azure obtenha tokens em nome dos utilizadores que iniciam sessão no conector personalizado.

Passo 3: Configurar a autenticação para o conector personalizado

Se ainda não tiver um conector personalizado, siga os passos indicados em Criar um conector personalizado do zero para criar um antes de avançar.

Configurar as definições de autenticação do Power Apps para o conector personalizado

1. No Power Apps, navega até Conectores personalizados.

2. Selecione o seu conector personalizado na lista.

3. Selecione a guia Segurança .

4. Em Tipo de Autenticação, selecione OAuth 2.0.

5. Para Identity Provider, selecione Microsoft Entra ID.

6. Introduza as seguintes informações:

   • ID de Cliente: introduza o ID da aplicação (cliente) a partir do registo da aplicação do conector (criado no Passo 2).
   • Segredo do cliente: introduza o valor do segredo do cliente a partir do registo da aplicação do conector (criado no Passo 2).
   • URL de autorização: deixe a predefinição (https://login.microsoftonline.com).
   • ID de Inquilino: deixe a predefinição (common) ou introduza o seu ID de inquilino específico.
   • URL de recurso: introduza o URL do recurso com base no seu cenário:
     • Para APIs personalizadas: introduza o URI do ID da aplicação a partir do registo da aplicação de serviço (criado no Passo 1). Por exemplo, api://b52b5b7a-e895-4600-b567-2c4cbe27d2e7.
     • Para serviços Microsoft: introduza o URL de recurso apropriado para o serviço a que está a aceder. Por exemplo:
       • Microsoft Graph: https://graph.microsoft.com
       • SharePoint: https://mycompany.sharepoint.com
       • Dynamics 365: https://mycompany.crm.dynamics.com
   • Ativar início de sessão em nome de: defina como true.
   • Âmbito: introduza um ou mais âmbitos a pedir, separados por espaços:
     • Para APIs personalizadas: introduza o âmbito completo a partir do registo da aplicação de serviço no Passo 1. Por exemplo, api://b52b5b7a-e895-4600-b567-2c4cbe27d2e7/employee.read.
     • Para serviços Microsoft: introduza o âmbito da permissão delegada. Por exemplo, Files.Read.All User.Read para o Microsoft Graph.

7. Selecione Atualizar conector para guardar as alterações. É apresentado um URL de redirecionamento.

8. Copie o URL de redirecionamento. É necessário adicionar o URL de redirecionamento ao registo da aplicação do conector no passo seguinte.

Adicionar o URL de redirecionamento ao registo da aplicação de ligação

1. Navegue até Registos de aplicações no Portal do Azure.

2. Selecione o registo da aplicação do conector.

3. Navegue até Autenticação.

4. Selecione Adicionar uma plataforma.

5. Selecione Web.

6. Introduza o URL de redirecionamento que foi gerado no Power Apps.

7. Selecione Configurar.

Passo 4: Partilhar o conector personalizado com utilizadores finais

Depois de configurar o seu conector personalizado, é necessário partilhá-lo com os utilizadores adequados para que possam utilizá-lo nas conversações com os agentes.

Para partilhar o conector personalizado, siga as instruções indicadas em Partilhar um conector personalizado na sua organização.

Ao partilhar o conector, considere os seguintes níveis de permissões:

• Criadores a colaborar no agente: conceda permissões Pode editar aos criadores que precisam de configurar e gerir o conector personalizado no agente.
• Utilizadores finais em conversas com o agente: Conceda permissões de visualização aos utilizadores que iniciam sessão e usam o conector durante as conversas com agentes.