Configurar la autenticación de claves de API

Recomendación

Recomendado: Comience con las herramientas de desarrollo de Work IQ para escenarios de complemento y agente declarativo de código profesional compatibles. Consulte el inicio rápido de WIQD. Las instrucciones basadas en el kit de herramientas siguen estando disponibles para los proyectos existentes y los flujos de trabajo que las requieren. Compruebe la compatibilidad con la capacidad y la experiencia de destino antes de elegir una herramienta: WIQD no se dirige a agentes de motor personalizados.

Algunas API usan claves de API para la autorización. Una clave de API es un secreto compartido que el cliente incluye en las solicitudes de API para autenticarse y obtener acceso. Los complementos de API admiten el envío de la clave API de tres maneras:

  • Como token de portador en el Authorization encabezado
  • Como un valor en un encabezado personalizado
  • Como parámetro de consulta

Nota

Para las acciones de agente declarativo, la autenticación de clave API se aplica a los complementos de API creados a partir de un documento OpenAPI, no a los complementos de MCP. Para el complemento MCP de un agente, use OAuth 2.0 (incluido el registro dinámico de clientes) o Microsoft Entra SSO. Una conexión MCP remota a nivel de paquete utiliza una configuración diferente; Consulte Autenticación en el manifiesto de la aplicación.

Configure la autenticación de clave API en dos pasos: agregue la clave API a su documento OpenAPI y cree la configuración de autenticación de clave API.

Paso 1: Agregar la clave API a tu documento OpenAPI

Microsoft 365 Copilot determina cómo enviar la clave de API en función de la entrada en el securitySchemes documento OpenAPI.

Token de portador

Si su API acepta la clave API como token de portador, habilite la autenticación de portador en su documento OpenAPI. Para obtener más información, consulte Autenticación de portador.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Encabezado personalizado

Si su API acepta la clave API en un encabezado personalizado, habilite la autenticación de clave API en su documento OpenAPI con la in propiedad establecida y header la name propiedad establecida en el nombre del encabezado. Para obtener más información, consulte Claves de API.

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

Parámetro de consulta

Si su API acepta la clave API en un parámetro de consulta, habilite la autenticación de clave API en su documento OpenAPI estableciendo la in propiedad query y la propiedad en el name nombre del parámetro de consulta. Para obtener más información, consulte Claves de API.

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

Paso 2: Crear la clave de API y la configuración de autenticación

La autenticación de claves API se basa en una configuración de autenticación (configuración de autenticación): un registro almacenado en el almacén de tokens de Microsoft Enterprise que Microsoft 365 Copilot usa para enviar la clave de API cuando el complemento llama a la API. Comience con WIQD para un proyecto pro-code compatible. Los procedimientos del portal para desarrolladores de Microsoft Toolkit y Microsoft Teams siguen disponibles como alternativas. La aptitud de desarrollador de agente declarativo no admite la autenticación de clave API, ya que crea complementos MCP.

Para un manifiesto de complemento de API existente, use wiqd agent add auth con --plugin-manifest, --auth-name, y --auth-type api-key. Establezca --api-key-in en header o query y --api-key-name en el nombre de su esquema de seguridad OpenAPI. Si la API acepta su clave como token de portador en su lugar, seleccione --auth-type bearer-token.

Al agregar una acción desde un documento OpenAPI, wiqd agent add action acepta --api-key credenciales de clave API o de portador. El comando documenta los marcadores de posición de entorno cuando se omite el valor. Siga el control de credenciales del comando seleccionado y complete el flujo de trabajo de aprovisionamiento del proyecto. Estas opciones de clave de API no establecen la compatibilidad con la clave de API para el complemento MCP de un agente.

Usar Microsoft 365 Agents Toolkit

Cuando crea un complemento de API a partir de un documento OpenAPI existente en Microsoft 365 Agents Toolkit, el kit de herramientas registra la clave de API, crea la configuración de autenticación y actualiza el manifiesto del complemento. Debe definir la propiedad en el securitySchemes documento OpenAPI.

Usar el portal para desarrolladores de Teams

El registro en el portal para desarrolladores de Teams es opcional si usa el Kit de herramientas de agentes. Úselo para crear la configuración de autenticación manualmente o para administrar una configuración de autenticación que Agents Toolkit ya creó.

  1. Abra el portal para desarrolladores de Teams. Seleccione Herramientas -Registro de claves de> API.

  2. Si no tiene registros existentes, seleccione Crear una clave de API. Si tiene registros existentes, seleccione Nueva clave de API.

  3. Seleccione Agregar secreto e introduzca la clave de API.

  4. Rellene los campos siguientes.

    • Nombre de la clave API: Un nombre descriptivo para el registro.
    • Dirección URL base: la dirección URL base de la API. Este valor debe corresponder a una entrada en la matriz enservers su documento OpenAPI.
    • Inquilino de destino: limite el acceso de API al inquilino principal o permita cualquier inquilino.
    • Aplicación de destino de Teams: seleccione cualquier aplicación de Teams si no conoce el identificador final de la aplicación. Después de publicar la aplicación, vincule este registro con el identificador de la aplicación publicada.
  5. Selecciona Guardar.

  6. La finalización del registro genera un identificador de configuración de autenticación (actualmente etiquetado como identificador de registro de clave de API en el portal para desarrolladores de Teams).

Agregar el identificador de configuración de autenticación al manifiesto del complemento

Al crear la configuración de autenticación manualmente en el portal para desarrolladores de Teams, establezca la type propiedad del objeto de autenticación en tiempo de ejecución en ApiKeyPluginVaulty establézcala reference_id en el identificador de configuración de autenticación. Agents Toolkit hace esto por usted.

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