Configurer l’authentification OAuth 2.0

Un plug-in peut accéder à un serveur ou à une API MCP (Model Context Protocol) à l’aide d’un jeton de porteur obtenu via le flux de code d’autorisation OAuth 2.0, avec la prise en charge de Proof Key for Code Exchange (PKCE) activée par défaut. Dans ce flux, Microsoft 365 Copilot ouvre l’expérience de connexion, le fournisseur OAuth retourne une réponse d’autorisation à Microsoft Teams et Teams échange le code d’autorisation contre des jetons.

Cet article utilise des plug-ins MCP comme procédure pas à pas par défaut. Les mêmes étapes s’appliquent aux plug-ins d’API créés à partir d’un document OpenAPI, sauf indication contraire.

Configurez l’authentification OAuth 2.0 en trois étapes : inscrivez un client OAuth auprès de votre fournisseur d’identité, configurez l’URI de redirection et créez la configuration OAuth 2.0.

Étape 1 : Inscrire un client OAuth auprès de votre fournisseur d’identité

Inscrivez une application auprès de votre fournisseur OAuth 2.0 (votre fournisseur d’identité) pour obtenir un ID client et, pour un client confidentiel (Web), un secret client. Fournissez ces valeurs lorsque vous créez la configuration OAuth 2.0 à l’étape 3.

Pour un serveur MCP nécessitant une autorisation, définissez la type propriété de l’objet d’authentification d’exécution sur OAuthPluginVault. None et ApiKeyPluginVault ne vous appliquez pas à un serveur MCP nécessitant une autorisation. Seul l’ID de configuration d’authentification est stocké dans le manifeste - aucun ID client, secret client ou jeton n’y est écrit. Pour inscrire le client de manière dynamique plutôt que statique, conservez type et OAuthPluginVault créez la configuration d’authentification via l’inscription de client dynamique (DCR), qui n’est pas disponible pour un serveur protégé par Microsoft Entra ID.

Remarque

Ces valeurs s’appliquent au manifeste du module. Si vous enregistrez plutôt votre serveur MCP en tant que connecteur d’agent dans le agentConnectors nœud du manifeste de l’application Microsoft 365, utilisez OAuthPluginVault ou DynamicClientRegistration là également. Ne pas utiliser AzureKeyVault: il n’existe que dans le schéma, donc un package qui cible une version de schéma numérotée échoue à la devPreview validation. Pour plus d’informations, consultez Inscrire des serveurs MCP en tant que connecteurs d’agent.

Étape 2 : configurer l’URI de redirection

Ajoutez l’URI de redirection suivant (également appelé URL de rappel d’autorisation) à l’inscription de votre fournisseur OAuth :

https://teams.microsoft.com/api/platform/v1.0/oAuthRedirect

Il s’agit de l’URL vers laquelle votre fournisseur OAuth envoie la réponse d’autorisation après qu’un utilisateur s’est connecté. Teams reçoit la réponse à cette URL de rappel et échange le code d’autorisation contre des jetons. Si vous n’inscrivez pas cet URI de redirection auprès de votre fournisseur, la connexion échoue. L’URI de redirection est le même pour chaque plugin et fournisseur - vous ne le personnalisez pas par application.

Étape 3 : Créer la configuration de l’authentification OAuth 2.0

L’authentification OAuth 2.0 repose sur une configuration d’authentification (auth config) : un enregistrement stocké dans le magasin de jetons Microsoft Enterprise que Microsoft 365 Copilot utilise pour obtenir et actualiser des jetons pour votre plug-in MCP. Vous pouvez créer la configuration d’authentification de trois manières. Les approches recommandées - Microsoft 365 Agents Toolkit et la compétence de développeur d’agent déclaratif - créent la configuration d’authentification et mettent à jour automatiquement votre manifeste de plug-in. Vous pouvez ensuite utiliser le portail des développeurs Teams pour gérer et affiner la configuration de l’authentification.

Quelle que soit la façon dont vous le créez, la configuration d’authentification a un ID de configuration d’authentification auquel votre manifeste de plug-in fait référence.

