Agent2Agent(A2A)-Authentifizierung

Das Agent2Agent (A2A)-Protokoll ermöglicht Es Ihren Agents, andere Agents aufzurufen. Die meisten A2A-Endpunkte erfordern eine Authentifizierung für den Zugriff auf den Endpunkt und den zugrunde liegenden Dienst. Durch die Konfiguration der Authentifizierung wird sichergestellt, dass nur autorisierte Benutzer Ihre A2A-Tools im Foundry Agent Service aufrufen können.

In diesem Artikel werden die für A2A-Verbindungen verfügbaren Authentifizierungsmethoden erläutert, und Sie können den richtigen Ansatz für Ihr Szenario auswählen.

Authentifizierungsszenarien

Im Allgemeinen gibt es zwei Authentifizierungsszenarien:

• Freigegebene Authentifizierung: Jeder Benutzer Ihres Agents verwendet dieselbe Identität, um sich beim A2A-Endpunkt zu authentifizieren. Der einzelne Benutzerkontext bleibt nicht erhalten. Dieser Ansatz ist ideal, wenn alle Benutzer über dieselbe Zugriffsebene verfügen sollten. Wenn Sie beispielsweise einen Chat-Agent zum Abrufen von Informationen aus Azure Cosmos DB für Ihre Organisation erstellen, möchten Sie möglicherweise, dass jeder Benutzer auf denselben freigegebenen Container zugreifen kann, ohne dass eine individuelle Anmeldung erforderlich ist.
• Individuelle Authentifizierung: Jeder Benutzer Ihres Agents authentifiziert sich mit einem eigenen Konto, sodass sein Benutzerkontext über Interaktionen hinweg beibehalten wird. Dieser Ansatz ist unerlässlich, wenn Aktionen auf die Berechtigungen des Benutzers abgegrenzt werden sollen. Wenn Sie z. B. einen Codierungs-Agent erstellen, der Commits abruft und Anforderungen von GitHub abruft, möchten Sie, dass sich jeder Entwickler mit einem eigenen GitHub Konto anmelden kann, damit nur Repositorys angezeigt werden, auf die er Zugriff hat.

Voraussetzungen

Bevor Sie eine Authentifizierungsmethode auswählen, benötigen Sie Folgendes:

• Zugriff auf das Foundry-Portal und ein Projekt. Wenn Sie nicht über eines verfügen, lesen Sie " Erstellen von Projekten in Foundry".
• Für Ihr Projekt benötigen Sie die Rolle Azure AI User oder höher. Diese Rolle gewährt Berechtigungen zum Erstellen von Projektverbindungen und zum Konfigurieren von Agents. Ausführliche Informationen finden Sie unter Rollenbasierte Zugriffssteuerung im Foundry-Portal.
• Die A2A-Endpunkt-URL, mit der Sie eine Verbindung herstellen möchten. Wenden Sie sich an den Endpunktherausgeber, um zu bestätigen, welche Authentifizierungsmethoden der Endpunkt unterstützt.
• Anmeldeinformationen für die ausgewählte Authentifizierungsmethode:
  • Schlüsselbasiert: Ein API-Schlüssel, ein persönliches Zugriffstoken (PAT) oder ein anderes geheimes Token vom Endpunktherausgeber.
  • Microsoft Entra authentication: Rollenzuweisungen für die Agentidentität oder die vom Projekt verwaltete Identität für den zugrunde liegenden Dienst. Die spezifischen Rollen hängen vom Dienst ab (z. B. Cosmos DB Data Reader für Azure Cosmos DB).

Auswählen einer Authentifizierungsmethode

Die gewählte Authentifizierungsmethode hängt davon ab, ob Sie freigegebenen oder individuellen Benutzerkontext benötigen und welche Authentifizierungsprotokolle der A2A-Endpunkt unterstützt.

Verwenden Sie die folgende Tabelle, um die richtige Methode für Ihr Szenario auszuwählen:

Unterstützte Authentifizierungsmethoden

In der folgenden Tabelle sind die für A2A-Verbindungen verfügbaren Authentifizierungsmethoden zusammengefasst:

Schlüsselbasierte Authentifizierung

