Funktionsweise der Toolboxauthentifizierung in Microsoft Foundry

Die Toolboxauthentifizierung in Microsoft Foundry bestimmt, wie Tools sich bei nachgeschalteten Diensten authentifizieren. Authentifizierungseinstellungen werden für Projektverbindungen konfiguriert, sodass Agents anonymen Zugriff, freigegebene Anmeldeinformationen, Dienstidentitäten oder die Identität eines angemeldeten Benutzers verwenden können, ohne die Authentifizierungslogik im Agentcode zu implementieren.

In diesem Artikel wird erläutert, wie die Toolboxauthentifizierung funktioniert und wie Sie OAuth-Identitätspassthrough für einen privaten MCP-Server und Work IQ konfigurieren und gleichzeitig die Berechtigungen und Zugriffsgrenzen jedes Benutzers beibehalten.

Eine Toolbox zentralisiert die Authentifizierung für die Verbindung. Die Authentifizierung ist eine Eigenschaft der Verbindung, nicht code in Ihrem Agent. Wenn Sie ein Tool verbinden, wählen Sie einen Authentifizierungstyp aus, und Foundry verarbeitet Tokenakquisition, Austausch, Aktualisierung und Einfügung auf der Dienstseite.When you connect a tool, you select an authentication type and Foundry handles token acquisition, exchange, refresh, and injection on the service side. Ihr Agentcode konzentriert sich weiterhin auf geschäftslogik und nicht auf Authentifizierungsflüsse.

Warum es schwierig ist, eine benutzerspezifische Authentifizierung selbst zu entwickeln

Wenn Sie den benutzerspezifischen Zugriff auf durch Entra geschützte Tools selbst einrichten, übernehmen Sie sicherheitskritische technische Grundlagen, bei deren Umsetzung man leicht subtile Fehler machen kann:

  1. Implementieren Sie die Isolation pro Benutzertoken selbst. Sie müssen Token-Caches ordnungsgemäß nach Benutzer und Mandant partitionieren. Ein falscher Cache-Schlüssel kann unbemerkt einem anderen Benutzer den nachgelagerten API-Zugriff eines Benutzers zugänglich machen – ein Fehler, der jeden Funktionstest besteht.
  2. Verwalten Sie die Zustimmung und den Lebenszyklus pro Benutzer pro Ressource. Sie müssen Fehler bei der Einwilligung wie AADSTS65001 erkennen, Benutzer den Einwilligungsprozess durchlaufen lassen, abgelaufene Token erneuern und Wiederholungen bei 401/403-Fehlern für jede API in jedem Agenten, den Sie schreiben, korrekt behandeln.
  3. Nehmen Sie Komplexität auf, die linear mit Tools und Agenten skaliert wird. Jedes neue Tool fügt einen weiteren Bereich, Tokenaustausch, Cacheeintrag, Zustimmungspfad, Wiederholungspfad und Headerpfad hinzu. Wenn Sie auf Hunderte von Werkzeugen und Tausende von Agenten skalieren, bauen Sie immer wieder die gleiche fragile Sanitärinstallation wieder auf.

Die beiden Identitäten in jedem Toolaufruf

Das gedankliche Modell, das beibehalten werden soll: Es gibt immer zwei Identitäten, und alles, was bei der benutzerspezifischen Authentifizierung schwierig ist, lebt darin, sie korrekt, getrennt und niemals über gleichzeitige Benutzer hinweg zu kreuzen.

  • Agent-zu-Toolbox-Grenze (die stabile Grenze). Der Agent authentifiziert sich mit seiner eigenen Agent-Identität bei der Plattform. Diese Identität steuert den Zugriff auf die Toolbox selbst, nicht auf die einzelnen Werkzeuge darin.
  • Tool-zu-Daten-Grenze (die pro Benutzer). Für den tatsächlichen Datenaufruf liefert Foundry den nachgeschalteten Dienst mit Anmeldeinformationen, die den angemeldeten Benutzer darstellen. Je nach Authentifizierungstyp stammen diese Anmeldeinformationen aus einem OAuth-Autorisierungsablauf oder einem zielgruppenspezifischen Microsoft Entra-Zugriffstoken. Der nachgeschaltete Dienst gibt nur das zurück, auf was der Benutzer zugreifen kann, und berücksichtigt seine Berechtigungen und Vertraulichkeitsbezeichnungen.

