Autenticação de Plugins no Microsoft Copilot Studio: Configuração OAuth vs Chave de API

Ao criar um plugin no Microsoft Copilot Studio, você precisa conectá-lo a um serviço externo como CRM, banco de dados ou API personalizada. Os dois métodos de autenticação mais comuns são OAuth 2.0 e chaves de API. Escolher o método errado pode causar falhas de conexão, brechas de segurança ou trabalho extra de manutenção. Este artigo explica as diferenças técnicas entre autenticação OAuth e chave de API para plugins do Copilot Studio. Também fornece instruções passo a passo para configurar ambos os métodos.

Autenticação OAuth 2.0 e Chave de API Explicadas

A autenticação determina como seu plugin do Copilot Studio prova sua identidade ao serviço externo. OAuth 2.0 é um protocolo padrão da indústria que usa tokens em vez de credenciais diretas. O plugin solicita um token de acesso de um servidor de autorização e depois envia esse token para a API. A autenticação por chave de API é mais simples: o plugin envia um valor de chave estático, geralmente em um cabeçalho HTTP ou parâmetro de consulta, para autenticar cada requisição.

Detalhes Técnicos do OAuth 2.0

OAuth 2.0 suporta vários tipos de concessão. Para plugins do Copilot Studio, o fluxo de código de autorização é o mais relevante. Esse fluxo envolve três partes: o cliente do plugin, o servidor de autorização e o servidor de recursos. O plugin primeiro obtém um código de autorização após o usuário fazer login. Em seguida, ele troca esse código por um token de acesso e, opcionalmente, um token de atualização. Os tokens de acesso expiram após um tempo determinado, geralmente 60 minutos. O token de atualização permite que o plugin obtenha novos tokens sem interação do usuário. Os tokens OAuth têm escopo, o que significa que o plugin só pode acessar os recursos específicos definidos no parâmetro de escopo.

Detalhes Técnicos da Chave de API

Uma chave de API é uma longa sequência de caracteres atribuída a um cliente específico. A chave é estática e não expira a menos que seja revogada manualmente. O plugin envia a chave em cada requisição, normalmente no cabeçalho Authorization ou como um cabeçalho personalizado como X-API-Key. As chaves de API não suportam escopos ou permissões granulares. Se uma chave for comprometida, um invasor pode usá-la até que seja revogada. As chaves de API são mais simples de implementar, mas oferecem menos segurança que o OAuth para operações voltadas ao usuário.

Passos para Configurar Autenticação OAuth no Copilot Studio

Antes de começar, registre seu plugin como um aplicativo no portal do desenvolvedor do serviço externo. Você precisará do ID do cliente, segredo do cliente, endpoint de autorização e endpoint de token. O Copilot Studio oferece suporte a provedores OAuth 2.0 padrão, incluindo Microsoft Entra ID, Google e servidores de identidade personalizados.

1. Abra as configurações de autenticação do plugin
   No Copilot Studio, vá em Plugins > selecione seu plugin > Configurações > Autenticação. Clique em Editar ao lado do método de autenticação atual.
2. Selecione OAuth 2.0 como tipo de autenticação
   No menu suspenso, escolha OAuth 2.0. Um formulário aparece com campos para URL de autorização, URL de token, ID do cliente, segredo do cliente e escopos.
3. Insira a URL do endpoint de autorização
   Cole a URL do seu serviço externo para onde o plugin redireciona os usuários para login. Para Microsoft Entra ID, use https://login.microsoftonline.com/{id-do-inquilino}/oauth2/v2.0/authorize. Substitua {id-do-inquilino} pelo ID do seu inquilino.
4. Insira a URL do endpoint de token
   Cole a URL de troca de token. Para Entra ID, use https://login.microsoftonline.com/{id-do-inquilino}/oauth2/v2.0/token.
5. Forneça as credenciais do cliente
   Insira o ID do cliente e o segredo do cliente do registro do aplicativo. Mantenha o segredo em um local seguro. O Copilot Studio criptografa o segredo armazenado.
6. Defina os escopos
   Insira os escopos necessários como uma lista separada por espaços. Por exemplo, User.Read Mail.Read. Os escopos limitam o plugin a dados específicos.
7. Defina o URI de redirecionamento
   Copie o URI de redirecionamento mostrado no Copilot Studio. Adicione este URI ao registro do seu aplicativo no serviço externo. Sem essa etapa, o OAuth falha com um erro de incompatibilidade de redirecionamento.
