Fonctionnement de l’authentification de la boîte à outils dans Microsoft Foundry

L’authentification de boîte à outils dans Microsoft Foundry détermine comment les outils s’authentifient auprès des services en aval. Les paramètres d’authentification sont configurés sur les connexions de projet, ce qui permet aux agents d’utiliser l’accès anonyme, les informations d’identification partagées, les identités de service ou l’identité d’un utilisateur connecté sans implémenter la logique d’authentification dans le code de l’agent.

Cet article explique comment l’authentification de la boîte à outils fonctionne et explique comment configurer le passage d’identité OAuth pour un serveur MCP privé et Work IQ tout en préservant les autorisations et les limites d’accès de chaque utilisateur.

Pour la délégation d’utilisateurs avec MCP et d’autres outils, connectez-les via une boîte à outils Foundry. Lors de l’ajout de cette boîte à outils à un agent hébergé Microsoft Agent Framework, utilisez-la FoundryToolbox dans Python ou AddFoundryToolboxes dans .NET. Consultez Utiliser une boîte à outils avec un agent hébergé.

Une boîte à outils centralise l’authentification sur la connexion. L’authentification est une propriété de la connexion, et non du code dans votre agent. Lorsque vous connectez un outil, vous sélectionnez un type d’authentification et Foundry gère l’acquisition, l’échange, l’actualisation et l’injection de jetons côté service. Votre code d’agent reste axé sur la logique métier plutôt que sur les flux d’authentification.

Pourquoi l’authentification par utilisateur est difficile à créer vous-même

Si vous mettez vous-même en place un accès par utilisateur aux outils protégés par Entra, vous vous chargez de mécanismes techniques essentiels à la sécurité, qu’il est facile de mal configurer sans s’en rendre compte :

  1. Implémentez vous-même l’isolation des jetons par utilisateur. Vous devez partitionner correctement les caches de jetons selon l’utilisateur et le locataire. Une clé de cache erronée peut divulguer silencieusement à un autre utilisateur l’accès d’un utilisateur à une API en aval, un bogue qui passe tous les tests fonctionnels.
  2. Gérez le consentement et le cycle de vie par utilisateur, par ressource. Vous devez détecter les échecs de consentement tels que AADSTS65001, envoyer des utilisateurs via le consentement, actualiser les jetons expirés et gérer les nouvelles tentatives 401/403 correctement pour chaque API dans chaque agent que vous écrivez.
  3. Absorbez la complexité qui évolue linéairement en fonction du nombre d’outils et d’agents. Chaque nouvel outil ajoute un périmètre d’autorisation supplémentaire, un échange de jetons, une entrée de cache, un parcours de consentement, un chemin de nouvelle tentative et un chemin d’en-tête. À mesure que vous effectuez une mise à l’échelle vers des centaines d’outils et des milliers d’agents, vous reconstruisez la même plomberie fragile encore et encore.

Les deux identités lors de chaque appel d’outil

Pour les appels d’outils par utilisateur médiatés par agent, distinguez l’identité de l’agent qui accède à la boîte à outils de l’identité utilisateur utilisée en aval. Séparez ces identités pour les utilisateurs simultanés.

  • Interface entre l’agent et la boîte à outils (la version stable). L’agent s’authentifie auprès de la plateforme avec son propre identité d’agent. Cette identité permet d’accéder à la boîte à outils elle-même, et non aux outils individuels qu’elle contient.
  • Frontière entre l’outil et les données (celle par utilisateur). Pour l’appel de données réel, Foundry fournit le service en aval avec des informations d’identification qui représentent l’utilisateur connecté. Selon le type d’authentification, ces informations d’identification proviennent d’un flux d’autorisation OAuth ou d’un jeton d’accès Microsoft Entra spécifique à l’audience. Le service en aval retourne uniquement ce que l’utilisateur peut accéder et respecte ses autorisations et étiquettes de confidentialité.

Comment une boîte à outils gère l’authentification

Un ensemble d’outils transfère entièrement la charge liée à l’authentification de votre agent vers la connexion :

  • L’authentification se fait au niveau de la connexion, pas de l’assistant. Vous choisissez un type d’authentification une fois, lorsque vous connectez un outil. Le code de l’agent ne nécessite pas d’authentification.
  • Foundry gère l’ensemble du flux. Selon les besoins d’un outil, Foundry stocke et injecte des clés API, obtient des informations d’identification pour les identités de service, termine l’autorisation OAuth ou fournit un jeton d’accès Microsoft Entra spécifique à l’audience. Foundry isole les informations d’identification par utilisateur des autres utilisateurs.
  • Vous créez simplement une logique métier. Le flux d’authentification n’a jamais été à vous de développer.
Le fardeau du DIY Qu’est-ce qu’une boîte à outils fait à la place
Isolation des tokens par utilisateur Foundry isole automatiquement les jetons pour chaque appelant. Il n’y a pas de clé de cache sur laquelle se tromper.
Gestion du consentement et du cycle de vie, par utilisateur et par ressource Foundry gère le flux de consentement et le cycle de vie des jetons pour chaque utilisateur, notamment l’acquisition et l’actualisation des jetons une fois le consentement requis accordé.
Authentification réappliquée par outil et par équipe Vous créez une boîte à outils avec ses outils et authentification une seule fois, puis la réutilisez sur chaque agent et runtime.

