Sécuriser les appels d’outil OpenAPI à partir du service Agent Foundry

Foundry Agent Service peut appeler un point de terminaison OpenAPI de service d’application de manière anonyme ou avec une identité gérée. Utilisez l’identité gérée lorsque l’authentification par service App protège le point de terminaison.

Ce scénario contient deux directions d’identité gérées indépendantes :

• Lorsque App Service appelle Foundry, l’appelant est l’identité managée attribuée au système App Service. Le contrôle d’accès basé sur le rôle (RBAC) d’Azure sur la ressource ou le projet Foundry autorise l’appel.
• Lorsque Foundry appelle le point de terminaison OpenAPI du service applicatif, l’appelant est l’identité managée attribuée par le système de ressources parent Foundry. La validation des jetons d’authentification d’App Service et les listes d’autorisation autorisent l’appel.

L’application d’authentification du service d’applications Microsoft Entra est la ressource API protégée. Cela ne remplace pas non plus l’appel à l’identité managée.

Le tableau suivant résume les identités et applications dans ce scénario.

Prerequisites

• Une application App Service avec des points de terminaison OpenAPI. Si vous devez ajouter des fonctionnalités OpenAPI à votre application, consultez l’un des didacticiels suivants :

  • Ajouter une application App Service en tant qu’outil dans Foundry Agent Service (.NET)
  • Ajouter une application App Service en tant qu’outil dans Foundry Agent Service (Java)
  • Ajouter une application App Service en tant qu’outil dans Foundry Agent Service (Python)
  • Ajouter une application App Service en tant qu’outil dans Foundry Agent Service (Node.js)

• Un projet Microsoft Foundry où vous ajoutez votre application en tant qu’outil OpenAPI.

Trouvez les identifiants d’identité gérés de la ressource Foundry mère

Le Service d’Agent Foundry utilise l’identité managée assignée par le système de la ressource Foundry parent lorsqu’elle appelle un outil OpenAPI. Il n’utilise pas l’identité gérée du projet Foundry pour cette demande.

Vous avez besoin de deux identifiants pour l’identité de la ressource parent :

• ID d’application (ID client) : Apparaît dans la revendication azp du jeton d’accès et est utilisé pour la vérification des applications clientes autorisées pour l’authentification App Service.
• Identifiant de l’objet (principal) : Apparaît dans la revendication oid du jeton et est utilisé lorsque l’authentification d’App Service restreint l’accès à des identités spécifiques.

1. Dans le portail Foundry, ouvrez votre projet, puis sélectionnez Gérer dans le menu supérieur.

2. Sélectionnez la ressource parente dans les détails du Project, puis sélectionnez Ouvrir dans le portail Azure.

3. Dans le menu de gauche de la ressource Foundry, sélectionnez Resource Management>Identity.

4. Sous Système affecté, copiez la valeur de l’ID d’objet (principal) pour une version ultérieure.

5. Dans le portail Azure, recherchez et sélectionnez Microsoft Entra ID.

6. Dans la zone de recherche, recherchez l’ID d’objet que vous avez copié et sélectionnez-le dans les résultats de recherche.

7. Dans la page Vue d’ensemble , copiez la valeur de l’ID d’application.

   L’ID d’objet est le même que celui affiché pour l’identité managée attribuée au système. Sauvegardez à la fois l’ID de l’application et l’ID de l’objet pour configurer l’authentification des services d’applications.

Configurer l’authentification Microsoft Entra pour votre application

1. Dans le portail Azure, accédez à votre application App Service.

2. Dans le menu de gauche de votre application, sélectionnez Paramètres>Authentification, puis Ajouter un fournisseur d’identité.

3. Dans la page Ajouter un fournisseur d’identité , sélectionnez Microsoft comme fournisseur d’identité pour créer une inscription d’application.

4. Pour Restreindre l’accès, sélectionnez Exiger l’authentification.

