Agent-Endpunktautorisierung in Microsoft Foundry

Die Agentendpunktautorisierung bestimmt, ob ein Anrufer zur Laufzeit im Foundry Agent Service mit einem Agent interagieren kann. Der Verwaltungszugriff steuert stattdessen, wer Agents und andere Ressourcen im Foundry-Projekt erstellen, konfigurieren, aktualisieren oder löschen kann. Ein Prinzipal kann einzelne Agents kontaktieren, ohne die Berechtigung zum Verwalten dieser Agents oder des zugehörigen Projekts zu erhalten. Informationen zum Zugriff auf die Foundry-Verwaltung finden Sie unter Authentifizierung und Autorisierung in Microsoft Foundry und rollenbasierte Zugriffssteuerung in Foundry.

Verwenden Sie diesen Artikel, um auszuwählen, wie Anrufer sich authentifizieren und Zugriff auf einen Agentendpunkt erhalten. Informationen zum Anwenden dieser Einstellungen finden Sie unter Konfigurieren der Agentendpunktautorisierung. Um zu verstehen, wie der Endpunktzugriff mit den Identitäten zusammenhängt, die ein Agent für Tools und Ressourcen verwendet, siehe Identität und Zugriff in Agent Service.

Endpunktzugriffsgrenze

Ein Agentendpunkt ist die stabile URL, die Clients und Kanäle zum Aufrufen eines Agents verwenden. Der Endpunkt kann mehrere Protokolle verfügbar machen, seine Autorisierungskonfiguration gilt jedoch an der Anrufer-zu-Agent-Grenze.

Die Autorisierung an dieser Grenze beantwortet zwei Fragen:

  • Welche Identität oder welcher vertrauenswürdige Kanal wird durch die Anforderung repräsentiert?
  • Welche Berechtigung ermöglicht es dieser Identität oder dem Kanal, den Agent anzurufen?

Endpunkt-Autorisierungsschemata vergleichen

Ein Endpunktautorisierungsschema definiert, wie Foundry eine eingehende Anforderung überprüft und entscheidet, ob der Anrufer mit dem Agent interagieren kann. Sie können mehrere Schemas auf einem Endpunkt konfigurieren. Ein Endpunkt kann z. B. sowohl von Azure RBAC autorisierte direkte Clients als auch von Agent-Blueprint autorisierte direkte Clients zusammen mit einem Botdienst-Schema für Microsoft Teams oder Microsoft 365 akzeptieren.

Scheme Wie der Zugriff festgelegt wird Typische Verwendung
AzureRbac oder der Entra-Alias1 Der Aufrufer legt ein Token für die Foundry-Ressource vor, und Azure RBAC bestimmt, ob der durch das Token repräsentierte Prinzipal auf den Agent zugreifen kann. Anwendungen, SDKs, REST-Clients, Entwicklertools und Workload-Aufrufer, die den Foundry-Zugriff verwenden.
AgentBlueprint (Vorschau) Der Aufrufer legt ein Token für den Agent-Blueprint des Agents vor, und der Endpunkt wendet die Tokenüberprüfungsregeln des Schemas an. Anwendungen, die individuellen Agentzugriff benötigen, ohne dem Aufrufer Foundry RBAC-Berechtigungen zu gewähren.
BotServiceRbac 2 Azure Bot Service überprüft die Kanalanforderung, und Azure RBAC bestimmt, ob der angemeldete Benutzer Zugriff hat. Microsoft Teams und Microsoft 365 Kanäle, in denen jeder Benutzer die entsprechende Azure Berechtigung benötigt.
BotServiceTenant 2 Azure Bot Service überprüft die Kanalanforderung und beschränkt den Zugriff auf angemeldete Benutzer im konfigurierten Mandanten. Microsoft Teams und Microsoft 365 Kanäle, die für den mandantenweiten Zugriff vorgesehen sind.
BotService 2 Azure Bot Service überprüft die Kanalanforderung ohne zusätzliche Benutzerautorisierungsregel. Nur zur Abwärtskompatibilität. Für neue Agents verwenden Sie BotServiceRbac oder BotServiceTenant.

1AzureRbac ist der aktuelle Name für das vorhandene Entra Autorisierungsschema. Der neue Name unterscheidet das Azure RBAC-Autorisierungsverhalten von anderen Verfahren, die ebenfalls die Microsoft Entra-Authentifizierung verwenden. Vorhandene Konfigurationen, die Entra verwenden, werden weiterhin unterstützt, aber konfigurieren Sie nicht beide Aliase auf demselben Endpunkt.

2 Sie können jeweils nur eine von BotService, BotServiceRbacund BotServiceTenant gleichzeitig konfigurieren.

