Habilitar a detecção e a proteção de ameaças externas para agentes personalizados do Copilot Studio (versão preliminar)

[Este artigo faz parte da documentação de pré-lançamento e está sujeito a alterações.]

Os agentes personalizados criados no Copilot Studio são seguros por padrão. Eles têm proteção interna contra várias ameaças, como UPIA (ataques de injeção de prompt de usuário) e XPIA (ataques de injeção de prompt entre domínios). Em runtime, o agente bloqueia ataques desses tipos, reduzindo o risco de exfiltração de dados.

Para aumentar ainda mais os recursos de monitoramento e a segurança de agentes personalizados, o Copilot Studio permite que as organizações configurem sistemas externos de detecção de ameaças para supervisão aprimorada. Essas ferramentas operam durante o runtime do agente, avaliando, de forma contínua, a atividade do agente. Se o sistema detectar quaisquer ferramentas ou ações suspeitas, ele poderá intervir para impedi-las de serem executadas. Essa detecção de ameaças fornece uma camada extra de proteção em tempo real e imposição de conformidade.

Como funciona

Um sistema de detecção de ameaças externas é configurado como um serviço Web, expondo uma API REST com um ponto de extremidade de detecção de ameaças. Uma conexão segura é configurada entre o agente e o endereço de destino. Em tempo de execução, sempre que o orquestrador considera invocar uma ferramenta, ele envia dados relevantes sobre o uso da ferramenta proposta para o endpoint de detecção de ameaças para avaliação. O sistema de detecção de ameaças analisa os dados e retorna uma decisão de permitir ou bloquear a invocação da ferramenta.

Se o sistema de detecção de ameaças detectar um problema de segurança durante a operação de um agente, o agente interromperá imediatamente o processamento e notificará o usuário de que sua mensagem está bloqueada. Por outro lado, se o sistema aprovar a operação, o agente continuará diretamente, sem nenhum efeito visível ou interrupção para o usuário.

Opções para configurar a detecção de ameaças externas

O Copilot Studio dá suporte a uma abordagem flexível de "traga sua própria proteção". As organizações possuem a liberdade de integrar soluções de segurança que melhor se adaptem aos seus requisitos exclusivos.

As opções incluem:

• Desenvolva suas próprias ferramentas de monitoramento personalizadas ou faça com que alguém as desenvolva para você. Para obter mais informações sobre como configurar o ponto de extremidade do sistema para que o agente possa se conectar a ele, consulte Criar um sistema de detecção de ameaças de runtime para agentes do Copilot Studio
• Aplicar uma solução empresarial robusta pelo Microsoft Defender
• Usar produtos de outros provedores de segurança confiáveis

Quais dados são compartilhados com o provedor de detecção de ameaças?

Depois de configurar uma conexão com um sistema de detecção de ameaças, o agente compartilhará dados com o provedor de segurança externo durante sua execução. O agente se comunica com o serviço sempre que considera invocar uma ferramenta. Esse compartilhamento de dados assegura uma tomada de decisão eficiente pelo sistema configurado, sem prejudicar a experiência dos usuários do agente.

Os dados de alto nível compartilhados com o sistema incluem:

• O prompt recente do usuário e o histórico mais recente de mensagens de chat trocadas entre o agente e o usuário.
• Saídas de ferramentas anteriores usadas pelo agente.
• Metadados de conversa: identidade do agente, o usuário que interage com ele, o locatário do usuário e o gatilho que o disparou (quando aplicável).
• A ferramenta que o agente deseja invocar, incluindo o raciocínio gerado pelo agente de por que essa ferramenta foi selecionada e as entradas e valores propostos.

Pré-requisitos

Antes de começar, você precisa de:

• Um serviço de detecção de ameaças externas configurado para avaliar solicitações de uso das ferramentas dos agentes. O serviço precisa expor um endpoint da API REST. Para a configuração no lado do Copilot Studio da integração, você precisa da URL base para o serviço Web do provedor de segurança. Este artigo refere-se a essa URL como o endpoint. O agente envia solicitações de detecção de ameaças para APIs nessa URL base. Você deve receber essa URL do provedor de segurança.
• Um tenant do Microsoft Entra onde você pode cadastrar um aplicativo para autenticação entre o agente e o serviço de detecção de ameaças.
• Um usuário com uma função de Administrador do Power Platform para configurar uma conexão entre o agente e o sistema de detecção de ameaças externas para o nível de ambiente individual e o nível do grupo de ambiente.