5. Sous Vérifications supplémentaires, pour connaître les exigences de l’application cliente, sélectionnez Autoriser les demandes à partir d’applications clientes spécifiques.

6. Sélectionnez l’icône du crayon et configurez les applications clientes autorisées :

   • Ajoutez l’ID d’application que vous avez copié dans Rechercher les ID d’identité managée de la ressource Foundry parente. Cet ID permet les jetons demandés par l’identité de la ressource Foundry parent.
   • Si l'application prend en charge la connexion interactive au navigateur, ajoutez également l'ID d'application (client) propre à l'application Microsoft Entra d'authentification App Service. Cet ID permet d’émettre des jetons à l’application web lors de la connexion de l’utilisateur. Si vous créez une nouvelle inscription d’application, ajoutez cet ID après avoir créé le fournisseur d’identité.

7. Configuration des exigences d’identité :

   • Pour la politique la plus étroite sur un point de terminaison appelé uniquement par Foundry, sélectionnez Autoriser les requêtes provenant d’identités spécifiques. Sélectionnez l’icône en forme de crayon et ajoutez l’ID d’objet de l’identité de la ressource Foundry parente.
   • Si l’application supporte également la connexion interactive par navigateur, sélectionnez Autoriser les requêtes depuis n’importe quelle identité afin que les utilisateurs locataires ne soient pas bloqués. Ce paramètre n’autorise pas l’accès anonyme. Les requêtes doivent toujours contenir un jeton valide provenant d’une application cliente autorisée et du locataire configuré.

8. Pour Condition du locataire, sélectionnez Autoriser uniquement les demandes provenant du locataire émetteur. L’identité de la ressource Foundry parente et tous les utilisateurs qui se connectent doivent appartenir à ce locataire.

9. Configurez les requêtes non authentifiées :

   • Si l’application ne sert que les clients API, sélectionnez HTTP 401 Non autorisé : recommandé pour les API.
   • Si l’application supporte la connexion interactive au navigateur, sélectionnez HTTP 302 Redirection trouvée, puis sélectionnez Microsoft comme fournisseur de redirection.

10. Sélectionnez Ajouter pour créer le fournisseur d’identité.

    L’image suivante montre la configuration la plus étroite réservée à Foundry.

    

11. Si l’application supporte la connexion interactive du navigateur, modifiez le fournisseur et assurez-vous que le magasin de jetons est activé. Si vous avez créé une nouvelle inscription d’application, ajoutez son identifiant d’application aux applications clients autorisées.

Vous avez besoin des deux identifiants d’application lorsque l’application supporte la connexion interactive du navigateur. Une API Foundry uniquement nécessite seulement l’ID d’application de l’identité de la ressource Foundry parente.

Mettre à jour l'URI de l'ID d'application pour l'enregistrement de l'application

Une URI d’ID d’application identifie l’API protégée comme une ressource OAuth. Pour un outil OpenAPI d’identité managée, l’audience doit correspondre exactement à une URI d’ID d’application enregistrée sur l’application Microsoft Entra d’authentification du service d’applications. Foundry utilise cette valeur comme audience lorsqu’il demande un jeton d’accès avec l’identité de ressource Foundry parente.

L’ID Application et l’URI Application ID sont des propriétés différentes :

• L’ID d’application, également appelé identifiant client, est un GUID généré.
• Une URI d’ID d’application est une URI qui identifie une API ou une ressource appartenant à l’application. Il n’est pas nécessaire de contenir l’identifiant client de l’application.

Choisissez une URI d’identification d’application stable et considérez-la comme faisant partie du contrat API :

L’URI doit être valide, unique dans le locataire et acceptée par la politique d’URI Application ID du locataire. Une chaîne de caractères simples comme some-random-string n’est pas un URI d’ID d’application valide.

Ce guide utilise l’URL complète du service d’application HTTPS :

https://<app-name>.azurewebsites.net

