Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Tożsamości agentów umożliwiają zaawansowane scenariusze uwierzytelniania, w których aplikacja agenta działa autonomicznie lub w imieniu użytkowników. Korzystając z tożsamości agentów w zestawie SDK uwierzytelniania Microsoft Entra ID (sidecar), można tworzyć zarówno agentów autonomicznych działających we własnym kontekście, jak i agentów interaktywnych działających w imieniu użytkowników. Aby ułatwić te scenariusze, zestaw SDK obsługuje określone parametry zapytania w celu określenia tożsamości agenta i kontekstów użytkownika.
Aby uzyskać szczegółowe wskazówki dotyczące tożsamości agentów, zobacz dokumentację platformy tożsamości agenta Microsoft.
Przegląd
Tożsamości agentów wspierają dwa podstawowe wzorce:
- Agent autonomiczny: agent działa we własnym kontekście aplikacji.
- Agent interaktywny: agent interaktywny działa w imieniu użytkownika.
Zestaw SDK akceptuje trzy opcjonalne parametry zapytania:
-
AgentIdentity- Identyfikator GUID tożsamości agenta. -
AgentUsername- Główna nazwa użytkownika (UPN) dla określonego użytkownika. -
AgentUserId- Identyfikator obiektu użytkownika (OID) dla określonego użytkownika, jako alternatywa dla nazwy UPN.
Reguły pierwszeństwa
AgentUsername i AgentUserId wzajemnie się wykluczają. Żądania, które zawierają oba parametry, nie przechodzą walidacji, jak opisano w regule 2: wzajemnej wyłączności. Podaj tylko jeden z tych parametrów na żądanie.
konfiguracja Microsoft Entra ID
Przed skonfigurowaniem tożsamości agentów w aplikacji skonfiguruj niezbędne składniki w Microsoft Entra ID. Aby zarejestrować nową aplikację w dzierżawie Microsoft Entra ID, zobacz sekcję Zarejestruj aplikację.
Wymagania wstępne dotyczące tożsamości agentów
Rejestracja aplikacji agenta:
- Zarejestruj aplikację agenta nadrzędnego w Microsoft Entra ID.
- Konfigurowanie uprawnień interfejsu API dla API podrzędnych.
- Skonfiguruj poświadczenia klienta (FIC+MSI, certyfikat lub tajne hasło).
Konfiguracja tożsamości agenta:
- Tworzenie tożsamości agenta przy użyciu strategii agenta.
- Przypisz niezbędne uprawnienia do tożsamości agenta.
Uprawnienia aplikacji:
- Przyznawanie uprawnień aplikacji w scenariuszach autonomicznych.
- Przyznawanie delegowanych uprawnień dla scenariuszy delegowania użytkowników.
- Upewnij się, że zgoda administratora jest podana tam, gdzie jest to wymagane.
Aby uzyskać szczegółowe instrukcje krok po kroku dotyczące konfigurowania tożsamości agentów w Microsoft Entra ID, zobacz dokumentację platformy tożsamości agenta Microsoft.
Reguły semantyczne
Aby pomyślnie przeprowadzić uwierzytelnianie, należy prawidłowo użyć parametrów tożsamości agenta. Poniższe reguły określają użycie parametrów AgentIdentity, AgentUsernamei AgentUserId . Postępuj zgodnie z tymi regułami, aby uniknąć błędów walidacji zwracanych przez zestaw SDK.
Reguła 1: Wymaganie dotyczące AgentIdentity
AgentUsername lub AgentUserId musi być sparowany z AgentIdentity.
W przypadku określenia AgentUsername lub AgentUserId bez AgentIdentity, żądanie zakończy się niepowodzeniem z powodu błędu weryfikacji.
# INVALID - AgentUsername without AgentIdentity
GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com
# VALID - AgentUsername with AgentIdentity
GET /AuthorizationHeader/Graph?AgentIdentity=agent-client-id&AgentUsername=user@contoso.com
Reguła 2. Wzajemne wyłączność
AgentUsername i AgentUserId są wzajemnie wykluczające się parametry.
Nie można określić jednocześnie AgentUsername i AgentUserId w tym samym żądaniu. Jeśli podasz oba parametry, żądanie zakończy się niepowodzeniem z powodu błędu weryfikacji.
# INVALID - Both AgentUsername and AgentUserId specified
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid
# VALID - Only AgentUsername
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com
# VALID - Only AgentUserId
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id
Reguła 3. Autonomiczna a interaktywna
Kombinacja parametrów określa wzorzec uwierzytelniania:
| Parametry | Wzór | Description |
|---|---|---|
AgentIdentity tylko |
Agent autonomiczny | Uzyskuje token aplikacji dla tożsamości agenta |
AgentIdentity + AgentUsername |
Agent interaktywny | Uzyskuje token użytkownika dla określonego użytkownika (według UPN) |
AgentIdentity + AgentUserId |
Agent interaktywny | Uzyskuje token użytkownika dla określonego użytkownika (według identyfikatora obiektu) |
Przykłady:
# Autonomous agent - application context
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id
# Interactive agent - user context by username
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com
# Interactive agent - user context by user ID
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id
Wzorce użycia
Dla każdego wzorca użycia kombinacja parametrów określa przepływ uwierzytelniania i typ uzyskanego tokenu.
Wzorzec 1. Agent autonomiczny
Aplikacja agenta działa niezależnie w kontekście własnej aplikacji i pobiera tokeny aplikacji.
Scenariusz: usługa przetwarzania wsadowego, która przetwarza pliki samodzielnie.
GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012
Cechy tokenu:
- Typ tokenu: token aplikacji
- Temat (
sub): identyfikator obiektu aplikacji agenta - Token utworzony dla tożsamości agenta
- Uprawnienia: uprawnienia aplikacji przypisane do tożsamości agenta
Przypadki użycia:
- Automatyczne przetwarzanie wsadowe
- Zadania w tle
- Operacje między systemami
- Zaplanowane zadania bez kontekstu użytkownika
Wzorzec 2: autonomiczny agent użytkownika (według nazwy użytkownika)
Agent jest uruchamiany w imieniu określonego użytkownika zidentyfikowanego przez UPN.
Scenariusz: Asystent sztucznej inteligencji, który działa w imieniu użytkownika w aplikacji do czatu.
GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUsername=alice@contoso.com
Cechy tokenu:
- Typ tokenu: token użytkownika
- Temat (
sub): identyfikator obiektu użytkownika - Aspekt tożsamości agenta uwzględniony w żądaniach tokenu
- Uprawnienia: uprawnienia interakcyjne ograniczone do użytkownika
Przypadki użycia:
- Aplikacje agentów interaktywnych
- Asystenci sztucznej inteligencji z delegowaniem użytkowników
- Automatyzacja w zakresie użytkownika
- Spersonalizowane przepływy pracy
Wzorzec 3: autonomiczny agent użytkownika (według identyfikatora obiektu)
Agent działa w imieniu określonego użytkownika zidentyfikowanego przez jego identyfikator obiektu.
Scenariusz: aparat przepływu pracy, który przetwarza zadania specyficzne dla użytkownika przy użyciu przechowywanych identyfikatorów użytkowników.
GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUserId=87654321-4321-4321-4321-210987654321
Cechy tokenu:
- Typ tokenu: token użytkownika
- Temat (
sub): identyfikator obiektu użytkownika - Aspekt tożsamości agenta uwzględniony w żądaniach tokenu
- Uprawnienia: uprawnienia interakcyjne ograniczone do użytkownika
Przypadki użycia:
- Długotrwałe przepływy pracy z przechowywanymi identyfikatorami użytkowników
- Operacje wsadowe wykonywane w imieniu wielu użytkowników
- Systemy korzystające z identyfikatorów obiektów na potrzeby dokumentacji użytkownika
Wzorzec 4: Agent interaktywny (działający w imieniu użytkownika wywołującego go)
Internetowy interfejs API agenta odbiera token użytkownika, weryfikuje go i wykonuje delegowane wywołania w imieniu tego użytkownika.
Scenariusz: internetowy interfejs web API działający jako agent interaktywny, weryfikując przychodzące tokeny użytkownika i wykonując delegowane wywołania do usług docelowych.
Przepływ:
- Internetowy interfejs API agenta odbiera token użytkownika z aplikacji wywołującej.
- Weryfikuje token za pośrednictwem punktu końcowego
/Validate. - Uzyskuje tokeny dla podrzędnych interfejsów API przez wywołanie
/AuthorizationHeader, używającAgentIdentityoraz nagłówka autoryzacji.
# Step 1: Validate incoming user token
GET /Validate
Authorization: Bearer <user-token>
# Step 2: Get authorization header on behalf of the user
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>
Authorization: Bearer <user-token>
Cechy tokenu:
- Typ tokenu: token użytkownika (przepływ OBO)
- Temat (
sub): identyfikator obiektu oryginalnego użytkownika - Agent działa jako pośrednik dla użytkownika
- Uprawnienia: uprawnienia interakcyjne ograniczone do użytkownika
Przypadki użycia:
- Internetowe interfejsy API, które działają jako agenty
- Usługi agenta interaktywnego
- Oprogramowanie pośredniczące oparte na agencie, które przesyła zadania do interfejsów API położonych niżej w hierarchii
- Usługi weryfikujące i przekazujące kontekst użytkownika
Wzorzec 5: Regularne żądanie (bez agenta)
Jeśli nie podasz parametrów agenta, zestaw SDK używa tożsamości tokenu przychodzącego.
Scenariusz: standardowy przepływ „w imieniu” (OBO) bez użycia tożsamości agenta.
GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>
Cechy tokenu:
- Typ tokenu: zależy od tokenu przychodzącego i konfiguracji
- Używa standardowego przepływu OBO lub przepływu poświadczeń klienta
- Brak aspektów tożsamości agenta
Przykłady kodu
W poniższych fragmentach kodu pokazano, jak zaimplementować różne wzorce tożsamości agenta przy użyciu różnych języków programowania i jak korzystać z punktów końcowych zestawu SDK. Kod pokazuje, jak obsługiwać wywołania międzyprocesowe do pakietu SDK w celu uzyskania nagłówków autoryzacyjnych dla kolejnych wywołań API.
TypeScript: agent autonomiczny
const sidecarUrl = "http://localhost:5000";
const Agent ID = "12345678-1234-1234-1234-123456789012";
async function runBatchJob() {
const response = await fetch(
`${sidecarUrl}/AuthorizationHeader/Graph?AgentIdentity=${agentId}`,
{
headers: {
'Authorization': 'Bearer system-token'
}
}
);
const { authorizationHeader } = await response.json();
// Use authorizationHeader for downstream API calls
}
Python: Agent z tożsamością użytkownika
import requests
sidecar_url = "http://localhost:5000"
agent_id = "12345678-1234-1234-1234-123456789012"
user_email = "alice@contoso.com"
response = requests.get(
f"{sidecar_url}/AuthorizationHeader/Graph",
params={
"AgentIdentity": agent_id,
"AgentUsername": user_email
},
headers={"Authorization": f"Bearer {system_token}"}
)
token = response.json()["authorizationHeader"]
TypeScript: agent interaktywny
async function delegateCall(userToken: string) {
// Validate incoming token
const validation = await fetch(
`${sidecarUrl}/Validate`,
{
headers: { 'Authorization': `Bearer ${userToken}` }
}
);
const claims = await validation.json();
// Call downstream API on behalf of user
const response = await fetch(
`${sidecarUrl}/DownstreamApi/Graph`,
{
headers: { 'Authorization': `Bearer ${userToken}` }
}
);
return await response.json();
}
Język C# z klientem HttpClient
using System.Net.Http;
var httpClient = new HttpClient();
// Autonomous agent
var autonomousUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
$"?AgentIdentity={agentClientId}";
var response = await httpClient.GetAsync(autonomousUrl);
// Delegated agent with username
var delegatedUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
$"?AgentIdentity={agentClientId}" +
$"&AgentUsername={Uri.EscapeDataString(userPrincipalName)}";
response = await httpClient.GetAsync(delegatedUrl);
// Delegated agent with user ID
var delegatedByIdUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
$"?AgentIdentity={agentClientId}" +
$"&AgentUserId={userObjectId}";
response = await httpClient.GetAsync(delegatedByIdUrl);
Scenariusze błędów
W przypadku błędnej konfiguracji parametrów tożsamości agenta lub nieprawidłowego użycia zestaw SDK zwraca błędy walidacji. W poniższych sekcjach opisano typowe scenariusze błędów i odpowiadające im odpowiedzi. Aby uzyskać więcej informacji na temat obsługi błędów, zobacz Przewodnik rozwiązywania problemów.
Brak elementu AgentIdentity z elementem AgentUsername
Żądanie:
GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com
Odpowiedź:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Bad Request",
"status": 400,
"detail": "AgentUsername requires AgentIdentity to be specified"
}
Określono zarówno agentUsername, jak i AgentUserId
Żądanie:
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid
Odpowiedź:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Bad Request",
"status": 400,
"detail": "AgentUsername and AgentUserId are mutually exclusive"
}
Nieprawidłowy format AgentUserId
Żądanie:
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=invalid-guid
Odpowiedź:
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Bad Request",
"status": 400,
"detail": "AgentUserId must be a valid GUID"
}
Najlepsze rozwiązania
- Sprawdź poprawność danych wejściowych: zawsze weryfikuj parametry tożsamości agenta przed wykonaniem żądań.
- Użyj identyfikatorów obiektów, jeśli są dostępne: identyfikatory obiektów są bardziej stabilne.
- Implementowanie prawidłowej obsługi błędów: Sprawnie obsługiwanie błędów weryfikacji tożsamości agenta.
- Bezpieczne poświadczenia agenta: Chroń identyfikatory klientów i poświadczenia tożsamości agenta.
- Operacje agenta inspekcji: Rejestrowanie i monitorowanie użycia tożsamości agenta pod kątem zabezpieczeń i zgodności.
- Przetestuj oba wzorce: zweryfikuj zarówno scenariusze autonomiczne, jak i delegowane w testach.
- Intencja dokumentu: jasno udokumentować, który wzorzec agenta jest odpowiedni dla każdego przypadku użycia.