So behandelt eine Toolbox die Authentifizierung

Eine Toolbox verschiebt den gesamten Authentifizierungsaufwand von Ihrem Agent und in die Verbindung:

  • Die Authentifizierung liegt in der Verbindung, nicht im Agenten. Sie wählen einmal einen Authentifizierungstyp aus, wenn Sie ein Tool verbinden. Der Agentcode bleibt authentifizierungsfrei.
  • Foundry übernimmt den gesamten Ablauf. Je nachdem, was ein Tool benötigt, speichert und übergibt Foundry API-Schlüssel, beschafft Anmeldeinformationen für Dienstidentitäten, führt die OAuth-Autorisierung durch oder stellt ein zielgruppenspezifisches Microsoft-Entra-Zugriffstoken bereit. Foundry isoliert Anmeldeinformationen pro Benutzer von anderen Benutzern.
  • Sie erstellen einfach Geschäftslogik. Es war nie Ihre Aufgabe, den Authentifizierungsablauf zu entwickeln.
Die DIY-Belastung Was eine Toolbox stattdessen macht
Token-Isolierung pro Benutzer Foundry isoliert Token pro Aufrufer automatisch. Es gibt keinen Cache-Schlüssel, den man falsch eingeben kann.
Zustimmungs- und Lebenszyklusbehandlung, pro Benutzer und pro Ressource Foundry verwaltet den Zustimmungsfluss und den Tokenlebenszyklus für jeden Benutzer, einschließlich des Abrufens und Aktualisierens von Token, nachdem die erforderliche Zustimmung erteilt wurde.
Erneut implementierte Authentifizierung pro Tool und pro Team Sie erstellen eine Toolbox mit ihren Tools und der Authentifizierung einmal, und verwenden Sie sie dann für jeden Agent und jede Laufzeit wieder.

Festlegen des Authentifizierungstyps für die Verbindung

Sie wählen den Authentifizierungstyp aus, wenn Sie die Verbindung im Portal mit der Azure Developer CLI oder über die REST-API erstellen. Nie im Agentcode. Jeder Authentifizierungstyp bestimmt, wessen Identität beim Tool ankommt:

authType Wessen Identität das Tool erreicht Verwenden Sie es für
none Anonym Öffentliche Server (z. B. der Microsoft Learn MCP-Server).
custom-keys Ein gespeicherter API-Schlüssel oder -Header Schlüsselbasierte SaaS. Der Agent sieht nie das Geheimnis.
project-managed-identity Die verwaltete Identität des Projekts Dienst-zu-Dienst-Anrufe ohne Benutzerkontext.
agentic-identity Die eigene Identität des Agents Überwachung pro Agent und geringste Berechtigungen.
oauth2 Der Benutzer, der die OAuth-Autorisierung abgeschlossen hat OAuth-kompatible Dienste, einschließlich Work IQ- und Partner-MCP-Servern (z. B. Vercel).
user-entra-token Der angemeldete Microsoft Entra Benutzer Verwaltete Microsoft-Dienste, die ein zielgruppenspezifisches Entra-Token erfordern, z. B. arbeitsbereichsprivate Fabric-Daten-Agent-Endpunkte.

Sowohl oauth2 als auch user-entra-token unterstützen den Zugriff pro Benutzer, beziehen die Anmeldeinformationen jedoch auf unterschiedliche Weise. Mit diesem Vorgang oauth2schließt der Benutzer einen OAuth-Autorisierungsfluss ab, und Foundry speichert und aktualisiert die resultierenden Anmeldeinformationen. Mit user-entra-token stellt Foundry dem nachgelagerten Dienst ein audienzspezifisches Microsoft Entra-Zugriffstoken zur Verfügung, das den angemeldeten Benutzer repräsentiert. Verwenden Sie den vom Dienst erforderlichen Authentifizierungstyp.

Konfigurieren einer Verbindung für jeden Authentifizierungstyp

