Jak działa uwierzytelnianie w zestawie narzędzi Microsoft Foundry

Uwierzytelnianie Toolbox w usłudze Microsoft Foundry określa, jak narzędzia uwierzytelniają się w usługach docelowych. Ustawienia uwierzytelniania są konfigurowane na połączeniach projektu, co umożliwia agentom używanie dostępu anonimowego, poświadczeń udostępnionych, tożsamości usługi lub tożsamości zalogowanego użytkownika bez implementowania logiki uwierzytelniania w kodzie agenta.

W tym artykule wyjaśniono, jak działa uwierzytelnianie w Toolbox, oraz pokazano, jak skonfigurować przekazywanie tożsamości OAuth dla prywatnego serwera MCP i Work IQ, z zachowaniem uprawnień i granic dostępu każdego użytkownika.

W przypadku delegowania przez użytkownika z użyciem MCP i innych narzędzi połącz te narzędzia za pośrednictwem zestawu narzędzi Foundry. Podczas dodawania tego zestawu narzędzi do agenta hostowanego przez Microsoft Agent Framework użyj FoundryToolbox w języku Python lub AddFoundryToolboxes w środowisku .NET. Zobacz Korzystanie z zestawu narzędzi z hostowanym agentem.

Zestaw narzędzi centralizuje uwierzytelnianie dla połączenia. Uwierzytelnianie jest właściwością połączenia, a nie kodem w agencie. Po nawiązaniu połączenia z narzędziem wybierasz typ uwierzytelniania, a narzędzie Foundry obsługuje pozyskiwanie tokenów, wymianę, odświeżanie i iniekcję po stronie usługi. Kod agenta pozostaje skoncentrowany na logice biznesowej, a nie na przepływach uwierzytelniania.

Dlaczego uwierzytelnianie poszczególnych użytkowników jest trudne do samodzielnego skompilowania

Jeśli samodzielnie konfigurujesz dostęp dla poszczególnych użytkowników do narzędzi chronionych przez Microsoft Entra, bierzesz na siebie implementację mechanizmów o kluczowym znaczeniu dla bezpieczeństwa, w których łatwo o trudne do wychwycenia błędy:

  1. Samodzielnie zaimplementuj izolację tokenów dla każdego użytkownika. Należy poprawnie partycjonować pamięci podręczne tokenów według użytkownika i dzierżawy. Nieprawidłowy klucz pamięci podręcznej może niepostrzeżenie ujawnić jednemu użytkownikowi dostęp do podrzędnego interfejsu API innego użytkownika — jest to błąd, który przechodzi wszystkie testy funkcjonalne.
  2. Zarządzaj zgodą i cyklem życia dla każdego użytkownika i każdego zasobu. Należy wykrywać niepowodzenia związane z uzyskaniem zgody, takie jak AADSTS65001, przeprowadzać użytkowników przez proces wyrażania zgody, odświeżać wygasłe tokeny oraz poprawnie obsługiwać ponowienia żądań po błędach 401/403 dla każdego interfejsu API w każdym tworzonym agencie.
  3. Opanuj złożoność, która rośnie liniowo wraz z liczbą narzędzi i agentów. Każde nowe narzędzie dodaje kolejny zakres, wymianę tokenów, wpis pamięci podręcznej, ścieżkę zgody, ścieżkę ponawiania prób i ścieżkę nagłówka. W miarę skalowania do setek narzędzi i tysięcy agentów ponownie odbudowujesz tę samą kruchą hydraulikę.

Dwie tożsamości w każdym wywołaniu narzędzia

W przypadku wywołań narzędzi wykonywanych przez agenta dla poszczególnych użytkowników należy odróżnić tożsamość agenta uzyskującego dostęp do zestawu narzędzi od tożsamości użytkownika używanej dalej. Zachowaj te tożsamości oddzielone między współbieżnymi użytkownikami.

  • Granica między agentem a zestawem narzędzi (ta stabilna). Agent uwierzytelnia się na platformie przy użyciu własnej tożsamości agenta. To konto kontroluje dostęp do samego zestawu narzędzi, a nie do poszczególnych narzędzi w jego ramach.
  • Granica między narzędziem a danymi (ta przypisana do użytkownika). W przypadku samego wywołania danych Foundry przekazuje usłudze zależnej poświadczenia reprezentujące zalogowanego użytkownika. W zależności od typu uwierzytelniania, te poświadczenia pochodzą z przepływu autoryzacji OAuth lub z tokenu dostępu Microsoft Entra przeznaczonego dla określonych odbiorców. Usługa podrzędna zwraca tylko to, do czego użytkownik ma dostęp, oraz respektuje jego uprawnienia i etykiety poufności.

Jak zestaw narzędzi obsługuje uwierzytelnianie

