Configurer l’authentification par clé API

Conseil

Recommandé : Commencez avec les outils de développement Work IQ pour les scénarios de plug-in et d’agent déclaratif pro-code pris en charge. Voir le guide de démarrage rapide de WIQD. Les instructions basées sur la boîte à outils restent disponibles pour les projets existants et les flux de travail qui les nécessitent. Vérifiez la prise en charge de la capacité et de l’expérience cible avant de choisir un outil : WIQD ne cible pas les agents de moteur personnalisés.

Certaines API utilisent des clés API pour l’autorisation. Une clé API est un secret partagé que le client inclut dans les demandes d’API pour s’authentifier et obtenir l’accès. Les plugins d’API prennent en charge l’envoi de la clé API de trois manières :

  • En tant que jeton du porteur dans l’en-tête Authorization
  • En tant que valeur dans un en-tête personnalisé
  • En tant que paramètre de requête

Remarque

Pour les actions d’agent déclaratif, l’authentification par clé API s’applique aux plugins API créés à partir d’un document OpenAPI, et non aux plugins MCP. Pour le plug-in MCP d’un agent, utilisez OAuth 2.0 (y compris l’inscription client dynamique) ou l’authentification unique Microsoft Entra. Une connexion MCP distante au niveau du package utilise une configuration différente ; Voir Authentification dans le manifeste de l’application.

Configurez l’authentification par clé API en deux étapes : ajoutez la clé API à votre document OpenAPI et créez la configuration de l’authentification par clé API.

Étape 1 : Ajouter la clé API à votre document OpenAPI

Microsoft 365 Copilot détermine comment envoyer la clé API en fonction de l’entrée securitySchemes dans votre document OpenAPI.

Jeton du porteur

Si votre API accepte la clé API en tant que jeton porteur, activez l’authentification du porteur dans votre document OpenAPI. Pour plus d’informations, voir Authentification du porteur.

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

En-tête personnalisé

Si votre API accepte la clé API dans un en-tête personnalisé, activez l’authentification par clé API dans votre document OpenAPI avec la propriété définie sur le nom de l’en-tête inheadername . Pour plus d’informations, consultez Clés API.

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

Paramètre de requête

Si votre API accepte la clé API dans un paramètre de requête, activez l’authentification par clé API dans votre document OpenAPI en définissant la in propriété query sur name le nom du paramètre de requête. Pour plus d’informations, consultez Clés API.

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

Étape 2 : Créer la configuration de l’authentification de la clé API

L’authentification par clé API repose sur une configuration d’authentification (configuration d’authentification) : un enregistrement stocké dans le magasin de jetons Microsoft Enterprise que Microsoft 365 Copilot utilise pour envoyer la clé API lorsque votre plug-in appelle l’API. Commencez par WIQD pour un projet pro-code pris en charge. Les procédures de Toolkit et du portail des développeurs Microsoft Teams restent disponibles en tant qu’alternatives. La compétence de développeur d’agent déclaratif ne prend pas en charge l’authentification par clé API, car elle génère des plug-ins MCP.

Dans le cas d’un manifeste de plug-in d’API existant, utilisez wiqd agent add auth avec --plugin-manifest, --auth-nameet --auth-type api-key. Définissez --api-key-in sur header ou et --api-key-namequery sur le nom de votre schéma de sécurité OpenAPI. Si l’API accepte sa clé comme jeton de porteur, sélectionnez --auth-type bearer-token.

Lors de l’ajout d’une action à partir d’un document OpenAPI, wiqd agent add action accepte --api-key les informations d’identification de clé API ou de porteur. La commande documente les espaces réservés d’environnement lorsque la valeur est omise. Suivez la gestion des informations d’identification de la commande sélectionnée et terminez le workflow d’approvisionnement du projet. Ces options de clé API n’établissent pas de prise en charge de la clé API pour le plug-in MCP d’un agent.

Utiliser le kit de ressources des agents Microsoft 365

Lorsque vous créez un plug-in d’API à partir d’un document OpenAPI existant dans Microsoft 365 Agents Toolkit, le kit de ressources enregistre la clé API, crée la configuration d’authentification et met à jour le manifeste de votre plug-in pour vous. Vous devez définir la securitySchemes propriété dans votre document OpenAPI.

Utiliser le portail de développement Teams

L’inscription au portail de développement Teams est facultative si vous utilisez Agents Toolkit. Utilisez-le pour créer manuellement la configuration d’authentification, ou pour gérer une configuration d’authentification déjà créée par Agents Toolkit.

  1. Ouvrez le portail de développement Teams. Sélectionnez Outils ->Inscription de clé API.

  2. Si vous n’avez pas d’inscriptions existantes, sélectionnez Créer une clé API. Si vous avez déjà des inscriptions, sélectionnez Nouvelle clé API.

  3. Sélectionnez Ajouter un secret et entrez la clé API.

  4. Renseignez les champs suivants.

    • Nom de la clé API : un nom facile à retenir pour votre inscription.
    • URL de base : URL de base de votre API. Cette valeur doit correspondre à une entrée du servers tableau dans votre document OpenAPI.
    • Locataire cible : limitez l’accès API à votre locataire d’accueil ou autorisez n’importe quel locataire.
    • Application Teams cible : sélectionnez une application Teams si vous ne connaissez pas votre ID d’application final. Après avoir publié votre application, liez cette inscription à votre ID d’application publiée.
  5. Sélectionnez Enregistrer.

  6. La fin de l’inscription génère un ID de configuration d’authentification (actuellement étiqueté ID d’inscription de clé API dans le portail de développement Teams).

Ajouter l’ID de configuration de l’authentification au manifeste du plug-in

Lorsque vous créez la configuration d’authentification manuellement dans le portail de développement Teams, définissez la type propriété de l’objet d’authentification d’exécution sur ApiKeyPluginVault, et définissez sur l’ID de configuration d’authentificationreference_id. Agents Toolkit le fait pour vous.

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