Ative a deteção e a proteção de ameaças externas para agentes personalizados do Copilot Studio (pré-visualização)

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

Os agentes personalizados criados no Copilot Studio são seguros por predefinição. Incluem proteção incorporada contra várias ameaças, como ataques de injeção de pedidos dos utilizadores (UPIA) e Ataques de injeção de pedidos entre domínios (XPIA). Em tempo de execução, 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 de deteção de ameaças externas para uma supervisão aprimorada. Estas ferramentas operam durante o runtime do agente, avaliando continuamente a atividade do agente. Se o sistema detetar quaisquer ferramentas ou ações suspeitas, pode intervir para bloquear a execução. Esta deteção de ameaças fornece uma camada adicional de proteção em tempo real e imposição de conformidade.

Como funciona

Um sistema externo de deteção de ameaças é configurado como um serviço Web, expondo uma API REST com um ponto de extremidade de deteção de ameaças. Uma ligação segura é configurada entre o agente e o ponto final. Durante o 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 deteção de ameaças para avaliação. O sistema de deteção de ameaças analisa os dados e retorna uma decisão de permitir ou bloquear a chamada da ferramenta.

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

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

O Copilot Studio suporta uma abordagem flexível de "traga sua própria proteção". As organizações têm 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 peça a alguém que as desenvolva para você. Para obter mais informações sobre como configurar o ponto de extremidade do sistema para que seu agente possa se conectar a ele, consulte Criar um sistema de deteção de ameaças em tempo de execução para agentes do Copilot Studio
• Aplique uma solução empresarial robusta pelo Microsoft Defender
• Utilize produtos de outros fornecedores de segurança fidedignos

Que dados são partilhados com o fornecedor de deteção de ameaças?

Depois de configurar uma conexão com um sistema de deteção de ameaças, o agente compartilha dados com o provedor de segurança externo durante sua execução. O agente comunica com o serviço sempre que considera invocar uma ferramenta. Esta partilha de dados garante uma tomada de decisão eficiente pelo sistema configurado, sem degradar a experiência dos utilizadores do seu agente.

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

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

Pré-requisitos

Antes de começar, você precisa:

• Um serviço de deteção de ameaças externo configurado para avaliar pedidos de utilização de ferramentas do agente. O serviço precisa expor um ponto de extremidade da API REST. Para a configuração do lado da integração do Copilot Studio, precisa do URL base para o serviço Web do fornecedor de segurança. Este artigo refere-se a este URL como o endpoint. O agente envia solicitações de deteção de ameaças para APIs nessa URL base. Deverá receber este URL do seu fornecedor de segurança.
• Um tenant do Microsoft Entra onde pode-se registar uma aplicação para autenticação entre o agente e o serviço de deteção de ameaças.
• Um usuário com uma função de Administrador da Power Platform para configurar uma conexão entre o agente e o sistema de deteção de ameaças externas para o nível de ambiente individual e o nível de grupo de ambiente.

Configurar um sistema de deteção de ameaças externo

O processo para configurar um sistema de deteção de ameaças externo para o seu agente tem dois passos:

1. Configure uma aplicação Microsoft Entra.
2. Configure a deteção de ameaças no centro de administração da Power Platform.

Etapa 1: Configurar um aplicativo Microsoft Entra

Há dois caminhos que você pode seguir para configurar um aplicativo 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 do PowerShell fornecido para automatizar a criação e a configuração do seu aplicativo Microsoft Entra.

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

• Windows PowerShell 5.1 ou posterior
• Permissões suficientes para criar registos de aplicações no seu inquilino do Microsoft Entra
• A URL base do serviço Web de deteção de ameaças. O URL é referido como o Endpoint nos parâmetros de script que se seguem. Deverá receber este URL do seu fornecedor de segurança.
• ID do tenant do Microsoft Entra da sua organização. O ID do locatário é chamado de TenantId nos parâmetros de script a seguir.

Transferir e preparar o script

Transfira o script Create-CopilotWebhookApp.ps1.

Parâmetros do script