Définir le type d’authentification sur la connexion

Vous choisissez le type d’authentification lorsque vous créez la connexion, dans le portail, avec l’interface CLI Azure développeur ou via l’API REST. Jamais dans le code de l’agent. Chaque type d’authentification détermine de qui l’identité parvient jusqu’à l’outil :

authType Dont l’identité accède à l’outil Utilisez-le pour
none Anonyme Serveurs publics (par exemple, le serveur Microsoft Learn MCP).
custom-keys Une clé d’API stockée ou un en-tête SaaS basé sur des clés. L’agent ne voit jamais le secret.
project-managed-identity Identité managée du projet Appels de service à service sans contexte utilisateur.
agentic-identity Identité de l’agent Audit par agent et privilège minimum.
oauth2 Utilisateur qui termine l’autorisation OAuth Services conformes à OAuth, notamment les serveurs Work IQ et MCP partenaires (par exemple, Vercel).
user-entra-token Utilisateur Microsoft Entra connecté Services Microsoft gérés qui nécessitent un jeton Entra destiné à une audience spécifique, tels que les points de terminaison de l’assistant de données Fabric privés de l’espace de travail.

oauth2 et user-entra-token prennent tous deux en charge l’accès par utilisateur, mais ils obtiennent les identifiants différemment. Avec oauth2, l’utilisateur termine un flux d’autorisation OAuth et Foundry stocke et actualise les informations d’identification résultantes. Avec user-entra-token, Foundry fournit au service en aval un jeton d’accès Microsoft Entra destiné à une audience spécifique, qui représente l’utilisateur connecté. Utilisez le type d’authentification requis par le service.

Configurer une connexion pour chaque type d’authentification

Inscrivez chaque connexion avec azd ai connection create. La forme de commande est toujours la même ; les indicateurs diffèrent par type d’authentification. Utiliser --kind remote-tool pour les serveurs MCP et A2A.

azd ai connection create my-mcp-conn \
  --kind remote-tool \
  --target https://public-mcp.example.com/mcp \
  --auth-type none

Procédure pas à pas : passthrough d’identité OAuth

Cet exemple connecte deux outils protégés par Microsoft Entra pour l’accès par utilisateur : un serveur MCP de commandes privées et Work IQ. Les deux utilisent le passage d’identité OAuth, de sorte que chaque appel en aval s’exécute en tant qu’utilisateur qui autorise la connexion.

1. Créer une connexion pour chaque outil

# Private orders MCP: OAuth identity passthrough
azd ai connection create orders-mcp \
  --kind remote-tool \
  --target https://orders-mcp.example.com/mcp \
  --auth-type oauth2 \
  --authorization-url https://auth.example.com/authorize \
  --token-url https://auth.example.com/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "openid,offline_access,orders.read"

# Work IQ: OAuth identity passthrough
azd ai connection create workiq-conn \
  --kind remote-a2a \
  --target https://workiq.svc.cloud.microsoft/a2a/ \
  --auth-type oauth2 \
  --authorization-url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/authorize \
  --token-url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token \
  --client-id <oauth-client-id> \
  --client-secret <oauth-client-secret> \
  --scopes "api://workiq.svc.cloud.microsoft/WorkIQAgent.Ask,offline_access"

2. Ajouter les deux outils à une boîte à outils

Chaque outil fait référence à sa connexion par ID. Cette référence unique est toute la différence entre l’exécution en tant que compte de service partagé et l’action au nom de l’utilisateur connecté. Votre agent n’a pas besoin d’un répartiteur de jetons ou d’un cache de jetons par utilisateur.

Cet exemple nécessite azure-ai-projects (Python) ou @azure/ai-projects (TypeScript) version 2.3.0 ou ultérieure.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, WorkIQPreviewToolboxTool

endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())
orders_connection = project.connections.get("orders-mcp")
workiq_connection = project.connections.get("workiq-conn")

toolbox_version = project.toolboxes.create_version(
    name="employee-toolbox",
    description="Private orders MCP + Work IQ, both via OAuth identity passthrough.",
    tools=[
        MCPToolboxTool(
            server_label="orders",
            server_url="https://orders-mcp.example.com/mcp",
            require_approval="never",
            project_connection_id=orders_connection.id,
        ),
        WorkIQPreviewToolboxTool(project_connection_id=workiq_connection.id),
    ],
)
print(f"Created toolbox: {toolbox_version.name}, version: {toolbox_version.version}")

Pour JavaScript, consultez les exemples maintenus de connexion de projet Toolbox et Work IQ. Le premier exemple crée une boîte à outils sauvegardée par MCP qui utilise une connexion de projet et l’attache à un agent. Le deuxième exemple montre comment faire référence à la connexion du projet Work IQ.