Configurar um sistema de detecção de ameaças externas

O processo para configurar um sistema de detecção de ameaças externas para seu agente tem duas etapas:

1. Configurar um aplicativo do Microsoft Entra ID.
2. Configurar a detecção de ameaças no Centro de administração do Power Platform.

Etapa 1: Configurar um aplicativo do Microsoft Entra

Há dois caminhos que você pode usar para configurar um aplicativo do Microsoft Entra:

• Opção A: Configurar usando o script do PowerShell (recomendado)
• Opção B: configurar manualmente usando o portal do Azure

Opção A: configurar usando o PowerShell (recomendado)

Você pode usar um script fornecido do PowerShell para automatizar a criação e a configuração do aplicativo Microsoft Entra.

Pré-requisitos para a configuração do PowerShell

• Windows PowerShell 5.1 ou posterior
• Permissões suficientes para criar registros de aplicativo em seu locatário do Microsoft Entra
• A URL base do serviço Web de detecção de ameaças. A URL é referida como Endpoint nos parâmetros de script que seguem. Você deve receber essa URL do provedor de segurança.
• A ID do locatário do Microsoft Entra da organização. O ID do locatário é referido como TenantId nos parâmetros de script a seguir.

Baixar e preparar o script

Baixe o script Create-CopilotWebhookApp.ps1.

Parâmetros de script

O script aceita os seguintes parâmetros:

Executar o script

Para criar o aplicativo:

1. Abra o Windows PowerShell como administrador.

2. Vá para o diretório que contém o script.

3. Execute o script a seguir, substituindo os valores de espaço reservado para TenantId, Endpoint, DisplayName e FICName pelos próprios parâmetros:

   .\Create-CopilotWebhookApp.ps1 `
   -TenantId "11111111-2222-3333-4444-555555555555" `
   -Endpoint "https://provider.example.com/threat_detection/copilot" `
   -DisplayName "Copilot Security Integration - Production" `
   -FICName "ProductionFIC"
   

O script interativo é executado na linha de comando. O script gera a ID do aplicativo do Microsoft Entra criado. Você precisará da ID do aplicativo mais tarde ao configurar a detecção de ameaças no Centro de administração do Power Platform.

Opção B: configurar manualmente usando o portal do Azure

Pré-requisitos para configuração manual

• A ID do locatário do Microsoft Entra da organização. A ID do locatário é conhecida como tenantId nas instruções a seguir.
• Permissões suficientes para criar registros de aplicativo em seu tenant do Microsoft Entra.
• A URL base do serviço Web de detecção de ameaças que você está usando. Isso é referido como o endpoint nas instruções a seguir. Você deve receber essa URL do provedor de segurança.

Registrar um aplicativo do Microsoft Entra ID

Siga estas etapas para criar um registro de aplicativo do Microsoft Entra. O aplicativo é usado para proteger a autenticação entre o agente e o serviço Web de detecção de ameaças. Consulte Registrar um aplicativo no Microsoft Entra ID para saber como criar esse aplicativo.

1. Entre no portal do Azure e navegue até a página Microsoft Entra ID.
2. Em Registros de aplicativo, selecione Novo registro.
3. Forneça um nome e selecione Contas somente neste diretório organizacional (Locatário único) como o tipo de conta com suporte.
4. Registre o aplicativo.
5. Depois que o aplicativo for criado, copie a ID do aplicativo. Você precisará da ID do aplicativo mais tarde ao configurar a detecção de ameaças no Centro de administração do Power Platform.

Autorize o aplicativo Microsoft Entra com seu provedor de escolha

O agente usa o FIC (Federated Identity Credentials) como um método de autenticação seguro e sem segredo para trocar dados com o provedor do sistema de detecção de ameaças. Siga estas etapas para configurar o FIC para seu aplicativo Microsoft Entra. Para obter mais informações, consulte Configurar uma identidade gerenciada atribuída pelo usuário para confiar em um provedor de identidade externo.

1. Abra o portal do Azure e acesse registros de aplicativo. Selecione o aplicativo que você criou na etapa 1 acima.

2. Na barra lateral, selecione Gerenciar>Certificados & segredos>Credenciais federadas.

3. Selecione Adicionar credencial.

4. Na lista suspensa do cenário de credenciais Federadas, selecione Outro emissor.

