Integrar um plug-in de API a uma API protegida por uma chave

  • 2 minutos

Uma das maneiras comuns de proteger APIs é usando chaves de API. As chaves de API são cadeias de caracteres arbitrárias que os proprietários de API emitem para conceder acesso à API. Muitos serviços populares usam chaves de API para proteger o acesso às suas APIs. O provedor de API que emite chaves de API controla se uma chave fornece acesso a toda a superfície de API e a todos os recursos ou apenas a uma parte específica dela. O serviço também controla por quanto tempo uma chave é válida.

As chaves de API são convenientes de usar graças à sua simplicidade. Para chamar uma API protegida por uma chave de API, tudo o que você precisa fazer é incluir a chave de API na solicitação de API. Em seguida, a API valida a chave e manipula a solicitação ou a rejeita com um erro de autenticação ou autorização. Essa simplicidade vem, no entanto, a um custo. As chaves de API não autenticam o usuário, o que significa que a API não pode agir em nome do usuário. Todos os usuários que chamam a API com a mesma chave de API têm as mesmas permissões.

Cada provedor de API define como espera que você passe a chave de API com suas solicitações. Por exemplo, uma API pode exigir que você use um parâmetro de cadeia de caracteres de consulta ou um cabeçalho de solicitação específico.

O Microsoft 365 Copilot dá suporte à passagem de chaves de API como:

  • Token Web JSON (JWT)
GET https://api.contoso.com/orders
Authorization: Bearer API_KEY
  • Parâmetro da seqüência de consulta
GET https://api.contoso.com/orders?api_key=API_KEY
  • Cabeçalho personalizado
GET https://api.contoso.com/orders
X-API-Key: API_KEY

Uma chave de API é um valor secreto que você nunca deve compartilhar publicamente. Ao criar um plug-in de API que se integra a uma API protegida por uma chave de API, você armazena a chave de API em um local de armazenamento seguro no Microsoft 365, também conhecido como cofre. Em seguida, em seu aplicativo, você faz referência à ID da entrada do cofre. Em tempo de execução, o agente declarativo carrega seu plug-in (2) e resolve a ID de entrada para a chave de API real (3a) que ele usa para chamar a API (3b). O diagrama a seguir ilustra esse processo.

Diagrama de como um agente declarativo executa um plug-in de API conectado a uma API protegida por uma chave.

Armazenar a chave de API no cofre permite que você gerencie com segurança sua chave de API sem nunca expô-la publicamente. Além disso, como seu aplicativo não faz referência direta à chave de API, você pode atualizá-la sem precisar atualizar seu aplicativo.

Durante o desenvolvimento, você mesmo pode registrar sua chave de API de desenvolvimento no cofre, manualmente acessando o Portal do Desenvolvedor do Teams e na seção Ferramentas abrindo o registro da chave de API ou usando o Microsoft 365 Agents Toolkit. Na produção, normalmente um administrador registra a chave de API e fornece a ID da entrada do cofre a ser usada em seu plug-in de API.

Captura de tela da página de registro da chave de API no Portal do Desenvolvedor do Teams.