Schémas d’authentification pour les plug-ins d’API pour Microsoft 365 Copilot

Article
10/01/2024

Importante

Les plug-ins d’API sont actuellement uniquement pris en charge en tant qu’actions au sein d’agents déclaratifs. Ils ne sont pas activés dans Microsoft 365 Copilot. Consultez Ajouter un plug-in pour obtenir un exemple d’ajout d’un plug-in d’API à un agent déclaratif.

Les plug-ins d’API pour Microsoft 365 Copilot prennent en charge trois schémas d’authentification pour se connecter à leurs API back-end.

Flux de code d’autorisation OAuth 2.0
Clé API via l’authentification du porteur
Aucune authentification (anonyme)

Flux de code d’autorisation OAuth 2.0

Ce schéma d’authentification permet à un plug-in d’accéder à une API à l’aide d’un jeton du porteur acquis par un flux de code d’autorisation OAuth 2.0. Ce schéma peut être représenté dans un document OpenAPI dans la securitySchemes propriété . Pour plus d’informations, consultez OAuth 2.0 .

Importante

Les plug-ins d’API prennent uniquement en charge le flux de code d’autorisation pour OAuth 2.0.

securitySchemes:
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: <authorization_url>
        tokenUrl: <token_url>
        refreshUrl: <refresh_url>
        scopes:
          scope: description

Pour utiliser ce schéma d’authentification dans un plug-in, vous devez inscrire un client OAuth dans le portail des développeurs Teams.

Conseil

Si votre document OpenAPI inclut la securitySchemes propriété , Teams Toolkit peut inscrire votre client OAuth et mettre à jour votre manifeste lorsque vous générez un plug-in à partir d’une API existante.

Inscrire un client OAuth

Ouvrez votre navigateur et accédez au portail des développeurs d’applications Teams. Sélectionnez Outils dans le volet de navigation de gauche.
Sélectionnez Inscription du client OAuth. Si vous n’avez aucune inscription existante, sélectionnez Inscrire le client. si vous avez des inscriptions existantes, sélectionnez Nouvelle inscription du client OAuth.
Renseignez les champs suivants.
- Nom de l’inscription : nom convivial pour votre inscription
- URL de base : URL de base de votre API
- ID client : ID client ou ID d’application émis par votre serveur OAuth 2.0
- Clé secrète client : votre clé secrète client émise par votre serveur OAuth 2.0
- Point de terminaison d’autorisation : URL de votre serveur OAuth 2.0 que les applications utilisent pour demander un code d’autorisation
- Point de terminaison de jeton : URL de votre serveur OAuth 2.0 que les applications utilisent pour échanger un code contre un jeton d’accès
- Point de terminaison d’actualisation : URL de votre serveur OAuth 2.0 que les applications utilisent pour actualiser le jeton d’accès
- Étendue : étendue d’autorisation définie par votre API qui accorde l’accès.
Sélectionnez Enregistrer.

La fin de l’inscription génère un ID d’inscription du client OAuth.

Ajout de l’authentification OAuth 2.0 au manifeste du plug-in

Pour utiliser l’authentification OAuth 2.0 dans votre plug-in, définissez la type propriété de l’objet d’authentification runtime sur OAuthPluginVaultet définissez sur reference_id l’ID d’inscription du client à partir du portail des développeurs Teams.

"auth": {
  "type": "OAuthPluginVault",
  "reference_id": "client registration ID"
},

Clé API via l’authentification du porteur

Ce schéma d’authentification permet à un plug-in d’accéder à une API à l’aide d’une clé ou d’un jeton API de longue durée. Ce jeton est envoyé dans les demandes d’API dans l’en-tête Authorization en tant que jeton du porteur. Ce schéma peut être représenté dans un document OpenAPI dans la securitySchemes propriété . Pour plus d’informations, consultez Authentification du porteur .

securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer

Remarque

Les plug-ins d’API ne prennent pas en charge le schéma de sécurité de clé d’API OpenAPI. Les API qui utilisent des clés API pour l’authentification doivent utiliser le schéma de sécurité d’authentification du porteur et accepter la clé API dans l’en-tête Authorization . Vous ne pouvez pas définir un en-tête personnalisé ou envoyer la clé en tant que paramètre de requête ou cookie.

Pour utiliser ce schéma d’authentification dans un plug-in, vous devez inscrire une clé API dans le portail des développeurs Teams.

Conseil

Si votre document OpenAPI inclut la securitySchemes propriété , Teams Toolkit peut inscrire votre clé API et mettre à jour votre manifeste lorsque vous générez un plug-in à partir d’une API existante.

Inscrire une clé API

Ouvrez votre navigateur et accédez au portail des développeurs d’applications Teams. Sélectionnez Outils dans le volet de navigation de gauche.
Sélectionnez Inscription de clé API. Si vous n’avez aucune inscription existante, sélectionnez Inscrire le client. si vous avez des inscriptions existantes, sélectionnez Nouvelle clé API.
Sélectionnez Ajouter un secret et entrez la clé API.
Renseignez les champs suivants.
- Nom de clé API : nom convivial pour votre inscription
- URL de base : URL de base de votre API
Sélectionnez Enregistrer.

La fin de l’inscription génère un ID d’inscription de clé d’application.

Ajout de l’authentification par clé API au manifeste du plug-in

Pour utiliser l’authentification par clé API dans votre plug-in, définissez la type propriété de l’objet d’authentification runtime sur ApiKeyPluginVaultet définissez sur reference_id l’ID d’inscription de clé d’application à partir du portail des développeurs Teams.

"auth": {
  "type": "ApiKeyPluginVault",
  "reference_id": "app key registration ID"
},

Aucune authentification (anonyme)

Pour les API qui ne nécessitent aucune authentification, ou pour les environnements de développement où l’authentification n’est pas encore implémentée, les plug-ins peuvent accéder aux API de manière anonyme. Dans ce cas, définissez la type propriété de l’objet d’authentification runtime sur None.

"auth": {
  "type": "None"
},

Partager via