Exercice - Intégrer un plug-in d’API à une API sécurisée avec OAuth

  • 11 minutes

Les plug-ins d’API pour Microsoft 365 Copilot vous permettent d’intégrer des API sécurisées avec OAuth. Vous conservez l’ID client et le secret de l’application qui protège votre API en les inscrivant dans le coffre Teams. Au moment de l’exécution, Microsoft 365 Copilot exécute votre plug-in, récupère les informations du coffre et les utilise pour obtenir un jeton d’accès et appeler l’API. En suivant ce processus, l’ID client et le secret restent sécurisés et ne sont jamais exposés au client.

Ouvrir l’exemple de projet

Commencez par télécharger l’exemple de projet :

  1. Dans un navigateur web, accédez à https://aka.ms/learn-da-api-ts-repairs. Vous recevez une invite pour télécharger un fichier ZIP avec l’exemple de projet.
  2. Enregistrez le fichier ZIP sur votre ordinateur.
  3. Extrayez le contenu du fichier ZIP.
  4. Ouvrez le dossier dans Visual Studio Code.

L’exemple de projet est un projet microsoft 365 Agents Toolkit qui inclut un agent déclaratif, un plug-in d’API et une API sécurisée avec Microsoft Entra ID. L’API s’exécute sur Azure Functions et implémente la sécurité à l’aide des fonctionnalités d’authentification et d’autorisation intégrées de Azure Functions, parfois appelées Easy Auth.

Examiner la configuration de l’autorisation OAuth2

Avant de continuer, examinez la configuration de l’autorisation OAuth2 dans l’exemple de projet.

Examiner la définition de l’API

Tout d’abord, examinez la configuration de sécurité de la définition d’API incluse dans le projet.