Verwenden Sie die schlüsselbasierte Authentifizierung, wenn der A2A-Endpunkt einen API-Schlüssel, ein persönliches Zugriffstoken (PAT) oder eine andere geheime Anmeldeinformationen akzeptiert. Um die Sicherheit zu verbessern, speichern Sie geteilte Anmeldeinformationen in einer Projektverbindung, anstatt sie zur Laufzeit zu übergeben.

Wenn Sie Ihren A2A-Endpunkt mit einem Agent im Foundry-Portal verbinden, erstellt Foundry eine Projektverbindung für Sie. Geben Sie den Anmeldeinformationsnamen (den HTTP-Headernamen) und den Anmeldeinformationswert (den Headerwert) an. Das Format hängt davon ab, was der Endpunkt erwartet.

Allgemeine Anmeldeinformationsformate:

Wenn der Agent den A2A-Endpunkt aufruft, ruft der Agentendienst die Anmeldeinformationen aus der Projektverbindung ab und fügt sie den Anforderungsheadern hinzu.

Bewährte Sicherheitsmethoden für die schlüsselbasierte Authentifizierung

• Verwenden Sie Anmeldeinformationen mit minimalen Berechtigungen: Fordern Sie nur die minimalen Berechtigungen an, die für die Aufgaben des Agenten erforderlich sind.
• Drehen Sie Token regelmäßig: Legen Sie eine Erinnerung fest, um Token neu zu generieren, bevor sie ablaufen.
• Einschränken des Projektzugriffs: Einschränken, wer auf Projekte zugreifen kann, die freigegebene geheime Schlüssel enthalten.
• Audit-Anmeldeinformationsverwendung: Überwachen Sie den Zugriff auf die Projektverbindung in Ihren Azure-Aktivitätsprotokollen.

Microsoft Entra ID Authentifizierung

Verwenden Sie Microsoft Entra ID Authentifizierung, wenn der A2A-Endpunkt und der zugrunde liegende Dienst Microsoft Entra ID Token akzeptieren. Diese Methode beseitigt die Notwendigkeit, geheime Schlüssel zu verwalten, da Azure tokenerfassung und -erneuerung automatisch verarbeitet.

Agentidentität

Verwenden Sie die verwaltete Identität Ihres Agents, um sich mit A2A-Endpunkten zu authentifizieren, die Microsoft Entra ID Authentifizierung unterstützen. Wenn Sie einen Agent im Agentdienst erstellen, empfängt der Agent automatisch eine verwaltete Identität.

Identitätslebenszyklus:

• Vor der Veröffentlichung: Alle Agents im selben Projekt haben eine gemeinsame Identität. Dies vereinfacht die Entwicklung und Tests.
• Nach der Veröffentlichung: Jeder veröffentlichte Agent erhält eine eindeutige Identität. Dies bietet Isolation und ermöglicht eine präzise Zugriffssteuerung.

Weitere Informationen zum Lebenszyklus der Agentidentität finden Sie unter Agent-Identitätskonzepte in Microsoft Foundry.

So konfigurieren Sie die Agentidentitätsauthentifizierung:

1. Identifizieren Sie den zugrunde liegenden Dienst, der den A2A-Endpunkt unterstützt (z. B. Azure Cosmos DB oder Azure Storage).
2. Weisen Sie der Agentidentität für diesen Dienst die erforderlichen Rollen zu. Die spezifischen Rollen hängen vom Dienst und den Vorgängen ab, die Ihr Agent ausführen muss.
3. Konfigurieren Sie die A2A-Verbindung, um die Identitätsauthentifizierung des Agenten zu verwenden.

Wenn der Agent den A2A-Endpunkt aufruft, verwendet der Agentdienst die Agentidentität, um ein Autorisierungstoken von Microsoft Entra ID anzufordern und in die Anforderung einzuschließt.

Verwaltete Identität des Foundry-Projekts

Verwenden Sie die verwaltete Identität Ihres Foundry-Projekts, um sich bei A2A-Endpunkten zu authentifizieren. Diese Option ist nützlich, wenn alle Agents in einem Projekt dieselbe Identität für den Zugriff auf Ressourcen gemeinsam nutzen sollen.

So konfigurieren Sie die vom Projekt verwaltete Identitätsauthentifizierung:

1. Identifizieren Sie den zugrunde liegenden Dienst, der den A2A-Endpunkt unterstützt.
2. Weisen Sie der verwalteten Identität des Projekts die erforderlichen Rollen für diesen Dienst zu.
3. Konfigurieren Sie die A2A-Verbindung für die Verwendung der vom Projekt verwalteten Identitätsauthentifizierung.