API-Schlüssel werden für Agentendpunkte nicht unterstützt. Konfigurieren Sie die Autorisierungsschemas auf dem Agentendpunkt, und weisen Sie alle erforderlichen Azure Rollen im Projekt- oder Agentbereich zu.

Microsoft Entra Endpunktzugriff

Sowohl AzureRbac als auch AgentBlueprint verwenden Microsoft Entra, um Anrufer zu authentifizieren. Sie unterscheiden sich darin, auf welche Ressource das Token ausgerichtet ist und wie der Endpunkt den Zugriff nach der Authentifizierung autorisiert. Ein Microsoft Entra-Zugriffstoken enthält einen Benutzergruppenanspruch (aud), der die Ressource identifiziert, für die das Token ausgestellt wurde. Jedes Schema akzeptiert eine andere Token-Benutzergruppe und wendet eine andere Autorisierungsregel an:

  • AzureRbac akzeptiert token, die für die Foundry-Ressource (https://ai.azure.com) ausgestellt wurden und wendet Azure RBAC an.
  • AgentBlueprint akzeptiert Token, die für den Agent-Blueprint des einzelnen Agents ausgestellt wurden, und wendet Tokenüberprüfungsregeln an, die für dieses Schema konfiguriert sind.

Sie können beide Schemata auf demselben Endpunkt konfigurieren. Die Benutzergruppe des Anforderungstokens bestimmt, welches konfigurierte Schema die Anforderung autorisieren kann.

Azure RBAC-Schema

Das AzureRbac Verfahren ist die Standardeinstellung für einen Agentendpunkt. Der Client fordert ein Token für die Foundry-Ressource an, die durch https://ai.azure.comidentifiziert wird. Aufrufer müssen auch über die Microsoft.CognitiveServices/accounts/AIServices/endpoints/interact/action-Berechtigung auf Ebene des Foundry-Projekts oder einzelner Agents verfügen. Foundry Agent Consumer ist die empfohlene integrierte Rolle mit geringsten Berechtigungen für diese Berechtigung. Foundry User umfasst diese Berechtigung ebenfalls, gewährt aber zusätzliche Berechtigungen zum Erstellen und Verwalten von Agents im Projekt.

Important

Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

Verwenden Sie eine Zuweisung mit Agent-Bereich, wenn ein Prinzipal einen Agent aufrufen soll, ohne einen umfassenderen Projektzugriff zu erhalten. Rollenzuweisungen im Agentbereich werden für den Agentendpunktzugriff ausgewertet und gewähren keine umfassenderen Steuerungsebenen- oder Verwaltungsberechtigungen.

Der vorherige Entra Schemaname hat das gleiche Laufzeitverhalten wie AzureRbac. Verwenden Sie AzureRbac für neue Konfigurationen und behalten Sie Entra nur dann bei, wenn Sie Kompatibilität mit einer vorhandenen Konfiguration oder Clientbibliothek benötigen.

Agent-Blueprint-Schema (Vorschau)

Das AgentBlueprint Schema akzeptiert ein Token, das für den Agent-Blueprint des einzelnen Agents anstelle der freigegebenen Foundry-Ressource ausgestellt wurde. Er autorisiert den direkten Laufzeitzugriff, ohne dass der verbrauchende Prinzipal über eine Foundry-Rolle verfügt.

Ein delegierter Client meldet den Benutzer an und fordert eine Berechtigung an, die von der Agent-Blueprint-Anwendungsregistrierung verfügbar gemacht wird. Standardmäßig lautet der vollqualifizierte delegierte Bereich:

api://<agent-blueprint-client-id>/access_agent

Der api://<agent-blueprint-client-id> Ressourcen-URI und access_agent der Berechtigungsname sind Standardwerte, keine festen Werte. Wenn Sie einen der beiden Werte für die Registrierung der Agent-Blueprint-Anwendung anpassen, fordert der Client den konfigurierten vollqualifizierten Bereich an.

Das resultierende Token stellt den angemeldeten Benutzer dar, identifiziert die Clientanwendung und zielt auf den Agent-Blueprint ab. Foundry autorisiert unterstützte Erstanbieterclients wie das Foundry-Portal, die CLI und Visual Studio Code vorab, wenn der Agent erstellt oder aktualisiert wird. Konfigurieren Sie für einen kundeneigenen Client die Vorautorisierung, oder holen Sie die Zustimmung des Benutzers oder Administrators ein.

Eine vertrauliche Anwendung kann stattdessen ein nur-App-Token für die Agent-Blueprint-Zielgruppe anfordern, mithilfe von /.default. Für Nur-App-Token erfordert das AgentBlueprint Schema derzeit eine nichtleere token_validation_rules.allowed_clients Liste, die die Anwendungs-ID des Aufrufers enthält. Wenn die Regel ausgelassen wird oder den Aufrufer nicht enthält, wird die Autorisierung verweigert. Diese Liste zulässiger Clients ist der derzeit unterstützte Autorisierungsmechanismus für den reinen Anwendungszugriff und erfordert keine Anwendungsrolle.

Die Autorisierung zum Erwerben eines Agent-Blueprint-Tokens ist von der Endpunktautorisierung getrennt. Die Anforderung muss weiterhin die Tokenüberprüfungsregeln des Endpunkts erfüllen.

Tokenüberprüfungsregeln

Nachdem Microsoft Entra das Token überprüft hat, kann das AgentBlueprint Schema akzeptierte Zielgruppen, Mandanten, Clientanwendungen, Prinzipale und delegierte Berechtigungen einschränken. Der Dienst stellt Standardwerte für Zielgruppe, Mandant und delegierte Berechtigungen für den Backing-Agent-Blueprint bereit, während explizite Regeln den Zugriff für einen bestimmten Agent einschränken können.

Bei delegierten Token steuert die Vorautorisierung oder zustimmung, ob der Client das Token abrufen kann, während Tokenüberprüfungsregeln steuern, ob der Endpunkt es akzeptiert. Sie können delegierte Token weglassen allowed_clients , wenn Sie keine zusätzliche Einschränkung für delegierten Client benötigen. Für reine App-Token steuert die erforderliche nicht leere Client-Zulassungsliste, welche Anwendungen den Agent nach der Tokenüberprüfung aufrufen können.

Informationen zu den Konfigurationseigenschaften, Standardeinstellungen und leerem Listenverhalten finden Sie unter Konfigurieren von Tokenüberprüfungsregeln.

Der Entwicklungszugriff zum Erstellen, Konfigurieren oder Testen von Agents richtet keinen Automatischen Zugriff auf den Endbenutzer-Agent-Blueprint ein. Umgekehrt gewährt die Autorisierung eines Clients für den Agent-Blueprint diesem Client keinen Verwaltungszugriff auf das Foundry-Projekt.

Reguläre Autorisierung

Der Routineversand verwendet ein Token für die Foundry-Zielgruppe und unterstützt das Vorschauschema AgentBlueprint nicht. Lassen Sie AzureRbac oder seinen Entra-Alias für einen Endpunkt konfiguriert, den eine Routine aufruft.

Bot Service Kanalautorisierung

In Microsoft Teams oder Microsoft 365 veröffentlichte Agents verwenden das Aktivitätsprotokoll und ein Azure Bot Service Autorisierungsschema. Der Veröffentlichungsfluss konfiguriert normalerweise das entsprechende Schema. BotServiceRbac und BotServiceTenant zeigen in der Unterhaltung eine Anmeldeaufforderung an, damit sich der Benutzer authentifizieren kann, bevor er mit dem Agent interagiert.

  • Verwenden Sie BotServiceRbac, wenn jeder Benutzer die entsprechende Azure-Berechtigung benötigt.
  • Verwenden Sie BotServiceTenant, wenn Benutzer im konfigurierten Mandanten ohne einzelne Foundry RBAC-Zuordnungen auf den Agent zugreifen können.
  • Nur für Legacy-Kompatibilität verwenden BotService. Es wird keine zusätzliche Benutzerautorisierungsregel angewendet.

Wenn Azure RBAC gilt

Die AzureRbac und BotServiceRbac Schemata wenden Azure RBAC an. Andere Schemata verwenden eine andere Autorisierungsregel.

Configuration Ist Azure RBAC erforderlich? Autorisierungsregel
AzureRbac oder der Entra-Alias Yes Delegierte Clients müssen berechtigt sein, die entsprechende Foundry-Berechtigung anzufordern. Der Aufrufer legt dann ein Token für die Foundry-Zielgruppe vor und muss über eine Azure-Rolle verfügen, die den Zugriff auf den Agent ermöglicht.
AgentBlueprint No Delegierte Clients müssen berechtigt sein, die konfigurierte Berechtigung anzufordern. Der Aufrufer legt dann ein Token für die Agent-Blueprint-Zielgruppe vor, das die Validierungsregeln des Schemas erfüllen muss.
BotServiceRbac Yes Der angemeldete Benutzer muss über eine Azure Rolle verfügen, die den Zugriff auf den Agent ermöglicht.
BotServiceTenant No Der angemeldete Benutzer muss sich im konfigurierten Mandanten befinden. Diese Regel ist eine feste Mandantenregel und keine anpassbare Regel.
BotService No Nachdem der Azure Bot Service die Kanalanforderung überprüft hat, wird keine zusätzliche Benutzerautorisierungsregel angewendet.

Verwandte Inhalte

  • Zuletzt aktualisiert um