Configurer l’authentification pour les plug-ins d’API dans Microsoft 365 Copilot agents

Vous pouvez configurer l’authentification pour les plug-ins d’API dans Microsoft 365 Copilot agents à l’aide de l’un des quatre schémas d’authentification pris en charge pour vous connecter en toute transparence à leurs API back-end.

• Flux de code d’autorisation OAuth 2.0
• Microsoft Entra ID l’authentification unique (SSO)
• Authentification par clé API
• 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 obtenu via le flux de code d’autorisation OAuth 2.0, avec la prise en charge facultative de la clé de preuve pour l’échange de code (PKCE).

Avant de commencer, vous devez vous inscrire auprès de votre fournisseur OAuth 2.0 pour obtenir un ID client et un secret. Si votre fournisseur OAuth vous oblige à spécifier des URI de redirection autorisés lors de l’inscription de l’application, veillez à inclure https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect dans la liste.

Vous pouvez définir ce schéma dans la securitySchemes propriété d’un document OpenAPI. Pour plus d’informations, consultez OAuth 2.0.

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

Pour activer l’authentification OAuth 2.0, vous devez inscrire un client OAuth dans le portail des développeurs Teams. Vous pouvez inscrire un client OAuth auprès du Kit de ressources Teams dans Visual Studio Code ou en vous inscrivant manuellement dans le portail des développeurs Teams.

Inscrire un client OAuth auprès du Kit de ressources Teams

Teams Toolkit inscrit votre client OAuth et met à jour votre package d’application pour vous lorsque vous créez un agent Copilot avec plug-in d’API à partir d’un document OpenAPI existant. La propriété doit être securitySchemes définie dans votre document OpenAPI.

Si votre fournisseur OAuth prend en charge PKCE, supprimez les marques de commentaire de la ligne de code suivante dans teamsapp.yml dans votre projet d’agent Copilot avant de provisionner l’agent.

# isPKCEEnabled: true

Inscrire un client OAuth dans le portail des développeurs Teams

1. Ouvrez le portail des développeurs Teams. Sélectionnez Outils ->Inscription du client OAuth.

2. 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.

3. Renseignez les champs suivants.

   • Nom de l’inscription : nom convivial 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.
   • ID client : ID client ou ID d’application émis par votre fournisseur OAuth 2.0.
   • Clé secrète client : votre clé secrète client émise par votre fournisseur OAuth 2.0.
   • Point de terminaison d’autorisation : URL de votre fournisseur OAuth 2.0 que les applications utilisent pour demander un code d’autorisation
   • Point de terminaison de jeton : URL de votre fournisseur 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 fournisseur OAuth 2.0 que les applications utilisent pour actualiser le jeton d’accès
   • Étendue : étendue d’autorisation définie par votre API qui autorise l’accès.
   • Activer la clé de preuve pour l’échange de code (PKCE) : activez ce paramètre si votre fournisseur OAuth prend en charge PKCE.

4. Sélectionnez Enregistrer.

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

Ajouter l’ID d’inscription du client au manifeste du plug-in

Pour utiliser l’authentification OAuth 2.0 pour votre plug-in d’API, 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": "auth registration ID"
},

Authentification unique Microsoft Entra ID

Microsoft Entra ID l’authentification unique permet une intégration transparente de l’authentification unique (SSO), ce qui permet aux utilisateurs de s’authentifier avec leurs informations d’identification Microsoft Entra ID existantes. Cette intégration simplifie la gestion des accès et garantit des connexions sécurisées aux API sans nécessiter d’informations d’identification supplémentaires. Votre API doit utiliser Microsoft Entra ID pour contrôler l’accès.

Inscrire un client d’authentification unique dans le portail des développeurs Teams

1. Ouvrez le portail des développeurs Teams. Sélectionnez Outils ->Microsoft Entra inscription de l’ID client SSO.

2. Si vous n’avez aucune inscription existante, sélectionnez Inscrire l’ID client. Si vous avez des inscriptions existantes, sélectionnez Nouvelle inscription du client.

