Configurar autenticação de chave de API

Dica

Recomendado: Comece com o Work IQ Dev Tools para cenários de agente declarativo e plug-in pro-código suportados. Consulte o guia de início rápido do WIQD. As instruções baseadas em toolkits permanecem disponíveis para projetos e fluxos de trabalho existentes que o exigem. Verifique o suporte à capacidade e à experiência de destino antes de escolher uma ferramenta: o WIQD não tem como alvo agentes de mecanismo personalizados.

Algumas APIs usam chaves de API para autorização. Uma chave de API é um segredo compartilhado que o cliente inclui nas solicitações de API para autenticar e obter acesso. Os plug-ins de API suportam o envio da chave de API de três maneiras:

  • Como um token ao portador Authorization no cabeçalho
  • Como um valor num cabeçalho personalizado
  • Como parâmetro de consulta

Observação

Para ações de agente declarativo, a autenticação de chave de API aplica-se a plug-ins de API criados a partir de um documento OpenAPI, não a plug-ins MCP. Para o plug-in MCP de um agente, use OAuth 2.0 (incluindo registro dinâmico de cliente) ou Microsoft Entra SSO. Uma conexão MCP remota no nível do pacote usa uma configuração diferente; Consulte Autenticação no manifesto do aplicativo.

Configure a autenticação da chave API em duas etapas: adicione a chave API ao documento OpenAPI e crie a configuração da autenticação da chave API.

Etapa 1: Adicionar a chave da API ao documento OpenAPI

Microsoft 365 Copilot determina como enviar a chave da API com base na securitySchemes entrada no documento OpenAPI.

Token ao portador

Se sua API aceitar a chave da API como um token de portador, habilite a autenticação do portador em seu documento OpenAPI. Para obter mais informações, consulte Autenticação do portador.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Cabeçalho personalizado

Se sua API aceitar a chave da API em um cabeçalho personalizado, habilite a autenticação da chave da API no documento OpenAPI com a in propriedade definida como header e a name propriedade definida para o nome do cabeçalho. Para obter mais informações, consulte Chaves de API.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-KEY

Parâmetro de consulta

Se sua API aceitar a chave API em um parâmetro de consulta, habilite a autenticação de chave de API em seu documento OpenAPI definindo a in propriedade como query e a name propriedade para o nome do parâmetro de consulta. Para obter mais informações, consulte Chaves de API.

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: query
    name: api_key

Etapa 2: criar a configuração de autenticação de chave de API

A autenticação de chave de API depende de uma configuração de autenticação (auth config) - um registro armazenado no armazenamento de tokens do Microsoft Enterprise que Microsoft 365 Copilot usa para enviar a chave de API quando seu plug-in chama a API. Comece com o WIQD para um projeto pro-code suportado. Os procedimentos do toolkit e do portal do programador do Microsoft Teams permanecem disponíveis como alternativas. A habilidade de desenvolvedor do agente declarativo não oferece suporte à autenticação por chave de API, pois cria plug-ins MCP.

Para um manifesto de plug-in de API existente, use wiqd agent add auth com --plugin-manifest, --auth-namee --auth-type api-key. Defina --api-key-in como header ou query e --api-key-name para o nome do seu esquema de segurança OpenAPI. Se a API aceitar sua chave como um token de portador, selecione --auth-type bearer-token.

Ao adicionar uma ação a partir de um documento OpenAPI, wiqd agent add action aceita --api-key para credenciais de chave de API ou portador. O comando documenta os espaços reservados do ambiente quando o valor é omitido. Siga a manipulação de credenciais do comando selecionado e conclua o fluxo de trabalho de provisionamento do projeto. Essas opções de chave de API não estabelecem suporte de chave de API para o plug-in MCP de um agente.

Utilizar o Microsoft 365 Agents Toolkit

Quando cria um plug-in API a partir de um documento OpenAPI existente no Microsoft 365 Agents Toolkit, o toolkit regista a chave API, cria a configuração de autenticação e atualiza o manifesto do plug-in por si. Você deve definir a securitySchemes propriedade em seu documento OpenAPI.

Utilizar o portal do programador do Teams

O registo no portal do programador do Teams é opcional se utilizar o Agents Toolkit. Use-o para criar a configuração de autenticação manualmente ou para gerenciar uma configuração de autenticação que o Agents Toolkit já criou.

  1. Abra o portal do programador do Teams. Selecione Ferramentas ->registro de chave API.

  2. Se você não tiver registros existentes, selecione Criar uma chave de API. Se você tiver registros existentes, selecione Nova chave de API.

  3. Selecione Adicionar segredo e insira a chave API.

  4. Preencha os seguintes campos.

    • Nome da chave API: um nome amigável para o seu registro.
    • URL base: o URL base da sua API. Esse valor deve corresponder a uma entrada na servers matriz em seu documento OpenAPI.
    • Inquilino alvo: limite o acesso à API ao seu inquilino principal ou permita qualquer inquilino.
    • Aplicação Target Teams: selecione Qualquer aplicação Teams se não souber o ID final da aplicação. Depois de publicar seu aplicativo, vincule esse registro com seu ID de aplicativo publicado.
  5. Selecione Salvar.

  6. Concluir o registo gera um ID de configuração de autenticação (atualmente denominado ID de registo da chave API no portal do programador do Teams).

Adicione o ID de configuração de autenticação ao manifesto do plug-in

Quando cria manualmente a configuração da autenticação no portal do programador do Teams, defina a type propriedade do objeto de autenticação de tempo de execução como ApiKeyPluginVault, e o reference_id ID de configuração da autenticação. O Agents Toolkit faz isso por você.

"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "auth config ID"
},