Wenn der Agent den A2A-Endpunkt aufruft, verwendet der Agentdienst die verwaltete Identität des Projekts, um ein Autorisierungstoken von Microsoft Entra ID anzufordern und in die Anforderung einzuschließt.

OAuth-Identitätsdurchleitung

Der OAuth-Identitätspassthrough ermöglicht es Ihrem Agenten, im Auftrag einzelner Benutzer zu handeln. Verwenden Sie diese Methode, wenn Aktionen auf die Berechtigungen der einzelnen Benutzer festgelegt werden sollen, z. B. den Zugriff auf ihre persönlichen Dateien, Repositorys oder andere geschützte Ressourcen.

OAuth Identity Passthrough funktioniert mit Microsoft und nicht Microsoft A2A-Endpunkten, die OAuth 2.0 unterstützen, einschließlich Diensten, die Microsoft Entra ID verwenden.

Funktionsweise der OAuth-Identitätsweiterleitung

1. Erste Interaktion: Wenn ein Benutzer zum ersten Mal mit Ihrem Agent interagiert, generiert der Agentdienst einen Zustimmungslink.
2. Zustimmung des Benutzers: Der Benutzer öffnet den Link, meldet sich beim zugrunde liegenden Dienst an und autorisiert den Agent, auf seine Daten zuzugreifen.
3. Tokenspeicher: Der Agentdienst speichert die OAuth-Token des Benutzers sicher (Zugriffstoken und Aktualisierungstoken). Diese Token sind auf diese bestimmte Benutzer- und Agent-Kombination zugeschnitten.
4. Nachfolgende Anforderungen: Wenn der Agent den A2A-Endpunkt aufruft, enthält der Agentdienst das Zugriffstoken des Benutzers in der Anforderung. Wenn das Zugriffstoken abläuft, verwendet der Agentdienst das Aktualisierungstoken, um ein neues Token abzurufen.

OAuth-Tokentypen

OAuth verwendet zwei Arten von Token:

OAuth-Bereiche definieren, worauf der Agent im Namen des Benutzers zugreifen und was er tun kann. Die Bereiche werden angegeben, wenn Sie die Verbindung konfigurieren und dem Benutzer während des Zustimmungsflusses angezeigt werden. Weitere Informationen zu OAuth finden Sie in der sicherheitsdokumentation Microsoft.

Verwaltetes OAuth im Vergleich zu benutzerdefiniertem OAuth

Der Agentdienst unterstützt zwei OAuth-Konfigurationsoptionen:

Geben Sie die folgenden Informationen an, um benutzerdefinierte OAuth zu konfigurieren:

• Client-ID: Die Anwendungs-ID aus Ihrer OAuth-App-Registrierung.
• Geheimer Clientschlüssel (falls erforderlich): Der geheime Schlüssel, der Ihrer App-Registrierung zugeordnet ist.
• Autorisierungs-URL: Der Endpunkt, an dem Benutzer den Zugriff autorisieren.
• Token-URL: Der Endpunkt, an dem der Agentdienst den Autorisierungscode für Token austauscht.
• Aktualisierungs-URL: Der Endpunkt zum Aktualisieren abgelaufener Zugriffstoken.
• Scopes: Die Berechtigungen, die Ihr Agent benötigt (z. B. repo für GitHub oder Files.Read für Microsoft Graph).

Nicht authentifizierter Zugriff

Verwenden Sie nicht authentifizierten Zugriff nur, wenn der A2A-Endpunkt öffentlich zugänglich ist und keine Authentifizierung erfordert. Diese Option ist zwar selten in Produktionsszenarien, kann aber angemessen sein für:

• Öffentliche APIs, die keine Authentifizierung erfordern
• Interne Entwicklungs- oder Testendpunkte
• Endpunkte, die durch Sicherheit auf Netzwerkebene geschützt sind (z. B. private Endpunkte) anstelle der Authentifizierung

Einrichten der Authentifizierung für eine A2A-Verbindung

Führen Sie die folgenden Schritte aus, um die Authentifizierung für eine A2A-Verbindung zu konfigurieren:

1. Identifizieren Sie den A2A-Endpunkt und unterstützte Authentifizierungsmethoden. Wenden Sie sich an den Endpunktherausgeber, oder überprüfen Sie die Endpunktdokumentation, um zu ermitteln, welche Authentifizierungsmethoden unterstützt werden.