1. Une fois la configuration du fournisseur Microsoft terminée, sélectionnez-la dans la colonne Fournisseur d’identité pour ouvrir la page d’inscription de l’application.

2. Dans le menu de gauche, sélectionnez Gérer l’exposition>d’une API.

3. En regard de l’URI de l’ID d’application, sélectionnez Modifier.

4. Modifiez la valeur pour l’URL HTTPS complète de votre application App Service, comme https://<app-name>.azurewebsites.net.

   Vous trouverez le nom d’hôte de l’application dans la page Vue d’ensemble du domaine par défaut.

5. Pour une nouvelle inscription à l’application, assurez-vous que la version du jeton Access est réglée à 2.

6. Cliquez sur Enregistrer.

Changer ensuite l’URI de l’ID d’application nécessite de mettre à jour l’audience de l’outil Foundry et tous les autres clients qui demandent des jetons pour l’API.

La configuration correspondante de l’authentification de l’outil OpenAPI est la suivante :

{
  "type": "managed_identity",
  "security_scheme": {
    "audience": "https://<app-name>.azurewebsites.net"
  }
}

Vous n’avez pas besoin de répertorier l’audience de l’outil dans Allowed token audiences. L’authentification par App Service reconnaît les identifiants de ressources que vous enregistrez sur son application Microsoft Entra. Inversement, ajouter une valeur uniquement à Destinataires de jetons autorisés n’enregistre pas de ressource OAuth et ne permet pas à Microsoft Entra d’émettre un jeton pour cette ressource.

N’utilisez pas le point de terminaison du projet Foundry ni l’ID client du service App comme audience à moins de configurer cette valeur exacte comme l’URI de l’ID d’application. D’autres formats d’URI d’ID d’application valides, y compris les URI api://, fonctionnent lorsque la valeur enregistrée et l’audience correspondent exactement. Pour les cas limites connexes, consultez la Foire aux questions.

Configurez l’API protégée de manière déclarative

Utilisez Bicep pour configurer l’API protégée et la politique d’authentification des services d’application. Le schéma suivant suppose :

• webApp est la ressource App Service.
• entraAppest un module qui crée l’application d’authentification des services d’applications Microsoft Entra.
• foundryAccountClientId est l’identifiant d’application de l’identité de ressource Foundry parente.
• appServiceAuthCredentialSettingName est le nom du paramètre d’application contenant le secret client existant d’authentification du service d’application.

Dans le module d’application Microsoft Graph Bicep, configurez l’URL du service App comme URI d’identifiant et demandez les jetons d’accès version 2 :

extension microsoftGraphV1

param environmentName string
param appServiceUrl string

resource app 'Microsoft.Graph/applications@v1.0' = {
  uniqueName: 'my-app-${environmentName}'
  displayName: 'My app (${environmentName})'
  signInAudience: 'AzureADMyOrg'
  identifierUris: [
    appServiceUrl
  ]
  api: {
    requestedAccessTokenVersion: 2
  }
  web: {
    homePageUrl: appServiceUrl
    redirectUris: [
      '${appServiceUrl}/.auth/login/aad/callback'
    ]
  }
}

output clientId string = app.appId
output webAppUrl string = appServiceUrl

L’exemple suivant authsettingsV2 permet à la fois la connexion interactive par navigateur et les appels Foundry OpenAPI :

@description('Parent Foundry resource identity application ID')
param foundryAccountClientId string = ''