8. Salve e teste
   Clique em Salvar. Em seguida, use o botão Testar no Copilot Studio para verificar a conexão. Um teste bem-sucedido retorna um código de status 200 e dados de amostra da API.

Passos para Configurar Autenticação por Chave de API no Copilot Studio

A configuração da chave de API é mais rápida que a do OAuth. Você só precisa do valor da chave e do nome do cabeçalho esperado pela API externa. A maioria das APIs documenta o nome exato do cabeçalho em seu guia do desenvolvedor.

1. Abra as configurações de autenticação do plugin
   No Copilot Studio, navegue até Plugins > seu plugin > Configurações > Autenticação. Clique em Editar.
2. Selecione Chave de API como tipo de autenticação
   No menu suspenso, escolha Chave de API. O formulário agora mostra campos para Nome do Cabeçalho e Valor da Chave.
3. Insira o nome do cabeçalho
   Digite o nome exato do cabeçalho que a API espera. Valores comuns são Authorization, X-API-Key ou Api-Key. Verifique a documentação da API para o nome correto.
4. Insira o valor da chave
   Cole a string da chave de API. Essa chave geralmente é gerada no painel de administração do serviço externo. A chave pode incluir hífens, sublinhados ou caracteres alfanuméricos.
5. Salve e teste a conexão
   Clique em Salvar. Use o botão Testar para verificar. Um teste com falha significa que o nome do cabeçalho ou o valor da chave está incorreto. Revise a documentação da API para a formatação exata.

Erros Comuns de Autenticação e Como Evitá-los

Erro de Incompatibilidade de URI de Redirecionamento OAuth

O erro OAuth mais frequente no Copilot Studio é uma incompatibilidade entre o URI de redirecionamento no registro do aplicativo e o URI que o plugin envia. Copie o URI de redirecionamento exatamente da página de autenticação do plugin. Cole-o no registro do aplicativo do serviço externo sem barras ou espaços finais. Se o erro persistir, verifique se o URI usa HTTPS.

Chave de API Exposta no Código do Lado do Cliente

Se o seu plugin for executado em um navegador ou aplicativo móvel, a chave de API fica visível para qualquer pessoa que inspecione o tráfego de rede. Use OAuth em vez de chaves de API para plugins do lado do cliente. Se precisar usar uma chave de API, restrinja-a a endereços IP específicos ou domínios de referência nas configurações do serviço externo.

Expiração do Token OAuth Sem Atualização

Se o seu plugin falhar após uma hora, o token de acesso expirou e o plugin não possui um token de atualização. Certifique-se de que o serviço externo inclua um token de atualização na resposta do token e que as configurações do plugin no Copilot Studio tenham o endpoint de token de atualização configurado. Para Entra ID, adicione o escopo offline_access à lista de escopos.

OAuth 2.0 vs Chave de API: Comparação para Plugins do Copilot Studio

Item	OAuth 2.0	Chave de API
Modelo de segurança	Baseado em token com escopos e expiração	String de chave estática
Contexto do usuário	Suporta permissões específicas do usuário	Sem contexto de usuário; chave compartilhada
Rotação de token	Automática via tokens de atualização	Rotação manual da chave necessária
Complexidade de configuração	Requer registro do aplicativo, endpoints, escopos	Uma chave e um nome de cabeçalho
Melhor caso de uso	Plugins voltados ao usuário que acessam dados pessoais	Plugins servidor a servidor ou ferramentas internas
Revogação	Revogar token ou desabilitar registro do aplicativo	Excluir ou regenerar a chave

Escolha OAuth quando seu plugin precisar agir em nome de um usuário específico e exigir permissões granulares. Escolha chave de API quando o plugin for executado em um ambiente de backend confiável e a API não suportar OAuth. Ambos os métodos funcionam no Copilot Studio, mas o OAuth é a abordagem recomendada para plugins de produção que lidam com dados confidenciais.

Agora você pode configurar autenticação OAuth ou chave de API para qualquer plugin do Copilot Studio usando as etapas acima. Para OAuth, sempre teste o URI de redirecionamento e inclua o escopo offline_access para renovação de token. Para chaves de API, restrinja a chave a intervalos de IP específicos no console do serviço externo. Uma dica avançada: use OAuth mesmo para plugins servidor a servidor quando possível, pois ele fornece rotação automática de credenciais por meio de tokens de atualização e reduz o risco de comprometimento da chave.