5. Preencha os campos de acordo com estas instruções:

   • Emissor: insira a seguinte URL, substituindo {tenantId} pela ID do locatário do Microsoft Entra da sua organização: https://login.microsoftonline.com/{tenantId}/v2.0

   • Tipo: selecione Identificador de entidade explícito.

   • Valor: insira uma cadeia de caracteres estruturada da seguinte maneira: /eid1/c/pub/t/{base 64 encoded tenantId}/a/m1WPnYRZpEaQKq1Cceg--g/{base 64 encoded endpoint}

     Realize a codificação base64 para a ID de locatário do Microsoft Entra da organização e a URL base do serviço Web da detecção de ameaças. Substitua o espaço reservado {base 64 encoded tenantId} pelo valor codificado em base64 da ID do locatário e pelo espaço reservado {base 64 encoded endpoint} com a URL base codificada em base64.

     Para obter a codificação base64 da ID do locatário e a URL do ponto de extremidade, use o script do PowerShell a seguir. Substitua os valores de espaço reservado "11111111-2222-3333-4444-555555555555" e "https://provider.example.com/threat_detection/copilot"" pelos valores reais de ID do locatário e URL do ponto de extremidade:

     # Encoding tenant ID
     $tenantId = [Guid]::Parse("11111111-2222-3333-4444-555555555555")
     $base64EncodedTenantId = [Convert]::ToBase64String($tenantId.ToByteArray()).Replace('+','-').Replace('/','_').TrimEnd('=')
     Write-Output $base64EncodedTenantId
     
     # Encoding the endpoint
     $endpointURL = "https://provider.example.com/threat_detection/copilot"
     $base64EncodedEndpointURL = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($endpointURL)).Replace('+','-').Replace('/','_').TrimEnd('=')
     Write-Output $base64EncodedEndpointURL
     

   • Nome: escolha um nome descritivo.

6. Selecione o botão Adicionar .

Etapa 2: configurar o sistema de detecção de ameaças

Em seguida, você precisa configurar o sistema de detecção de ameaças no centro de administração do Power Platform para conectar seu agente ao provedor de segurança externo.

Pré-requisitos para configurar a detecção de ameaças no Centro de administração do Power Platform

• A ID do aplicativo Microsoft Entra que você criou na etapa anterior.
• O link do endpoint fornecido pelo provedor do sistema de monitoramento externo. O link do ponto de extremidade é o mesmo ponto de extremidade de URL base usado por você ao configurar o aplicativo Microsoft Entra.
• Um usuário com uma função de Administrador do Power Platform para configurar a conexão.
• Execute todas as outras etapas exigidas pelo provedor de segurança para autorizar seu aplicativo registrado. Você deve consultar a documentação do provedor (conforme aplicável) para quaisquer etapas específicas de integração e autorização.

Para configurar o sistema de detecção de ameaças no Centro de administração do Power Platform, siga estas etapas:

1. Entre no centro de administração do Power Platform.
2. Na navegação lateral, selecione Segurança e, em seguida, selecione Detecção de ameaças. A página de detecção de ameaças é aberta.
3. Selecione Detecção adicional de ameaças. Um painel é aberto.
4. Selecione o ambiente para o qual você deseja aprimorar a proteção do agente e selecione Configurar. Um painel é aberto.
5. Selecione Permitir que o Copilot Studio compartilhe dados com um provedor de detecção de ameaças.
6. Na ID do Aplicativo do Azure Entra, insira a ID do aplicativo Microsoft Entra que você criou anteriormente.
7. Insira o link do endpoint fornecido pelo provedor do sistema de monitoramento externo. O link do ponto de extremidade é o mesmo ponto de extremidade de URL base usado por você ao configurar o aplicativo Microsoft Entra.
8. Em Definir o comportamento de erro, defina o comportamento padrão do sistema para quando o sistema de detecção de ameaças não responder a tempo ou responder com um erro. Por padrão, isso é definido como Permitir que o agente responda, mas você também pode escolher a opção Bloquear a consulta para reduzir ainda mais o risco.
9. Clique em Salvar.

Resolução de problemas

Aqui estão algumas informações sobre problemas que podem ocorrer e como lidar com eles.

Problemas de configuração de detecção de ameaças do Centro de Administração do Power Platform

A tabela a seguir descreve erros comuns que podem acontecer quando você seleciona Salvar na etapa anterior e como lidar com esses erros:

Para obter mais detalhes de erro, selecione Copiar informações de erro.

Problemas comuns de autenticação e do Microsoft Entra

Aqui estão alguns outros problemas comuns que podem ocorrer com seu aplicativo Microsoft Entra e a autenticação.