Zestaw narzędzi przenosi całe obciążenie związane z uwierzytelnianiem z agenta na połączenie:

  • Uwierzytelnianie odbywa się na poziomie połączenia, a nie agenta. Typ uwierzytelniania wybierasz tylko raz, podczas nawiązywania połączenia z narzędziem. Kod agenta pozostaje wolny od uwierzytelniania.
  • Usługa Foundry obsługuje cały przepływ. W zależności od potrzeb narzędzia Foundry przechowuje i wstrzykuje klucze API, uzyskuje poświadczenia dla tożsamości usługi, przeprowadza autoryzację OAuth lub dostarcza token dostępu Microsoft Entra przeznaczony dla określonych odbiorców. Narzędzie Foundry izoluje poświadczenia poszczególnych użytkowników od innych użytkowników.
  • Po prostu tworzysz logikę biznesową. Proces uwierzytelniania nigdy nie był czymś, co miałeś tworzyć.
Ciężar samodzielnego wykonania Co przybornik robi zamiast tego
Izolacja tokenów na użytkownika Foundry automatycznie izoluje tokeny dla każdego wywołującego. Nie ma klucza pamięci podręcznej, który można błędnie określić.
Obsługa zgody i cyklu życia dla poszczególnych użytkowników i zasobów Usługa Foundry zarządza przepływem zgody i cyklem życia tokenu dla każdego użytkownika, w tym uzyskiwanie i odświeżanie tokenów po udzieleniu wymaganej zgody.
Ponownie zaimplementowano uwierzytelnianie dla każdego narzędzia i każdego zespołu Możesz utworzyć przybornik z jego narzędziami i uwierzytelnianiem raz, a następnie użyć go ponownie w każdym agencie i środowisku uruchomieniowym.

Ustawianie typu uwierzytelniania w połączeniu

Typ uwierzytelniania należy wybrać podczas tworzenia połączenia w portalu przy użyciu interfejsu wiersza polecenia dewelopera Azure lub za pośrednictwem interfejsu API REST. Nigdy w kodzie agenta. Każdy typ uwierzytelniania określa, którego tożsamość dociera do narzędzia:

authType Czyja tożsamość trafia do narzędzia Użyj go do
none Anonim Serwery publiczne (na przykład serwer Microsoft Learn MCP).
custom-keys Zapisany klucz API lub nagłówek SaaS oparty na kluczach. Agent nigdy nie widzi sekretu.
project-managed-identity Tożsamość zarządzana projektu Wywołania między usługami bez kontekstu użytkownika.
agentic-identity Własna tożsamość agenta Audyt dla każdego agenta i zasada najmniejszych uprawnień.
oauth2 Użytkownik, który ukończy autoryzację protokołu OAuth Usługi zgodne ze standardem OAuth, w tym Work IQ i serwery MCP partnerów (na przykład Vercel).
user-entra-token Zalogowany użytkownik Microsoft Entra Usługi zarządzane firmy Microsoft, które wymagają tokenu Entra przeznaczonego dla określonego odbiorcy, takie jak prywatne punkty końcowe agenta danych Fabric dla obszaru roboczego.

Zarówno oauth2, jak i user-entra-token obsługują dostęp dla poszczególnych użytkowników, ale uzyskują poświadczenia w różny sposób. Za pomocą oauth2 użytkownik przechodzi przez proces autoryzacji OAuth, a Foundry przechowuje i odświeża uzyskane poświadczenia. Dzięki user-entra-tokenFoundry dostarcza usłudze podrzędnej token dostępu Microsoft Entra przeznaczony dla określonego odbiorcy, który reprezentuje zalogowanego użytkownika. Użyj typu uwierzytelniania wymaganego przez usługę.

Konfigurowanie połączenia dla każdego typu uwierzytelniania

Zarejestruj każde połączenie za pomocą polecenia azd ai connection create. Kształt polecenia jest zawsze taki sam; flagi różnią się w zależności od typu uwierzytelniania. Użyj --kind remote-tool w przypadku serwerów MCP i A2A.

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

Przewodnik: przekazywanie tożsamości protokołu OAuth

Ten przykład łączy dwa narzędzia chronione przez Microsoft Entra na potrzeby dostępu dla poszczególnych użytkowników: prywatny serwer MCP zamówień i Work IQ. Oba korzystają z przekazywania tożsamości OAuth, więc każde kolejne wywołanie jest wykonywane w kontekście użytkownika, który autoryzował połączenie.

1. Tworzenie połączenia dla każdego narzędzia

# 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. Dodawanie obu narzędzi do przybornika

Każde narzędzie odwołuje się do połączenia za pomocą identyfikatora. Ta jedna referencja stanowi całą różnicę między działaniem z użyciem współdzielonego konta usługi a działaniem w imieniu zalogowanego użytkownika. Agent nie potrzebuje brokera tokenów ani pamięci podręcznej tokenów dla poszczególnych użytkowników.

Ten przykład wymaga azure-ai-projects (Python) lub @azure/ai-projects (TypeScript) w wersji 2.3.0 lub nowszej.

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

Dla języka JavaScript zobacz utrzymywany przykład toolbox project-connection oraz przykład Work IQ. Pierwszy przykład tworzy zestaw narzędzi oparty na MCP, który korzysta z połączenia z projektem i dołącza go do agenta. Drugi przykład pokazuje, jak odwołać się do połączenia z projektem Work IQ.

3. Połącz agenta z zestawem narzędzi