O script aceita os seguintes parâmetros:

Executar o script

Para criar a aplicação:

1. Abra o Windows PowerShell como administrador.

2. Aceda ao diretório que contém o script.

3. Execute o seguinte script, substituindo os valores de espaço reservado para TenantId, Endpoint, DisplayNamee FICName com seus 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 Microsoft Entra criado. Você precisará da ID do aplicativo mais tarde ao configurar a deteção de ameaças no centro de administração da Power Platform.

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

Pré-requisitos para configuração manual

• ID de locatário Microsoft Entra da sua organização. O ID do locatário é chamado de tenantId nas instruções a seguir.
• Permissões suficientes para criar registos de aplicações no seu inquilino do Microsoft Entra.
• A URL base do serviço Web de deteção de ameaças que você está usando. Isso é conhecido como o ponto de extremidade nas instruções a seguir. Deverá receber este URL do seu fornecedor de segurança.

Registar uma aplicação Microsoft Entra

Siga estas etapas para criar um registro de aplicativo Microsoft Entra. O aplicativo é usado para proteger a autenticação entre o agente e o serviço Web de deteção de ameaças. Consulte Registar uma aplicação no Microsoft Entra ID para obter informações sobre como criar essa aplicação.

1. Entre no portal do Azure e navegue até à página Microsoft Entra ID.
2. Em Registos de aplicações, selecione Novo registo.
3. Forneça um nome e selecione Contas só neste diretório organizacional (Inquilino único) como o tipo de conta suportado.
4. Registe a aplicação.
5. Depois que o aplicativo for criado, copie a ID do aplicativo. Você precisará da ID do aplicativo mais tarde ao configurar a deteção de ameaças no centro de administração da Power Platform.

Autorize a aplicação Microsoft Entra com o seu fornecer escolhido

O agente usa Federated Identity Credentials (FIC) como um método de autenticação seguro e sem segredo para trocar dados com o provedor do sistema de deteçã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 vá para Registros de aplicativos. Selecione a aplicação que criou no passo 1 acima.

2. Na barra lateral, selecione Gerir>Certificados e segredos>Credenciais federadas.

3. Selecione Adicionar credencial.

4. Na lista pendente 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 de locatário do Microsoft Entra da sua organização: https://login.microsoftonline.com/{tenantId}/v2.0

   • Tipo: selecione Identificador de assunto explícito.

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

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

     Para obter a codificação base64 do seu ID de inquilino e URL de ponto final, utilize o seguinte script do PowerShell. Certifique-se de que substitui os valores do marcador de posição "11111111-2222-3333-4444-555555555555" e "https://provider.example.com/threat_detection/copilot"" pelos seus valores reais para o ID de inquilino e URL do ponto final:

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

Passo 2: Configurar o sistema de deteção de ameaças

Em seguida, você precisa configurar o sistema de deteçã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 deteção de ameaças no centro de administração da Power Platform

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

Para configurar o sistema de deteção de ameaças no centro de administração do Power Platform, siga estes passos:

1. Inicie sessão no Centro de administração do Power Platform.
2. Na navegação lateral, selecione Segurança e, em seguida, selecione Deteção de ameaças. A página Deteção de ameaças é aberta.
3. Selecione Deteção de ameaças adicionais. Um painel é aberto.
4. Selecione o ambiente para o qual 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 deteção de ameaças.
6. Em ID do Aplicativo do Azure Entra, insira a ID do Aplicativo do aplicativo Microsoft Entra que você criou anteriormente.
7. Insira o endereço Endpoint fornecido pelo provedor do seu sistema externo de monitorização. A ligação do ponto final é o mesmo ponto final do URL base que utiliza quando configura a aplicação Microsoft Entra.
8. Em Definir comportamento de erro, defina o comportamento padrão do sistema para quando o sistema de deteçã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. Selecione Guardar.

Solução de problemas

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

Problemas de configuração de deteção de ameaças do centro de administração do Power Platform

A tabela a seguir descreve erros comuns que poderão acontecer quando seleciona Guardar no passo anterior e como lidar com estes erros:

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