resource webAppAuthSettings 'Microsoft.Web/sites/config@2024-11-01' = {
  name: '${webApp.name}/authsettingsV2'
  properties: {
    platform: {
      enabled: true
    }
    globalValidation: {
      requireAuthentication: true
      unauthenticatedClientAction: 'RedirectToLoginPage'
      redirectToProvider: 'azureActiveDirectory'
    }
    identityProviders: {
      azureActiveDirectory: {
        enabled: true
        registration: {
          clientId: entraApp.outputs.clientId
          clientSecretSettingName: appServiceAuthCredentialSettingName
          openIdIssuer: 'https://login.microsoftonline.com/${tenant().tenantId}/v2.0'
        }
        validation: {
          allowedAudiences: [
            'api://${entraApp.outputs.clientId}'
          ]
          defaultAuthorizationPolicy: {
            allowedApplications: concat(
              [
                entraApp.outputs.clientId
              ],
              empty(foundryAccountClientId) ? [] : [foundryAccountClientId]
            )
            allowedPrincipals: {}
          }
        }
      }
    }
    login: {
      tokenStore: {
        enabled: true
      }
    }
    httpSettings: {
      requireHttps: true
    }
  }
}

Passer l’ID de l’application Foundry resource identity via Azure Developer CLI (AZD) :

{
  "foundryAccountClientId": {
    "value": "${AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID=}"
  }
}

Ensuite, configurez l’environnement et redéployez :

azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
azd provision

Configurer l’outil OpenAPI dans Microsoft Foundry

1. Dans le portail Foundry, sélectionnez votre agent.

2. Recherchez l’outil OpenAPI et sélectionnez ...>Modifier.

3. Vérifiez que la boîte de schéma OpenAPI 3.0+ contient le schéma de votre application App Service. Si ce n’est pas le cas, collez votre schéma OpenAPI. Pour plus d’informations, consultez Comment utiliser OpenAPI avec le service De l’agent Foundry.

4. Pour la méthode d’authentification, sélectionnez Identité managée.

5. Dans Audience, saisissez l’URI d’ID d’application que vous avez configuré précédemment. Pour la configuration dans ce guide, utilisez l’URL HTTPS complète de votre application App Service, comme https://<app-name>.azurewebsites.net. Les valeurs doivent correspondre exactement.

6. Sélectionnez l’outil Mettre à jour.

Tester l’agent

1. Dans le portail Foundry, sélectionnez votre agent et choisissez Essayer dans l'environnement de test.

2. Discutez avec l’agent pour tester vos points de terminaison OpenAPI. Par exemple:

   • Affichez-moi toutes les tâches.
   • Créez une tâche appelée « Acheter des épiceries ».
   • Mettez à jour cette tâche pour « Acheter des épiceries et cuisiner le dîner ».

Si vous configurez correctement l’authentification, l’agent appelle les API de votre application via l’outil OpenAPI.

Questions fréquemment posées

Pourquoi puis-je sauvegarder l’outil OpenAPI avant de configurer l’autorisation des services d’application ?

Lorsque vous sauvegardez un outil OpenAPI, Foundry valide son schéma, son format d’audience et sa définition. Il n’appelle pas le point de terminaison App Service. Vous pouvez donc sauvegarder l’outil avant d’ajouter l’identité de la ressource Foundry parent à la liste des autorisations du service d’applications.

Configurez la liste d’autorisation avant d’appeler l’outil dans le playground ou à l’exécution. Jusqu’à ce moment-là, App Service rejette les appels d’outils.

Pourquoi le public par défaut api://<client-id> échoue-t-il parfois ?

Le portail App Service crée généralement une application Microsoft Entra avec api://<application-client-id> pour URI d’application ID. Dans ce cas, Foundry peut utiliser la même valeur que son audience.

Le provisionnement personnalisé ou déclaratif peut laisser vide la collection identifierUris de l’application Microsoft Entra, même lorsque l’authentification App Service affiche api://<client-id> sous Audiences de jeton autorisées. Dans cet état, Foundry ne peut pas obtenir de token d’identité géré pour cette valeur car il ne s’agit pas d’un identifiant de ressource enregistré.

Pour résoudre le problème, utilisez l’une de ces options :

• Enregistrez api://<client-id> comme URI d’ID d’application et utilisez-le comme audience de Foundry.
• Enregistrez l’URL HTTPS d’App Service comme l’URI d’ID d’application et utilisez cette URL comme audience de Foundry.