Agent łączy się z pojedynczym punktem końcowym zestawu narzędzi dla jednego klienta, który zawsze udostępnia wersję domyślną. Agent uwierzytelnia się na platformie przy użyciu własnej tożsamości. Dla każdego narzędzia narzędzie Foundry dostarcza poświadczenia reprezentujące użytkownika, który ukończył autoryzację OAuth. Agent nie zawiera kodu uwierzytelniania dla poszczególnych narzędzi.

Same poświadczenia agenta nie wystarczą do identyfikacji poszczególnych użytkowników. Użyj FoundryToolbox w Pythonie lub AddFoundryToolboxes w .NET z integracją hostingu Foundry. Przekazuje ono bieżące żądanie x-agent-foundry-call-id hostowane, aby serwer proxy przybornika mógł rozpoznać kontekst obiektu wywołującego. Nie koduj identyfikatora wywołania ani nie używaj go ponownie w żądaniach użytkowników. Połączenie narzędzia musi również korzystać z odpowiedniego typu uwierzytelniania przypisanego użytkownikowi, a użytkownik musi mieć wymagane uprawnienia w systemach podrzędnych oraz wszelkie wymagane zgody. Informacje na temat konfiguracji hostowanej można znaleźć w artykule Korzystanie z zestawu narzędzi z hostowanym agentem.

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],
)

Narzędzie Foundry generuje link zgody przy pierwszym konieczności autoryzowania narzędzia przez określonego użytkownika. Po wyrażeniu zgody kolejne wywołania korzystają z poświadczeń tego użytkownika. Użytkownik może ponownie autoryzować narzędzie, jeśli token odświeżania wygaśnie lub zostanie odwołany.

Uwaga / Notatka

Użytkownicy agenta korzystającego z przekazywania tożsamości OAuth potrzebują co najmniej roli konsumenta agenta usługi Foundry w projekcie. Dzierżawca Microsoft Entra użytkownika musi być zgodny z dzierżawcą projektu Foundry; wymiana tokenów między dzierżawcami nie jest obsługiwana.

Poza trybem pass-through: co jeszcze daje zestaw narzędzi

Ponieważ ruch związany z uwierzytelnianiem i narzędziami przechodzi przez zestaw narzędzi, zyskujesz coś więcej niż tylko sprawne zarządzanie tożsamością:

  • Zabezpieczenia dla odpowiedzialnej sztucznej inteligencji. Mechanizmy zabezpieczające sprawdzają wszystkie dane wejściowe i wyjściowe każdego narzędzia, dzięki czemu niezaufana odpowiedź MCP nie może przemycić z powrotem do agenta ataku typu prompt injection ani niebezpiecznych treści.
  • Przynieś własną bramę sztucznej inteligencji. Umieść usługę Azure API Management (APIM) przed serwerami MCP, aby korzystać z ograniczania szybkości, rejestrowania i zasad sieciowych.
  • Wersjonowanie. Utwórz i przetestuj nową wersję zestawu narzędzi, a następnie ustaw ją jako domyślną. Każdy agent wskazujący na punkt końcowy konsumenta automatycznie korzysta z promowanej wersji, bez żadnych zmian w kodzie.

Bezpośredni dostęp klientów narzędziowych oraz dostęp pośredniczony przez agenta

Uwierzytelnianie w endpoint toolboxa jest oddzielone od uwierzytelniania do narzędzi zależnych. Klient, który łączy się bezpośrednio z toolboxem, a nie za pośrednictwem agenta usługi Foundry, nie może użyć logowania planu agenta, aby uzyskać dostęp do punktu końcowego toolboxa. Klienci bezpośredni również nie mogą używać AgentOnBehalfOfUser do wywołań narzędzi podrzędnych.

W przypadku bezpośredniego delegowania użytkownika Toolbox użyj oddzielnego logowania OAuth dla każdego narzędzia z połączeniem OAuth2. Ten przepływ jest opisany jako logowanie OAuth w konwersacji dla agentów, chociaż interfejs udostępniany przez klienta MCP nie musi być konwersacyjny. Program Foundry przechowuje i odświeża wynikowe poświadczenia poszczególnych użytkowników. To logowanie nie zastępuje uwierzytelniania klienta do samego zestawu narzędzi.

Klient musi rozpoznać interakcyjne żądanie autoryzacji, przedstawić je użytkownikowi i kontynuować po zalogowaniu. Nie zakładaj, że ogólny klient MCP lub agent korzystający z odpowiedzi automatycznie obsługuje ten przepływ. Samo skonfigurowanie OAuth2 w połączeniu nie jest wystarczające.

Te ograniczenia bezpośredniego klienta nie opisują dostępu pośredniczonego przez agenta. Gdy agent usługi Foundry uzyskuje dostęp do narzędzi za pośrednictwem przybornika, dostępne zachowanie delegowania zależy od punktu końcowego agenta i połączenia narzędzia. Zobacz Delegowanie użytkowników dla narzędzi dla modelu aktora i Konfigurowanie delegowania użytkowników pod kątem wymagań dotyczących punktów końcowych i połączeń.

Treści powiązane

  • Ostatnia aktualizacja o