Lorsque vous générez un agent avec un plug-in MCP (si le serveur nécessite une authentification) ou que vous créez un plug-in d’API à partir d’un document OpenAPI existant dans le kit de ressources des agents Microsoft 365, le kit de ressources vous invite à entrer l’ID client OAuth, le secret client et les étendues. Agents Toolkit récupère les points de terminaison d’autorisation, de jeton et d’actualisation à partir du point de terminaison bien connu de votre serveur MCP (ou du document OpenAPI pour les plug-ins d’API), crée la configuration d’authentification dans le magasin de jetons Enterprise et met automatiquement à jour l’objet d’authentification d’exécution dans votre manifeste de plug-in.

Remarque

Pour les plugins d’API, vous devez définir la propriété dans votre document OpenAPI afin que Agents securitySchemes Toolkit puisse lire les détails OAuth. 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

PKCE est activé par défaut, car de nombreuses organisations bloquent les secrets clients. Définissez isPKCEEnabled la valeur false in m365agents.yml dans votre projet d’agent avant de provisionner l’agent uniquement si votre fournisseur OAuth ne prend pas en charge PKCE.

isPKCEEnabled: false

Pour éviter complètement les secrets client, enregistrez un client public auprès de votre fournisseur - une plate-forme d’application monopage plutôt qu’une plate-forme Web - et laissez PKCE sécuriser l’échange de code.

Utiliser la compétence de développeur d’agent déclaratif

La compétence de développeur d’agent déclaratif (declarative-agent-developer) est une compétence d’agent dans Microsoft Work IQ qui empaquet les connaissances nécessaires à la création d’agents déclaratifs. Au lieu d’exécuter des commandes ou de modifier vous-même des manifestes, vous décrivez ce que vous voulez Copilot ou l’interface de ligne de commande GitHub en langage naturel, et la compétence génère l’agent déclaratif, ajoute le plug-in MCP et gère la configuration de l’authentification pour vous. La compétence prend uniquement en charge les plug-ins MCP. Pour OAuth 2.0, il prend en charge à la fois l’inscription statique et l’inscription client dynamique (DCR) : il crée la configuration d’authentification dans le magasin de jetons d’entreprise et met à jour le manifeste du plug-in sans étape manuelle.

Conseil

Pour une vidéo de présentation de l’utilisation de la compétence de développeur d’agent déclaratif, consultez Créer des agents déclaratifs avec la compétence de développeur d’agent déclaratif.

Utiliser le portail de développement Teams

L’inscription au portail des développeurs Teams est facultative si vous utilisez Agents Toolkit ou la compétence de développeur d’agent déclaratif. Utilisez-le lorsque vous souhaitez créer la configuration d’authentification manuellement, ou - plus couramment - pour gérer une configuration d’authentification déjà créée par Agents Toolkit ou la compétence. Dans le portail, vous pouvez restreindre la configuration de l’authentification à une application Teams ou à une organisation Microsoft 365 spécifique et modifier d’autres propriétés.

L’inscription du client OAuth dans le portail de développement Teams connecte la configuration du plug-in de votre agent à l’inscription du fournisseur OAuth qui émet des jetons pour votre serveur MCP ou API. Les valeurs de cette inscription doivent correspondre à votre fournisseur OAuth, à votre manifeste de plug-in et au point de terminaison de l’API protégée. Des URL de base, des restrictions d’application ou des ID de configuration d’authentification incompatibles peuvent empêcher les utilisateurs de se connecter ou bloquer l’échange de jetons.

Avertissement