O aplicativo Microsoft Entra não existe

Exemplo: falha ao adquirir token: AADSTS700016: o aplicativo com identificador '55ed00f8-faac-4a22-9183-9b113bc53dd4' não foi encontrado no diretório da 'Contoso'. Isso pode acontecer se o aplicativo não for instalado pelo administrador do locatário ou consentido por qualquer usuário no locatário. Você pode ter enviado sua solicitação de autenticação para o locatário errado.

Como lidar: verifique se a ID do aplicativo fornecida está correta e existe no Azure.

Nenhum FIC configurado no aplicativo

Exemplo: Falha ao adquirir o token: um problema de configuração está impedindo a autenticação — verifique a mensagem de erro do servidor para obter detalhes. Você pode modificar a configuração no portal de registro do aplicativo. Consulte https://aka.ms/msal-net-invalid-client para obter detalhes. Exceção original: AADSTS70025: o cliente '57342d48-0227-47cd-863b-1f4376224c21'(Teste de webhooks) não tem credenciais de identidade federadas configuradas.

Como lidar: o aplicativo fornecido não tem nenhum FIC configurado nele. Siga a documentação e configure o FIC adequadamente.

Emissor FIC inválido

Exemplo: Falha ao adquirir o token: um problema de configuração está impedindo a autenticação — verifique a mensagem de erro do servidor para obter detalhes. Você pode modificar a configuração no portal de registro do aplicativo. Consulte https://aka.ms/msal-net-invalid-client para obter detalhes. Exceção original: AADSTS7002111: nenhum registro de identidade federado correspondente encontrado para o emissor de declaração apresentado 'https://login.microsoftonline.com/262d6d26-0e00-40b3-9c2f-31501d4dcbd1/v2.0'. Verifique se o emissor da credencial de identidade federada é 'https://login.microsoftonline.com/{tenantId}/v2.0'.

Como lidar: Nenhum FIC com o emissor esperado foi encontrado no aplicativo. Abra a configuração de FIC e defina o emissor como https://login.microsoftonline.com/{tenantId}/v2.0 (preenchendo sua ID de locatário).

Entidade FIC Inválida

Exemplo: Falha ao adquirir o token: um problema de configuração está impedindo a autenticação — verifique a mensagem de erro do servidor para obter detalhes. Você pode modificar a configuração no portal de registro do aplicativo. Consulte https://aka.ms/msal-net-invalid-client para obter detalhes. Exceção original: AADSTS7002137: nenhum registro de identidade federado correspondente encontrado para a entidade de asserção apresentada '/eid1/c/pub/t/Jm0tJgAOs0CcLzFQHU3L0Q/a/iDQPIrayM0GBBVzmyXgucw/aHR0cHM6Ly9jb250b3NvLnByb3ZpZGVyLmNvbeKAiw'. Verifique se a entidade de credencial de identidade federada é '/eid1/c/pub/t/{tenantId}/a/iDQPIrayM0GBBVzmyXgucw/aHR0cHM6Ly9jb250b3NvLnByb3ZpZGVyLmNvbeKAiw'.

Como lidar: nenhum FIC com a entidade esperada foi encontrado no aplicativo. Abra a configuração de FIC e defina a entidade para o valor esperado conforme sugerido no erro (preencha sua ID do locatário). Verifique se não há espaços de branco extras ou linhas em branco nos campos de entidade.

O aplicativo não está na lista de permissões com o provedor (específico do Microsoft Defender)

Exemplo: a ID do aplicativo no token de autenticação não corresponde ao aplicativo registrado para acesso ao webhook. Verifique se você está usando as credenciais corretas do aplicativo.

Como lidar: o aplicativo não está na lista de permissões com o provedor. Consulte a documentação do provedor para conceder acesso ao webhook do aplicativo.

Desconectar a proteção pelo sistema de detecção de ameaças

Se você não quiser mais que o sistema de detecção de ameaças monitore seu agente, siga estas etapas:

1. Entre no centro de administração do Power Platform.
2. Na navegação lateral, selecione Segurança e, em seguida, selecione Detecção de ameaças. A página de detecção de ameaças é aberta.
3. Selecione Detecção adicional de ameaças. Um painel é aberto.
4. Selecione o ambiente para o qual você deseja desativar a proteção avançada do agente e selecione Configurar. Um painel é aberto.
5. Desmarque a opção Permitir que o Copilot Studio compartilhe dados com seu provedor selecionado.
6. Clique em Salvar.