3. Renseignez les champs suivants.

   • Nom de l’inscription : nom convivial 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.
   • Restreindre l’utilisation par organisation : sélectionnez le organization Microsoft 365 qui a accès à votre application pour accéder aux points de terminaison d’API.
   • Restreindre l’utilisation par application : sélectionnez N’importe quelle application Teams si vous ne connaissez pas votre ID d’application final. Après avoir publié votre application, liez cette inscription avec votre ID d’application publié.
   • ID client : ID client de l’application inscrite dans Microsoft Entra.

4. Sélectionnez Enregistrer.

5. La fin de l’inscription génère un ID d’inscription d’authentification unique Microsoft Entra et un URI d’ID d’application.

Mettre à jour l’inscription de l’application Microsoft Entra

1. Ouvrez centre d’administration Microsoft Entra. Mettez à jour l’inscription d’application Microsoft Entra qui sécurise votre API avec l’URI d’ID d’application généré par le portail des développeurs Teams. Si vous avez un URI d’ID d’application existant mappé à l’inscription de l’application, vous pouvez utiliser l’éditeur de manifeste pour ajouter un autre URI dans la section identifierUris .

   "identifierUris": [
     "<<URI1>>"
     "<<URI2>>"
   ]
   

   Remarque

   L’ajout de plusieurs URI n’est pas pris en charge via l’interface utilisateur de l’centre d’administration Microsoft Entra. L’interface utilisateur affiche uniquement le premier URI de la liste. L’ajout de plusieurs URI n’affecte pas vos URI et étendues existants, même s’ils s’affichent différemment dans l’interface utilisateur.

2. Sous Gérer, sélectionnez Authentification. Ajoutez https://teams.microsoft.com/api/platform/v1.0/oAuthConsentRedirect aux URI de redirection dans la plateforme web .

3. Sélectionnez Exposer une API sous Gérer. Sélectionnez Ajouter une application cliente et ajoutez l’ID client du magasin de jetons d’entreprise de Microsoft, ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b.

Ajouter l’ID d’inscription de l’authentification unique au manifeste du plug-in

Définissez la type propriété de l’objet d’authentification du runtime sur OAuthPluginVault, et définissez sur reference_idl’ID d’inscription de l’authentification unique Microsoft Entra à partir du portail des développeurs Teams.

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

Ajouter la nouvelle audience de jeton à votre API

Mettez à jour votre API pour autoriser le nouvel URI d’identificateur comme audience de jeton. Si votre API valide l’ID de l’application cliente, assurez-vous que l’ID client du magasin de jetons d’entreprise Microsoft (ab3be6b7-f5df-413d-ac2d-abf1e3fd9c0b) est ajouté en tant qu’application cliente autorisée.

Authentification par clé API

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 plug-ins 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

Ajouter une 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 du porteur, activez l’authentification du porteur dans votre document OpenAPI. Pour plus d’informations, consultez 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 in propriété définie sur header et la name propriété définie sur le nom d’en-tête. 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 avec la in propriété définie sur query et la name propriété définie sur 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

Inscrire une clé API

Pour activer l’authentification par clé API, vous devez inscrire la clé API dans le portail des développeurs Teams. Vous pouvez inscrire la clé API auprès du Kit de ressources Teams dans Visual Studio Code ou en vous inscrivant manuellement dans le portail des développeurs Teams.

Inscrire une clé API auprès du Kit de ressources Teams

Teams Toolkit inscrit votre clé API et met à jour votre package d’application quand vous créez un agent Copilot avec un plug-in d’API à partir d’un document OpenAPI existant. La propriété doit être securitySchemes définie dans votre document OpenAPI.

Inscrire une clé API dans le portail des développeurs Teams

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

2. Si vous n’avez aucune inscription existante, sélectionnez Créer une clé API. Si vous avez des inscriptions existantes, 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 : nom convivial 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 ou non l’accès de l’API au locataire d’origine.
   • Application Teams cible : sélectionnez n’importe quelle application Teams si vous ne connaissez pas votre ID d’application final. Après avoir publié votre application, liez cette inscription avec votre ID d’application publié.

5. Sélectionnez Enregistrer.

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

Ajouter l’ID d’inscription de clé API au manifeste du plug-in

1. Dans le fichier manifeste de votre plug-in, définissez la type propriété de l’objet d’authentification du runtime sur ApiKeyPluginVault, et définissez sur reference_id l’ID d’inscription de clé API à 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"
},