Limitez l’inscription à une application Teams. Une inscription limitée à une application Teams spécifique est liée à cet ID d’application Teams. Microsoft 365 Copilot ne résout pas cet ID lorsqu’il appelle un serveur MCP, de sorte que l’approvisionnement se termine avec succès, puis chaque appel d’outil renvoie une 404 erreur.

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

  2. Si vous n’avez aucune inscription existante, sélectionnez Inscrire le client. Si vous avez déjà des inscriptions, sélectionnez Nouvelle inscription client OAuth.

  3. Renseignez les champs suivants.

    • Nom de l’enregistrement : un nom convivial pour votre enregistrement.
    • URL de base : URL de base de votre API. Cette valeur doit correspondre à l’URL dans la propriété de l’objet urlde spécification du serveur MCP dans le manifeste du plugin pour les plugins basés sur MCP, ou à une entrée dans le servers tableau dans votre document OpenAPI pour les plugins API.
    • Restreindre l’utilisation par org : sélectionnez les organisations Microsoft 365 qui peuvent utiliser cette inscription OAuth pour accéder à vos points de terminaison d’API. Utiliser Mon organisation uniquement pour le développement ou le test dans un locataire. Utilisez n’importe quelle organisation Microsoft 365 lorsque le plug-in doit fonctionner sur plusieurs clients.
    • Restreindre l’utilisation par application : sélectionnez n’importe quelle application Teams. Ne liez pas l’inscription à l’ID d’application Teams existant pour un serveur MCP. Si vous provisionnez la configuration d’authentification avec Microsoft 365 Agents Toolkit à la place, le paramètre équivalent dans l’action oauth/register de m365agents.yml est applicableToApps: AnyApp. Conserver le appId champ dans cette action même s’il AnyApp le rend inerte, car le pilote d’approvisionnement le valide appId inconditionnellement et sa suppression interrompt l’approvisionnement.
    • 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.
    • Actualiser le point de terminaison : URL de votre fournisseur OAuth 2.0 que les applications utilisent pour actualiser le jeton d’accès.
    • Portée : les autorisations que votre plug-in demande au fournisseur OAuth. Utilisez les valeurs d’étendue requises par votre fournisseur et votre API. Si votre fournisseur utilise la Plateforme d’identités Microsoft et que votre plug-in a besoin de jetons d’actualisation, incluez offline_access avec toute étendue déléguée spécifique à l’API.
    • Activer la clé de preuve pour l’échange de code (PKCE) : laissez ce paramètre activé. Elle est activée par défaut. désactivez-le uniquement si votre fournisseur OAuth ne prend pas en charge PKCE.

  4. Sélectionnez Enregistrer.

  5. L’inscription crée la configuration d’authentification et génère un ID de configuration d’authentification (actuellement intitulé ID d’inscription client OAuth 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 OAuthPluginVault, et définissez sur l’ID de configuration d’authentificationreference_id. Agents Toolkit et la compétence de développeur d’agent déclaratif le font pour vous.

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

Considérations relatives à Microsoft Entra ID

Lorsque vous protégez votre serveur MCP à l’aide de Microsoft Entra ID, trois contraintes s’appliquent que vous ne pouvez pas contourner dans les outils.

  • L’inscription de client dynamique n’est pas disponible. Microsoft Entra ID ne publie pas de point de terminaison d’inscription RFC 7591. Par conséquent, l’inscription de client dynamique n’a rien à enregistrer. Enregistrez le client OAuth de façon statique en suivant les étapes de cet article.
  • Le agentConnectors nœud n’a pas de type d’autorisation Microsoft Entra. Contrairement à composeExtensions, le agentConnectors nœud dans le manifeste de l’application Microsoft 365 n’a pas microsoftEntra de type d’autorisation. Un serveur MCP protégé par Microsoft Entra ID a toujours besoin d’une application que vous inscrivez vous-même dans Microsoft Entra ID, ainsi que d’une configuration d’authentification OAuth, même lorsque le serveur dispose d’une API Microsoft interne.
  • Le consentement à l’étendue n’est pas vérifié lors de l’approvisionnement. La mise en case activée ne vérifie pas si l’étendue demandée peut être autorisée. Une étendue qui ne peut pas être autorisée à des approvisionnements réussis, puis qui échoue plus tard avec l’approbation de l’administrateur nécessaire, et l’application de ressources peut être invisible pour vous et votre administrateur client. Confirmez qu’un administrateur a consenti à l’étendue avant la mise en service.

Gérer la configuration de l’authentification

L’action oauth/register dans m365agents.yml crée uniquement une configuration d’authentification ou ignore la création d’une configuration - elle ne réécrit jamais un enregistrement existant.

  • Si configurationId elle a déjà une valeur, l’action ne fait rien.
  • Si configurationId elle pointe vers un enregistrement que vous avez supprimé, l’action vous avertit et ne fait rien.
  • Pour modifier les valeurs d’un enregistrement existant, utilisez l’action oauth/update .
  • Pour supprimer une inscription, utilisez le portail de développement Teams. C’est le seul endroit où vous pouvez en supprimer un.

Se déconnecter

Remarque

Les utilisateurs peuvent se déconnecter d’un agent à partir des paramètres> de ChatAgents dans Microsoft 365 Copilot. Cette action efface le jeton OAuth stocké.

Contenu connexe

  • Last updated on