3. Connecter l’agent à la boîte à outils

L’agent se connecte au point de terminaison consommateur unique de la boîte à outils, qui sert toujours la version par défaut. L’agent s’authentifie auprès de la plateforme avec sa propre identité. Pour chaque outil, Foundry fournit des informations d’identification qui représentent l’utilisateur qui a terminé l’autorisation OAuth. L’agent n’a pas de code d’authentification par outil.

Les informations d’identification de l’agent seules ne suffisent pas pour la résolution par utilisateur. Utilisez FoundryToolbox en Python ou AddFoundryToolboxes en .NET avec l’intégration d’hébergement Foundry. Il transfère le x-agent-foundry-call-id de la requête hébergée actuelle afin que le proxy de la boîte à outils puisse résoudre le contexte de l’appelant. Ne codez pas en dur l’ID d’appel ou réutilisez-le dans les requêtes utilisateur. La connexion de l’outil doit également utiliser le type d’authentification par utilisateur approprié, et l’utilisateur a besoin d’autorisations en aval et de tout consentement requis. Pour l’installation de l’hébergement, consultez Utiliser une boîte à outils avec un agent hébergé.

from azure.identity import DefaultAzureCredential
from agent_framework import FoundryToolbox

# Agent-to-toolbox identity: the agent's own credential, scoped to the platform
credential = DefaultAzureCredential()

# Consumer endpoint always resolves to the toolbox's default version
CONSUMER_URL = f"{endpoint}/toolboxes/employee-toolbox/mcp?api-version=v1"

toolbox = FoundryToolbox(
    name="employee_toolbox",
    url=CONSUMER_URL,
    http_client=http_client,
    load_prompts=False,
)

agent = chat_client.as_agent(
    name="employee-agent",
    instructions="Help employees with their orders and Microsoft 365 context.",
    tools=[toolbox],
)

Foundry génère un lien de consentement la première fois qu’un utilisateur particulier doit autoriser un outil. Après leur consentement, les appels suivants utilisent les informations d’identification de cet utilisateur. L’utilisateur peut avoir besoin d’autoriser à nouveau l’outil si le jeton d’actualisation expire ou est révoqué.

Note

Les consommateurs d’un assistant qui utilise la transmission de l’identité OAuth doivent disposer au minimum du rôle Consommateur de l’agent Foundry dans le projet. Le locataire Microsoft Entra de l’utilisateur doit correspondre au locataire de votre projet Foundry ; l’échange de jetons entre locataires n’est pas pris en charge.

Au-delà de la procédure pas à pas : qu’est-ce qu’une boîte à outils vous donne ?

Comme le trafic d’authentification et celui des outils transitent par la boîte à outils, vous bénéficiez de bien plus qu’une gestion fiable des identités :

  • Garde-fous pour une IA responsable. Les garde-fous filtrent les entrées et les sorties de chaque outil, de sorte qu’une réponse MCP non fiable ne peut pas réinjecter subrepticement dans l’agent une injection de requête ou un contenu dangereux.
  • Apportez votre propre passerelle IA. Placez vos serveurs MCP derrière Gestion des API Azure (APIM) pour la limitation du débit, la journalisation et la stratégie réseau.
  • Contrôle de version. Créez et testez une nouvelle version de boîte à outils, puis faites-la passer par défaut. Chaque agent qui pointe vers le point de terminaison du consommateur récupère automatiquement la version promue, sans aucune modification du code.

Accès direct aux clients de la boîte à outils et accès via un agent

L’authentification au point de terminaison de la boîte à outils est distincte de l’authentification aux outils en aval. Un client qui se connecte directement à une toolbox, plutôt que par le biais d’un agent Foundry, ne peut pas utiliser la connexion Blueprint de l’agent pour accéder au point de terminaison de la toolbox. Les clients directs ne peuvent pas non plus utiliser AgentOnBehalfOfUser pour les appels d’outils en aval.

Pour la délégation directe des utilisateurs de la boîte à outils, utilisez une connexion OAuth distincte par outil avec une connexion OAuth2. Ce flux est décrit comme une connexion OAuth dans la conversation pour les agents, bien que l’interface exposée par un client MCP ne soit pas nécessairement conversationnelle. Foundry stocke et actualise les identifiants par utilisateur qui en résultent. Cette connexion ne remplace pas l’authentification du client à la boîte à outils elle-même.

Le client doit reconnaître une demande d’autorisation interactive, la présenter à l’utilisateur et continuer après la connexion. Ne supposez pas qu’un client MCP générique ou un agent qui consomme la réponse gère automatiquement ce flux. Configurer OAuth2 sur la connexion seule n’est pas suffisant.

Ces limitations liées aux clients directs ne décrivent pas l’accès via un agent. Lorsqu’un agent Foundry accède aux outils via une boîte à outils, le comportement de délégation disponible dépend du point de terminaison de l’agent et de la connexion de l’outil. Consultez délégation d’utilisateur pour les outils pour le modèle d’acteur et Configurer la délégation d’utilisateur pour les exigences de point de terminaison et de connexion.