Autoryzacja punktu końcowego agenta w Microsoft Foundry

Autoryzacja punktu końcowego agenta określa, czy podmiot wywołujący może wchodzić w interakcje z agentem w czasie wykonywania w usłudze agenta Foundry. Zamiast tego dostęp administracyjny kontroluje, kto może tworzyć, konfigurować, aktualizować lub usuwać agentów i inne zasoby w projekcie Foundry. podmiot zabezpieczeń może otrzymać uprawnienie do wywołania pojedynczego agenta bez otrzymywania uprawnień do zarządzania tym agentem lub jego projektem. Aby uzyskać dostęp administracyjny do usługi Foundry, zobacz Uwierzytelnianie i autoryzacja w usłudze Microsoft Foundry i kontrola dostępu oparta na rolach w narzędziu Foundry.

Użyj tego artykułu, aby wybrać sposób uwierzytelniania wywołujących i uzyskiwania dostępu do punktu końcowego agenta. Aby zastosować te ustawienia, zobacz Konfigurowanie autoryzacji punktu końcowego agenta. Aby dowiedzieć się, jak dostęp do punktu końcowego wiąże się z tożsamościami, których agent używa do uzyskiwania dostępu do narzędzi i zasobów, zobacz Tożsamość i dostęp w usłudze agenta.

Granica dostępu endpointu

Punkt końcowy agenta to stabilny adres URL używany przez klientów i kanały do wywoływania agenta. Punkt końcowy może obsługiwać wiele protokołów, ale jego konfiguracja autoryzacji ma zastosowanie na granicy między wywołującym a agentem.

Autoryzacja na tej granicy odpowiada na dwa pytania:

  • Jaka tożsamość lub zaufany kanał reprezentuje żądanie?
  • Jakie uprawnienie zezwala tej tożsamości lub temu kanałowi na wywoływanie agenta?

Porównaj schematy autoryzacji punktu końcowego

Schemat autoryzacji punktu końcowego definiuje sposób weryfikacji żądania przychodzącego przez usługę Foundry i określa, czy podmiot wywołujący może wchodzić w interakcję z agentem. W punkcie końcowym można skonfigurować wiele schematów uwierzytelniania. Na przykład punkt końcowy może akceptować zarówno klientów bezpośrednich z autoryzacją RBAC Azure, jak i klientów bezpośrednich autoryzowanych przez blueprint agenta oraz schemat Bot Service dla Microsoft Teams lub Microsoft 365.

Scheme Sposób decydowania o dostępie Typowe użycie
AzureRbac lub alias Entra1 Obiekt wywołujący przedstawia token zasobu Foundry, a Azure kontrola dostępu oparta na rolach określa, czy reprezentowany podmiot zabezpieczeń może uzyskać dostęp do agenta. Aplikacje, zestawy SDK, klienci REST, narzędzia deweloperskie i wywołania obciążeń roboczych korzystające z dostępu do rozwiązania Foundry.
AgentBlueprint (wersja zapoznawcza) Obiekt wywołujący przedstawia token planu agenta agenta, a punkt końcowy stosuje reguły weryfikacji tokenów schematu. Aplikacje, które wymagają dostępu poszczególnych agentów bez udzielania podmiotowi wywołującemu uprawnień RBAC Foundry.
BotServiceRbac 2 Azure Bot Service weryfikuje żądanie kanału, a Azure RBAC określa, czy zalogowany użytkownik ma dostęp. kanały Microsoft Teams i Microsoft 365, w których każdy użytkownik potrzebuje odpowiednich uprawnień Azure.
BotServiceTenant 2 Azure Bot Service weryfikuje żądanie kanału i ogranicza dostęp do zalogowanych użytkowników w skonfigurowanym tenantcie. Kanały Microsoft Teams i Microsoft 365 przeznaczone do dostępu w całej organizacji.
BotService 2 Azure Bot Service weryfikuje żądanie kanału bez dodatkowej reguły autoryzacji użytkownika. Tylko zgodność ze starszymi wersjami. W przypadku nowych agentów użyj polecenia BotServiceRbac lub BotServiceTenant.

1AzureRbac to jest bieżąca nazwa istniejącego Entra schematu autoryzacji. Nowa nazwa odróżnia jego zachowanie autoryzacji Azure RBAC od innych schematów, które również używają uwierzytelniania Microsoft Entra. Istniejące konfiguracje, które używają Entra, pozostają obsługiwane, ale nie konfiguruj obu aliasów na tym samym punkcie końcowym.

2 Można skonfigurować naraz tylko jeden z elementów BotService, BotServiceRbac i BotServiceTenant.

Klucze interfejsu API nie są obsługiwane w przypadku punktów końcowych agenta. Skonfiguruj schematy autoryzacji w punkcie końcowym agenta i przypisz wszystkie wymagane role Azure w zakresie projektu lub agenta.