Registrieren Sie jede Verbindung mit azd ai connection create. Die Struktur des Befehls bleibt immer gleich; die Flags unterscheiden sich je nach Authentifizierungstyp. Verwenden Sie --kind remote-tool für MCP- und A2A-Server.

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

Schritt-für-Schritt-Anleitung: OAuth-Identitätsdurchleitung

Dieses Beispiel verbindet zwei Microsoft Entra-geschützte Tools für den benutzerspezifischen Zugriff: einen privaten Orders-MCP-Server und Work IQ. Beide verwenden die OAuth-Identitätsweitergabe, sodass jeder nachgelagerte Aufruf im Namen des Benutzers ausgeführt wird, der die Verbindung autorisiert hat.

1. Erstellen einer Verbindung für jedes Tool

# 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. Hinzufügen beider Tools zu einer Toolbox

Jedes Tool referenziert seine Verbindung anhand der ID. Dieser eine Verweis macht den entscheidenden Unterschied zwischen dem Ausführen unter einem gemeinsam genutzten Dienstkonto und dem Handeln im Namen des angemeldeten Benutzers aus. Ihr Agent benötigt weder einen Tokenbroker noch einen benutzerspezifischen Tokencache.

Dieses Beispiel erfordert @azure/ai-projects (Python) oder azure-ai-projects (TypeScript) in Version 2.3.0 oder höher.

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}")

Informationen zu JavaScript finden Sie im gepflegten Beispiel toolbox project-connection sample und im Work IQ sample. Im ersten Beispiel wird eine MCP-gestützte Toolbox erstellt, die eine Projektverbindung nutzt und einem Agent zugeordnet wird. Das zweite Beispiel zeigt, wie auf die Work IQ-Projektverbindung verwiesen wird.

3. Verbinden des Agents mit der Toolbox

Der Agent verbindet sich mit dem Single-Consumer-Endpunkt der Toolbox, der immer die Standardversion bereitstellt. Der Agent authentifiziert sich mit seiner eigenen Identität bei der Plattform. Für jedes Tool stellt Foundry Anmeldeinformationen bereit, die den Benutzer darstellen, der die OAuth-Autorisierung abgeschlossen hat. Der Agent enthält keinen toolspezifischen Authentifizierungscode.

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()
, timeout=120.0)

# 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 generiert einen Zustimmungslink, wenn ein bestimmter Benutzer ein Tool zum ersten Mal autorisieren muss. Nach der Zustimmung verwenden nachfolgende Aufrufe die Anmeldeinformationen dieses Benutzers. Der Benutzer muss das Tool möglicherweise erneut autorisieren, wenn das Aktualisierungstoken abläuft oder widerrufen wird.

Note

Nutzer eines Agenten, der OAuth-Identitätsweitergabe verwendet, benötigen im Projekt mindestens die Rolle Foundry Agent Consumer. Der Microsoft Entra Mandant des Benutzers muss dem Mandanten Ihres Foundry-Projekts entsprechen. Der mandantenübergreifende Tokenaustausch wird nicht unterstützt.

Über Passthrough hinaus: Was Ihnen eine Toolbox sonst noch bietet

Da die Authentifizierung und der Datenverkehr der Tools über die Toolbox laufen, erhalten Sie mehr als nur eine saubere Verwaltung von Identitäten:

  • Verantwortungsvolle KI-Schutzschienen. Guardrails überprüfen die Ein- und Ausgaben jedes Tools, sodass eine nicht vertrauenswürdige MCP-Antwort keine Prompt-Injection oder unsicheren Inhalte an den Agenten zurückschleusen kann.
  • Bringen Sie Ihr eigenes KI-Gateway mit. Schalten Sie Azure API Management (APIM) zur Ratenbegrenzung, Protokollierung und Durchsetzung von Netzwerkrichtlinien vor Ihre MCP-Server.
  • Versionskontrolle. Erstellen und testen Sie eine neue Toolboxversion, und höherstufen Sie sie auf die Standardeinstellung. Jeder Agent, der auf den Consumer-Endpunkt verweist, übernimmt die freigegebene Version automatisch, ohne Codeänderungen.

Verwandte Inhalte

  • Last updated on