Dans Visual Studio Code :

  1. Ouvrez le fichier appPackage/apiSpecificationFile/repair.yml .

  2. Dans la section components.securitySchemes , notez la propriété oAuth2AuthCode :

    components:
  securitySchemes:
    oAuth2AuthCode:
      type: oauth2
      description: OAuth configuration for the repair service
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/${{AAD_APP_TENANT_ID}}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/${{AAD_APP_TENANT_ID}}/oauth2/v2.0/token
          scopes:
            api://${{AAD_APP_CLIENT_ID}}/repairs_read: Read repair records

    La propriété définit un schéma de sécurité OAuth2 et inclut des informations sur les URL à appeler pour obtenir un jeton d’accès et sur les étendues que l’API utilise.

    Importante

    Notez que l’étendue est complète avec l’URI d’ID d’application (api://...). Lorsque vous utilisez Microsoft Entra vous devez qualifier entièrement les étendues personnalisées. Quand Microsoft Entra voit une étendue non qualifiée, elle suppose qu’elle appartient à Microsoft Graph, ce qui entraîne des erreurs de flux d’autorisation.

  3. Recherchez la propriété paths./repairs.get.security . Notez qu’il fait référence au schéma de sécurité oAuth2AuthCode et à l’étendue dont le client a besoin pour effectuer l’opération.

    [...]
paths:
  /repairs:
    get:
      operationId: listRepairs
      [...]
      security:
        - oAuth2AuthCode:
          - api://${{AAD_APP_CLIENT_ID}}/repairs_read
[...]

    Importante

    La liste des étendues nécessaires dans la spécification de l’API est purement informative. Lors de l’implémentation de l’API, vous êtes responsable de la validation du jeton et de la vérification qu’il contient les étendues nécessaires.

Examiner l’implémentation de l’API

Ensuite, examinez l’implémentation de l’API.

Dans Visual Studio Code :

  1. Ouvrez le fichier src/functions/repairs.ts .

  2. Dans la fonction de gestionnaire de réparations , recherchez la ligne suivante qui vérifie si la demande contient un jeton d’accès avec les étendues nécessaires :

    if (!hasRequiredScopes(req, 'repairs_read')) {
  return {
    status: 403,
    body: "Insufficient permissions",
  };
}

  3. La fonction hasRequiredScopes est implémentée plus loin dans le fichier repairs.ts :

    function hasRequiredScopes(req: HttpRequest, requiredScopes: string[] | string): boolean {
  if (typeof requiredScopes === 'string') {
    requiredScopes = [requiredScopes];
  }

  const token = req.headers.get("Authorization")?.split(" ");
  if (!token || token[0] !== "Bearer") {
    return false;
  }

  try {
    const decodedToken = jwtDecode<JwtPayload & { scp?: string }>(token[1]);
    const scopes = decodedToken.scp?.split(" ") ?? [];
    return requiredScopes.every(scope => scopes.includes(scope));
  }
  catch (error) {
    return false;
  }
}

    La fonction commence par extraire le jeton du porteur de l’en-tête de demande d’autorisation. Ensuite, il utilise le package jwt-decode pour décoder le jeton et obtenir la liste des étendues à partir de la revendication scp . Enfin, il vérifie si la revendication scp contient toutes les étendues requises.

    Notez que la fonction ne valide pas le jeton d’accès. Au lieu de cela, il vérifie uniquement si le jeton d’accès contient les étendues requises. Dans ce modèle, l’API s’exécute sur Azure Functions et implémente la sécurité à l’aide d’Easy Auth, qui est chargée de valider le jeton d’accès. Si la demande ne contient pas de jeton d’accès valide, le runtime Azure Functions le rejette avant d’atteindre votre code. Bien que Easy Auth valide le jeton, il n’case activée pas les étendues nécessaires, ce que vous devez faire vous-même.

Examiner la configuration de la tâche du coffre

Dans ce projet, vous utilisez microsoft 365 Agents Toolkit pour ajouter les informations OAuth au coffre. Microsoft 365 Agents Toolkit inscrit les informations OAuth dans le coffre à l’aide d’une tâche spéciale dans la configuration du projet.

Dans Visual Studio Code :

  1. Ouvrez le fichier ./teampsapp.local.yml .

  2. Dans la section provisionnement , recherchez la tâche oauth/register .

    - uses: oauth/register
  with:
    name: oAuth2AuthCode
    flow: authorizationCode
    appId: ${{TEAMS_APP_ID}}
    clientId: ${{AAD_APP_CLIENT_ID}}
    clientSecret: ${{SECRET_AAD_APP_CLIENT_SECRET}}
    isPKCEEnabled: true
    # Path to OpenAPI description document
    apiSpecPath: ./appPackage/apiSpecificationFile/repair.yml
  writeToEnvironmentFile:
    configurationId: OAUTH2AUTHCODE_CONFIGURATION_ID

    La tâche prend les valeurs des variables de projet TEAMS_APP_ID, AAD_APP_CLIENT_ID et SECRET_AAD_APP_CLIENT_SECRET , stockées dans les fichiers env/.env.local et env/.env.local.user , et les inscrit dans le coffre. Il active également la clé de preuve pour l’échange de code (PKCE) comme mesure de sécurité supplémentaire. Ensuite, il prend l’ID d’entrée du coffre et l’écrit dans le fichier d’environnement env/.env.local. Le résultat de cette tâche est une variable d’environnement nommée OAUTH2AUTHCODE_CONFIGURATION_ID. Microsoft 365 Agents Toolkit écrit la valeur de cette variable dans le fichier appPackages/ai-plugin.json qui contient la définition du plug-in. Au moment de l’exécution, l’agent déclaratif qui charge le plug-in d’API utilise cet ID pour récupérer les informations OAuth du coffre, puis le flux de démarrage et d’authentification pour obtenir un jeton d’accès.

    Importante

    La tâche oauth/register est uniquement responsable de l’inscription des informations OAuth dans le coffre si elles n’existent pas encore. Si les informations existent déjà, microsoft 365 Agents Toolkit ignore l’exécution de cette tâche.

  3. Ensuite, recherchez la tâche oauth/update .

    - uses: oauth/update
  with:
    name: oAuth2AuthCode
    appId: ${{TEAMS_APP_ID}}
    apiSpecPath: ./appPackage/apiSpecificationFile/repair.yml
    configurationId: ${{OAUTH2AUTHCODE_CONFIGURATION_ID}}
    isPKCEEnabled: true

    La tâche conserve les informations OAuth dans le coffre synchronisées avec votre projet. Il est nécessaire que votre projet fonctionne correctement. L’une des propriétés clés est l’URL sur laquelle votre plug-in d’API est disponible. Chaque fois que vous démarrez votre projet, Microsoft 365 Agents Toolkit ouvre un tunnel de développement sur une nouvelle URL. Les informations OAuth dans le coffre doivent référencer cette URL pour que Copilot puisse atteindre votre API.

Examiner la configuration de l’authentification et de l’autorisation

La partie suivante à explorer est celle des paramètres d’authentification et d’autorisation du Azure Functions. L’API de cet exercice utilise les fonctionnalités d’authentification et d’autorisation intégrées de Azure Functions. Microsoft 365 Agents Toolkit configure ces fonctionnalités lors de l’approvisionnement de Azure Functions dans Azure.

Dans Visual Studio Code :

  1. Ouvrez le fichier infra/azure.bicep .

  2. Recherchez la ressource authSettings :

    resource authSettings 'Microsoft.Web/sites/config@2021-02-01' = {
  parent: functionApp
  name: 'authsettingsV2'
  properties: {
    globalValidation: {
      requireAuthentication: true
      unauthenticatedClientAction: 'Return401'
    }
    identityProviders: {
      azureActiveDirectory: {
        enabled: true
        registration: {
          openIdIssuer: oauthAuthority
          clientId: aadAppClientId
        }
        validation: {
          allowedAudiences: [
            aadAppClientId
            aadApplicationIdUri
          ]
        }
      }
    }
  }
}

    Cette ressource active les fonctionnalités d’authentification et d’autorisation intégrées sur l’application Azure Functions. Tout d’abord, dans la section globalValidation , il définit que l’application autorise uniquement les demandes authentifiées. Si l’application reçoit une requête non authentifiée, elle la rejette avec une erreur HTTP 401. Ensuite, dans la section identityProviders, la configuration définit qu’elle utilise Microsoft Entra ID (anciennement Azure Active Directory) pour autoriser les demandes. Il spécifie quelle Microsoft Entra’inscription d’application qu’il utilise pour sécuriser l’API, et quelles audiences sont autorisées à appeler l’API.

Examiner l’inscription de l’application Microsoft Entra

La dernière partie à examiner est l’inscription d’application Microsoft Entra que le projet utilise pour sécuriser l’API. Lorsque vous utilisez OAuth, vous sécurisez l’accès aux ressources à l’aide d’une application. L’application définit généralement les informations d’identification nécessaires pour obtenir un jeton d’accès, tel qu’une clé secrète client ou un certificat. Il spécifie également les différentes autorisations (également appelées étendues) que le client peut demander lors de l’appel de l’API. Microsoft Entra’inscription d’application représente une application dans le cloud Microsoft et définit une application à utiliser avec des flux d’autorisation OAuth.

Dans Visual Studio Code :

  1. Ouvrez le fichier ./aad.manifest.json .

  2. Recherchez la propriété oauth2Permissions .

    "oauth2Permissions": [
  {
    "adminConsentDescription": "Allows Copilot to read repair records on your behalf.",
    "adminConsentDisplayName": "Read repairs",
    "id": "${{AAD_APP_ACCESS_AS_USER_PERMISSION_ID}}",
    "isEnabled": true,
    "type": "User",
    "userConsentDescription": "Allows Copilot to read repair records.",
    "userConsentDisplayName": "Read repairs",
    "value": "repairs_read"
  }
],

    La propriété définit une étendue personnalisée, nommée repairs_read qui accorde au client l’autorisation de lire les réparations à partir de l’API de réparation.

  3. Recherchez la propriété identifierUris .

    "identifierUris": [
  "api://${{AAD_APP_CLIENT_ID}}"
]

    La propriété identifierUris définit un identificateur utilisé pour qualifier entièrement l’étendue.

Testez l’agent déclaratif avec le plug-in d’API dans Microsoft 365 Copilot

La dernière étape consiste à tester l’agent déclaratif avec le plug-in d’API dans Microsoft 365 Copilot.

Dans Visual Studio Code :

  1. Dans la barre d’activité, activez l’extension Microsoft 365 Agents Toolkit .

  2. Dans le panneau de l’extension Microsoft 365 Agents Toolkit , dans la section Comptes , vérifiez que vous êtes connecté à votre locataire Microsoft 365 avec Copilot activé.

    Capture d’écran de Microsoft 365 Agents Toolkit montrant la status de la connexion à Microsoft 365.

  3. Dans la barre d’activité, basculez vers la vue Exécuter et déboguer .

  4. Dans la liste des configurations, choisissez Déboguer dans Copilot (Edge) et appuyez sur le bouton de lecture pour démarrer le débogage.

    Capture d’écran de l’option de débogage dans Visual Studio Code.

    Visual Studio Code ouvre un nouveau navigateur web avec Microsoft 365 Copilot. Si vous y êtes invité, connectez-vous à l’aide de votre compte Microsoft 365.

Dans le navigateur web :

  1. Dans le panneau latéral, sélectionnez l’agent da-repairs-oauthlocal .

    Capture d’écran de l’agent personnalisé affiché dans Microsoft 365 Copilot.

  2. Dans la zone de texte de l’invite, tapez Show repair records assigned to Karin Blair et envoyez l’invite.

    Conseil

    Au lieu de taper l’invite, vous pouvez la sélectionner dans les starters de conversation.

    Capture d’écran d’une conversation démarrée dans l’agent déclaratif personnalisé.

  3. Vérifiez que vous souhaitez envoyer des données au plug-in d’API à l’aide du bouton Toujours autoriser .

    Capture d’écran de l’invite pour autoriser l’envoi de données à l’API.

  4. Lorsque vous y êtes invité, connectez-vous à l’API pour continuer à utiliser le même compte que celui que vous utilisez pour vous connecter à votre client Microsoft 365, en sélectionnant Se connecter à da-repairs-oauthlocal.

    Capture d’écran de l’invite de connexion à l’application qui sécurise l’API.

  5. Attendez que l’agent réponde.

    Capture d’écran de la réponse de l’agent déclaratif à l’invite de l’utilisateur.

Même si votre API est accessible de manière anonyme, car elle s’exécute sur votre ordinateur local, Microsoft 365 Copilot appelle votre API authentifiée comme spécifié dans la spécification de l’API. Vous pouvez vérifier que la demande contient un jeton d’accès en définissant un point d’arrêt dans la fonction de réparation et en envoyant une autre invite dans l’agent déclaratif. Lorsque le code atteint votre point d’arrêt, développez la collection req.headers et recherchez l’en-tête d’autorisation qui contient un jeton web JSON (JWT).

Capture d’écran de Visual Studio Code avec un point d’arrêt et le panneau de débogage montrant l’en-tête d’autorisation sur la requête entrante.

Arrêtez la session de débogage dans Visual Studio Code lorsque vous avez terminé le test.