2. Sammeln Sie die erforderlichen Anmeldeinformationen basierend auf Ihrer gewählten Authentifizierungsmethode:

   • Schlüsselbasiert: Abrufen des API-Schlüssels oder -Tokens vom Endpunktherausgeber.
   • Microsoft Entra ID: Identifizieren Sie die erforderlichen Rollenzuweisungen für den zugrunde liegenden Dienst.
   • OAuth: Ermitteln Sie, ob verwaltetes OAuth verfügbar ist, oder sammeln Sie Ihre benutzerdefinierten OAuth-App-Registrierungsdetails.

3. Erstellen Sie eine Projektverbindung im Foundry-Portal. Die Verbindung speichert die A2A-Endpunkt-URL, Authentifizierungsmethode und Anmeldeinformationen.

   • Allgemeine Verbindungsanleitungen finden Sie unter Hinzufügen einer neuen Verbindung zu Ihrem Projekt.
   • Für A2A-spezifische Konfigurationen, siehe Hinzufügen eines A2A-Agent-Endpunkts zum Foundry-Agent-Dienst.

4. Rollenzuweisungen konfigurieren (nur Microsoft Entra ID Authentifizierung). Weisen Sie die erforderlichen Rollen der Agent-Identität oder der projektverwalteten Identität auf dem zugrunde liegenden Dienst zu.

5. Fügen Sie Ihrem Agenten das A2A-Tool hinzu. Verweisen Sie auf die von Ihnen erstellte Projektverbindung, und konfigurieren Sie, welche Tools vom A2A-Endpunkt aus vom Agent aufgerufen werden können.

Überprüfen der Authentifizierung

Nachdem Sie die Authentifizierung konfiguriert haben, testen Sie die Verbindung, um zu bestätigen, dass sie ordnungsgemäß funktioniert.

Validieren von schlüsselbasierter oder Microsoft Entra ID-Authentifizierung

1. Öffnen Sie Ihren Agent im Foundry-Portal.
2. Starten Sie eine Unterhaltung, und lösen Sie eine Aktion aus, die das A2A-Tool aufruft.
3. Bestätigen Sie, dass der Toolaufruf erfolgreich abgeschlossen ist. Wenn der Anruf fehlschlägt, überprüfen Sie die Fehlermeldung, und lesen Sie die Problembehandlung.

Überprüfung der OAuth-Identitätsdurchleitung

1. Öffnen Sie Ihren Agent im Foundry-Portal mit einem Testbenutzerkonto, das noch nicht zugestimmt hat.
2. Starten Sie eine Unterhaltung, und lösen Sie eine Aktion aus, die das A2A-Tool aufruft.
3. Vergewissern Sie sich, dass ein Zustimmungslink in der Antwort des Agenten angezeigt wird.
4. Öffnen Sie den Zustimmungslink, und melden Sie sich mit den Anmeldeinformationen des Testbenutzers an.
5. Autorisieren Sie die angeforderten Berechtigungen.
6. Kehren Sie zum Agent zurück, und lösen Sie das A2A-Tool erneut aus.
7. Vergewissern Sie sich, dass der Toolaufruf erfolgreich abgeschlossen ist, indem Sie die Anmeldeinformationen des Testbenutzers verwenden.
8. (Optional) Testen Sie mit einem anderen Benutzerkonto, um zu bestätigen, dass die Zustimmungsflüsse für mehrere Benutzer funktionieren.

Problembehandlung

Verwenden Sie die folgende Tabelle, um häufige Authentifizierungsprobleme zu diagnostizieren und zu beheben:

Verwandte Inhalte

• Fügen Sie einen A2A-Agent-Endpunkt zum Foundry Agent Service hinzu: Schrittweise Anleitung zum Konfigurieren eines A2A-Tools für Ihren Agent.
• Agent-Identitätskonzepte in Microsoft Foundry: Erfahren Sie, wie Agentidentitäten und deren Lebenszyklus funktionieren.
• Role-basierte Zugriffssteuerung für Microsoft Foundry: Grundlegendes zu den in Foundry verfügbaren Rollen und Berechtigungen.
• Fügen Sie ihrem Projekt eine neue Verbindung hinzu: Allgemeine Anleitungen zum Erstellen von Projektverbindungen.