Microsoft Entra dostęp do punktu końcowego

Zarówno AzureRbac, jak i AgentBlueprint, używają Microsoft Entra do uwierzytelniania wywołującego. Różnią się one zasobem docelowym tokenu oraz tym, jak punkt końcowy autoryzuje dostęp po uwierzytelnieniu. Token dostępu Microsoft Entra zawiera roszczenie „aud” (aud), które identyfikuje zasób, dla którego wystawiono token. Każdy schemat akceptuje inną grupę odbiorców tokenów i stosuje inną regułę autoryzacji:

  • AzureRbac akceptuje tokeny wystawione dla zasobu Foundry (https://ai.azure.com) i stosuje kontrolę dostępu opartą na rolach platformy Azure.
  • AgentBlueprint akceptuje tokeny wystawione dla schematu agenta pojedynczego agenta i stosuje reguły sprawdzania poprawności tokenów skonfigurowane w tym schemacie.

Oba schematy można skonfigurować w tym samym punkcie końcowym. Odbiorca tokenu żądania określa, który skonfigurowany schemat może autoryzować żądanie.

schemat RBAC platformy Azure

Schemat URI AzureRbac jest domyślny dla punktu końcowego agenta. Klient żąda tokenu dla zasobu Foundry, który jest identyfikowany przez https://ai.azure.com. Wywołujący musi również mieć uprawnienie Microsoft.CognitiveServices/accounts/AIServices/endpoints/interact/action w projekcie Foundry lub w zakresie poszczególnych agentów. Foundry Agent Consumer jest zalecaną wbudowaną rolą o najniższych uprawnieniach dla tego uprawnienia. Użytkownik usługi Foundry również obejmuje to uprawnienie, ale zapewnia dodatkowe uprawnienia do tworzenia agentów i zarządzania nimi w projekcie.

Important

Niedawno zmieniono nazwy ról RBAC w usłudze Foundry. Użytkownik Foundry, właściciel Foundry, właściciel konta Foundry i menedżer projektu Foundry były wcześniej nazywane odpowiednio użytkownikiem Azure AI, właścicielem Azure AI, właścicielem konta Azure AI i menedżerem projektu Azure AI. Poprzednie nazwy mogą być nadal widoczne w niektórych miejscach, podczas gdy zmiana nazwy jest wdrażana. Identyfikatory ról i uprawnienia podstawowe są niezmienione przez zmianę nazwy.

Użyj przypisania zakresu agenta, gdy podmiot powinien wywoływać jednego agenta bez uzyskiwania szerszego dostępu do projektu. Przypisania ról zakresu agenta są oceniane pod kątem dostępu do punktu końcowego agenta i nie udzielają szerszych uprawnień płaszczyzny sterowania ani zarządzania.

Poprzednia Entra nazwa schematu ma takie samo zachowanie w czasie wykonywania jak AzureRbac. Użyj polecenia AzureRbac dla nowych konfiguracji i zachowaj Entra tylko wtedy, gdy potrzebna jest zgodność z istniejącą konfiguracją lub biblioteką klienta.

Schemat planu agenta (wersja zapoznawcza)

Schemat AgentBlueprint akceptuje token wystawiony dla szablonu danego agenta zamiast współdzielonego zasobu Foundry. Autoryzuje bezpośredni dostęp w czasie wykonywania bez konieczności posiadania roli podmiotu zabezpieczeń korzystającego z usługi Foundry.

Delegowany klient loguje użytkownika i żąda uprawnień uwidocznionych przez rejestrację aplikacji planu agenta. Domyślnie w pełni kwalifikowany zakres delegowany to:

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

Identyfikator api://<agent-blueprint-client-id> URI zasobu i access_agent nazwa uprawnień są wartościami domyślnymi, a nie stałymi wartościami. Jeśli dostosujesz jedną z tych dwóch wartości w rejestracji aplikacji schematu agenta, klient zażąda skonfigurowanego w pełni kwalifikowanego zakresu.

Wynikowy token reprezentuje zalogowanego użytkownika, identyfikuje aplikację kliencką i jest przeznaczony dla szablonu agenta. Foundry wstępnie autoryzuje obsługiwanych klientów własnych, takich jak portal Foundry, interfejs wiersza polecenia i środowisko Visual Studio Code, podczas tworzenia lub aktualizowania agenta. W przypadku klienta będącego własnością klienta skonfiguruj wstępną autoryzację lub uzyskaj zgodę użytkownika lub administratora.

Aplikacja poufna może zamiast tego zażądać tokenu tylko dla aplikacji dla odbiorcy planu agenta przy użyciu polecenia /.default. W przypadku tokenów tylko dla aplikacji AgentBlueprint schemat obecnie wymaga niepustej listy token_validation_rules.allowed_clients zawierającej identyfikator aplikacji obiektu wywołującego. Jeśli reguła zostanie pominięta lub nie zawiera wywołującego, autoryzacja zostanie odrzucona. Ta lista dozwolonych klientów jest obecnie obsługiwanym mechanizmem autoryzacji tylko dla aplikacji i nie wymaga roli aplikacji.

Autoryzacja uzyskiwania tokenu schematu agenta jest oddzielona od autoryzacji punktu końcowego. Żądanie musi nadal spełniać reguły weryfikacji tokenów punktu końcowego.

Reguły walidacji tokenu

Po zweryfikowaniu tokenu przez Microsoft Entra schemat AgentBlueprint może ograniczyć zaakceptowane grupy odbiorców, dzierżawy, aplikacje klienckie, podmioty zabezpieczeń i delegowane uprawnienia. Usługa dostarcza odbiorców docelowych, dzierżawców i domyślne ustawienia uprawnień delegowanych dla szablonu agenta bazowego, podczas gdy jawne reguły umożliwiają zawężenie dostępu dla określonego agenta.

W przypadku tokenów delegowanych autoryzacja wstępna lub zgoda steruje tym, czy klient może uzyskać token, podczas gdy reguły weryfikacji tokenu kontrolują, czy punkt końcowy go akceptuje. Możesz pominąć allowed_clients w przypadku tokenów delegowanych, jeśli nie potrzebujesz dodatkowego ograniczenia dla klienta delegowanego. W przypadku tokenów tylko dla aplikacji wymagana niepusta lista dozwolonych klientów określa, które aplikacje mogą wywoływać agenta po weryfikacji tokenu.

Aby uzyskać informacje o właściwościach konfiguracji, wartościach domyślnych i zachowaniu pustej listy, zobacz Konfigurowanie reguł walidacji tokenu.

Dostęp deweloperski do tworzenia, konfigurowania lub testowania agentów nie ustanawia automatycznie dostępu do szablonu agenta użytkownika końcowego. Z drugiej strony autoryzowanie klienta dla schematu agenta nie przyznaje temu klientowi dostępu do zarządzania projektem Foundry.

Autoryzacja standardowa

Rutynowa wysyłka używa tokenu dla grupy odbiorców Foundry i nie obsługuje schematu podglądu AgentBlueprint. Zachowaj AzureRbac lub jego alias Entra skonfigurowany dla punktu końcowego, który wywołuje procedura.

autoryzacja kanału Bot Service

Agenty opublikowane w Microsoft Teams lub Microsoft 365 używają Activity Protocol i schematu autoryzacji Azure Bot Service. Przepływ publikowania zwykle konfiguruje odpowiedni schemat. BotServiceRbac i BotServiceTenant wyświetlają monit logowania w konwersacji, aby użytkownik mógł uwierzytelnić się przed rozpoczęciem interakcji z agentem.

  • UżyjBotServiceRbac, gdy każdy użytkownik potrzebuje odpowiedniego uprawnienia Azure.
  • Użyj BotServiceTenant, gdy użytkownicy w skonfigurowanej dzierżawie mogą uzyskiwać dostęp do agenta bez przypisań RBAC usługi Foundry.
  • Użyj BotService tylko w przypadku zgodności wstecznej. Nie stosuje dodatkowej reguły autoryzacji użytkownika.

Kiedy jest stosowana kontrola dostępu oparta na rolach platformy Azure

Schematy AzureRbac i BotServiceRbac stosują kontrolę dostępu opartą na rolach na platformie Azure. Inne mechanizmy stosują inną regułę autoryzacji.

Configuration Czy wymagana jest kontrola dostępu oparta na rolach Azure? Reguła autoryzacji
AzureRbac lub jego alias Entra Yes Delegowane klienty muszą być autoryzowane, aby zażądać odpowiedniego uprawnienia Foundry. Podmiot wywołujący przedstawia następnie token dla odbiorcy Foundry i musi mieć rolę Azure, która zezwala na dostęp do agenta.
AgentBlueprint No Klienci delegowani muszą być autoryzowani do żądania skonfigurowanego uprawnienia. Obiekt wywołujący przedstawia następnie token dla odbiorcy szablonu agenta, który musi spełniać reguły weryfikacji schematu.
BotServiceRbac Yes Zalogowany użytkownik musi mieć rolę Azure, która zezwala na dostęp do agenta.
BotServiceTenant No Zalogowany użytkownik musi znajdować się w skonfigurowanym dzierżawcy. Ta reguła jest stałą regułą dzierżawcy, a nie regułą z możliwością dostosowywania.
BotService No Po Azure Bot Service zweryfikowaniu żądania kanału nie jest stosowana żadna dodatkowa reguła autoryzacji użytkownika.

Treści powiązane

  • Ostatnia aktualizacja o