Ne corrigez pas le décalage en ajoutant des chaînes arbitraires à allowedAudiences.

L’authentification App Service peut-elle fonctionner sans URI d’ID d’application ?

La connexion interactive par navigateur peut fonctionner sans URI d’ID d’application car le flux du navigateur utilise un token ID pour l’ID client de l’application web.

Le flux OpenAPI géré par Foundry nécessite un jeton d’accès pour une ressource API enregistrée. Pour ce flux, configurez un URI d’ID d’application et utilisez la même valeur que l’audience de l’outil.

Résoudre les problèmes d’authentification et d’autorisation

L’outil OpenAPI reçoit HTTP 401

Une réponse HTTP 401 signifie que l’authentification par App Service n’a pas pu authentifier la requête. Les causes probables sont les suivantes :

• Vous n’avez pas sélectionné l’identité managée pour l’outil OpenAPI.
• L’audience ne correspond pas exactement à l’URI de l’ID d’application Microsoft Entra.
• L’émetteur ou le locataire du jeton ne correspond pas à l’authentification App Service.
• Vous n'avez pas configuré l'URI de l'ID d'application sur l'application Microsoft Entra.

Vérifiez que l’audience OpenAPI correspond exactement à un URI d’ID d’application enregistré. Pour la configuration dans ce guide, la valeur est l’URL HTTPS complète du service applicatif.

L’outil OpenAPI reçoit HTTP 403

Une réponse HTTP 403 signifie que l’authentification a réussi, mais que les vérifications d’autorisation ont rejeté l’appelant. Les causes probables sont les suivantes :

• Vous avez ajouté l’identité du projet Foundry à la liste d’autorisation au lieu de l’identité de la ressource Foundry parente.
• Vous avez saisi l’ID d’objet où l’authentification par App Service nécessite un identifiant d’application.
• Vous n’avez pas ajouté l’identifiant de l’application de ressource parent à allowedApplications.
• Vous n’avez pas ajouté l’ID de l’objet de ressource parent à la liste d’identité autorisée pour une configuration uniquement Foundry.

Examinez les revendications du jeton d’accès :

• azp doit être égal à l’ID d’application de l’identité de ressource Foundry parente.
• oid doit être égal à l’ID d’objet de l’identité de ressource Foundry parente.

Les utilisateurs du navigateur reçoivent HTTP 403 après s’être connectés

Pour une application qui prend en charge la connexion interactive du navigateur, vérifiez ces paramètres :

• L’identifiant client propre de l’application web reste dans allowedApplications.
• L’exigence relative à l’identité autorise les utilisateurs standard du locataire.
• Les requêtes de navigateur non authentifiées utilisent HTTP 302 plutôt que HTTP 401.

L’outil fonctionne de manière anonyme mais échoue après l’activation de l’authentification

Mettez à jour l’outil de Anonyme vers identité managée, définissez l’audience sur un URI d’ID d’application enregistré et autorisez l’identité de la ressource Foundry parente.

Nettoyer les ressources

Lorsque vous supprimez ou remplacez des ressources de ce scénario :

• Supprimez l’identité de ressource Foundry parent de l’authentification des services d’applications lorsque vous supprimez ou remplacez la ressource Foundry.
• Supprimez l’application Microsoft Entra d’authentification App Service lorsque vous supprimez définitivement l’application App Service. Cette étape permet également d’éviter le risque d’URI d’ID d’application orphelin décrit précédemment.
• Si vous utilisez une identité assignée par l’utilisateur et une identifiante d’identité fédérée pour l’authentification des services d’applications non secrètes, supprimez cette identité et cette identifiance fédérée avec l’application.

Contenu connexe

• Configurer votre application App Service ou Azure Functions pour utiliser la connexion à Microsoft Entra
• Intégrer l’IA à vos applications Azure App Service
• Qu’est-ce que le Service de l’agent Foundry ?