Problemas comuns do Microsoft Entra e de autenticação

Eis alguns outros problemas comuns que podem ocorrer com a sua aplicação Microsoft Entra e autenticação.

A aplicação Microsoft Entra não existe

Exemplo: falha ao adquirir token: AADSTS700016: aplicação com identificador "55ed00f8-faac-4a22-9183-9b113bc53dd4" não foi encontrada no diretório "Contoso". Isto pode acontecer se a aplicação não for instalada pelo administrador do inquilino ou consentido por qualquer utilizador no inquilino. Você pode ter enviado sua solicitação de autenticação para o locatário errado.

Como processar: certifique-se de que o ID da aplicação fornecida está correto e existe no Azure.

Nenhum FIC configurado na aplicação

Exemplo: Falha ao adquirir token: um problema de configuração está impedindo a autenticação — verifique a mensagem de erro do servidor para obter detalhes. Pode modificar a configuração no portal de registo de aplicação. 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 federada configuradas.

Como processar: a aplicação fornecida não tem nenhum FIC configurado. Siga a documentação e configure o FIC de acordo.

Emissor FIC inválido

Exemplo: Falha ao adquirir token: um problema de configuração está impedindo a autenticação — verifique a mensagem de erro do servidor para obter detalhes. Pode modificar a configuração no portal de registo de aplicação. Consulte https://aka.ms/msal-net-invalid-client para obter detalhes. Exceção original: AADSTS7002111: nenhum registo de identidade federada correspondente encontrado para o emissor de asserçã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 processar: nenhum FIC com o emissor esperado foi encontrado na aplicação. Abra a configuração do FIC e defina o emissor como https://login.microsoftonline.com/{tenantId}/v2.0 (preenchendo o ID do locatário).

Assunto FIC inválido

Exemplo: Falha ao adquirir token: um problema de configuração está impedindo a autenticação — verifique a mensagem de erro do servidor para obter detalhes. Pode modificar a configuração no portal de registo de aplicação. Consulte https://aka.ms/msal-net-invalid-client para obter detalhes. Exceção original: AADSTS7002137: Nenhum registo de identidade federada correspondente encontrado para o assunto de asserção apresentado "/eid1/c/pub/t/Jm0tJgAOs0CcLzFQHU3L0Q/a/iDQPIrayM0GBBVzmyXgucw/aHR0cHM6Ly9jb250b3NvLnByb3ZpZGVyLmNvbeKAiw". Verifique se o assunto da credencial de identidade federada é "/eid1/c/pub/t/{tenantId}/a/iDQPIrayM0GBBVzmyXgucw/aHR0cHM6Ly9jb250b3NvLnByb3ZpZGVyLmNvbeKAiw".

Como processar: nenhum FIC com o assunto esperado foi encontrado na aplicação. Abra a configuração do FIC e defina o assunto para o valor esperado, conforme sugerido no erro (preencha o ID do locatário). Certifique-se de que não há espaços em branco adicionais ou linhas em branco nos campos de assunto.

A aplicação não está na lista de permissões com o fornecedor (específico do Microsoft Defender)

Exemplo: o ID da aplicação no seu token de autenticação não corresponde à aplicação registada para acesso ao webhook. Verifique se está a usar as credenciais corretas da aplicação.

Como lidar: O aplicativo não está na lista de permitidos com o provedor. Consulte a documentação do fornecedor para conceder acesso ao webhook da aplicação.

Desligar a proteção pelo sistema de deteção de ameaças

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

1. Inicie sessão no Centro de administração do Power Platform.
2. Na navegação lateral, selecione Segurança e, em seguida, selecione Deteção de ameaças. A página Deteção de ameaças é aberta.
3. Selecione Deteção de ameaças adicionais. Um painel é aberto.
4. Selecione o ambiente para o qual deseja desativar a proteção avançada do agente e selecione Configurar. Um painel é aberto.
5. Desmarque Permitir que o Copilot Studio partilhe dados com o fornecedor selecionado.
6. Selecione Guardar.