Często zadawane pytania dotyczące zestawu Microsoft Entra SDK for AgentID

Pytania ogólne

Co to jest zestaw Microsoft Entra SDK dla agentID?

Zestaw Microsoft Entra SDK for AgentID to konteneryzowana usługa internetowa, która obsługuje pozyskiwanie, walidację i zabezpieczanie wywołań interfejsu API podrzędnego. Działa jako kontener towarzyszący obok aplikacji, co umożliwia odciążanie logiki tożsamości do dedykowanej usługi. Scentralizowanie operacji tożsamości w zestawie SDK eliminuje konieczność osadzania złożonej logiki zarządzania tokenami w każdej usłudze, zmniejszając duplikację kodu i potencjalne luki w zabezpieczeniach.

Dlaczego należy używać zestawu Microsoft Entra SDK dla identyfikatora AgentID zamiast Microsoft.Identity.Web?

Funkcja	Microsoft.Identity.Web	Zestaw Microsoft Entra SDK dla identyfikatora agenta
Obsługa języków	Tylko język C# /.NET	Dowolny język (HTTP)
Wdrożenie	Biblioteka procesów	Oddzielny kontener
Pozyskiwanie tokenów	✅ Bezpośrednie MSAL.NET	✅ Za pośrednictwem interfejsu API HTTP
Buforowanie tokenów	✅Rozproszona pamięć ✅	✅Rozproszona pamięć ❌
Przepływ OBO	✅ Natywna obsługa	✅ Za pośrednictwem punktu końcowego HTTP
Poświadczenia klienta	✅ Natywna obsługa	✅ Za pośrednictwem punktu końcowego HTTP
Tożsamość zarządzana	✅ Bezpośrednia obsługa	✅ Bezpośrednia obsługa
Tożsamości agenta	✅ Za pośrednictwem rozszerzeń	✅ Parametry zapytania
Walidacja tokenu	✅ Oprogramowanie pośredniczące	✅ /Validate endpoint (Weryfikowanie punktu końcowego)
Interfejs API podrzędny	✅ IDownstreamApi	✅ /DownstreamApi punkt końcowy
Microsoft Graph	✅ Integracja z zestawem Graph SDK	⚠✔ Za pośrednictwem downstreamapi
Wydajność	⚡ Proces (najszybszy)	🔄 Obciążenie http
Configuration	`appsettings.json` i kod	`appsettings.json` zmienne środowiskowe i zmienne środowiskowe
Debugowanie	✅ Standardowe debugowanie platformy .NET	⚠✔ Debugowanie kontenera
Przeładowywanie na gorąco	✅ Ponowne ładowanie na gorąco platformy .NET	❌ Ponowne uruchamianie kontenera
Aktualizacje pakietów	📦 Pakiety NuGet	🐳 Obrazy kontenerów
Licencja	MIT	MIT

Aby uzyskać szczegółowe wskazówki, zobacz Przewodnik porównawczy .

Czy zestaw Microsoft Entra SDK dla identyfikatora agenta jest gotowy do użycia w środowisku produkcyjnym?

Tak, zestaw SDK jest gotowy do produkcji. Zapoznaj się z wersjami usługi GitHub , aby zapoznać się z najnowszymi wytycznymi dotyczącymi stanu wydania i gotowości produkcyjnej.

Czy są dostępne obrazy kontenerów?

Tak — zapoznaj się z przewodnikiem instalacji , aby uzyskać dostępne obrazy i tagi wersji.

Czy mogę uruchomić zestaw SDK poza platformą Kubernetes?

Tak — zapoznaj się z przewodnikiem instalacji , aby uzyskać instrukcje dotyczące uruchamiania zestawu SDK w narzędziu Docker Compose lub innych środowiskach kontenerów (Docker Compose, Azure Container Instances, AWS ECS/Fargate, Standalone Docker).

Jakich portów sieciowych używa zestaw SDK?

Port domyślny: 5000 (konfigurowalny)

Zestaw SDK powinien być dostępny tylko z kontenera aplikacji, nigdy nie uwidoczniony zewnętrznie.

Wdrożenie

Dowiedz się więcej o opcjach wdrażania, wymaganiach dotyczących zasobów i integracji z platformami kontenerów, takimi jak Docker Compose i Kubernetes.

Jakie są wymagania dotyczące zasobów?

Tak — zobacz Przewodnik instalacji , aby uzyskać informacje o wymaganiach dotyczących zasobów.

Czy mogę używać zestawu SDK z narzędziem Docker Compose?

Tak — zobacz przewodnik instalacji dla przykładów narzędzia Docker Compose.

Jak wdrożyć w usłudze AKS przy użyciu tożsamości zarządzanej?

Tak — postępuj zgodnie z przewodnikiem instalacji w sekcji Azure Kubernetes Service (AKS) z tożsamością zarządzaną .

Konfiguracja

Skonfiguruj ustawienia zestawu SDK, w tym poświadczenia, podrzędne interfejsy API i przesłonięcia żądań, aby odpowiadały wymaganiom wdrożenia.

Czy dostępna jest dokumentacja konfiguracji?

Tak — zobacz dokumentację konfiguracji , aby uzyskać szczegółowe opcje konfiguracji.

Czy należy używać wpisów tajnych klienta lub certyfikatów?

Preferuj certyfikaty za pośrednictwem wpisów tajnych klienta:

Bezpieczniejszy
Łatwiejsze obracanie
Zalecane przez firmę Microsoft

Najlepsze: użyj tożsamości zarządzanej na platformie Azure (nie są wymagane poświadczenia)

Aby uzyskać wskazówki, zobacz Najlepsze rozwiązania dotyczące zabezpieczeń .

Czy mogę skonfigurować wiele podrzędnych interfejsów API?

Tak. Skonfiguruj każdą z nich przy użyciu własnej sekcji:

DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
DownstreamApis__Graph__Scopes: "User.Read"

DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
DownstreamApis__MyApi__Scopes: "api://myapi/.default"

Jak przesłonić konfigurację na żądanie?

Użyj parametrów zapytania w punktach końcowych:

# Override scopes
GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read

# Request app token instead of OBO
GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true

# Override relative path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

Zobacz Dokumentację konfiguracji , aby uzyskać informacje o wszystkich opcjach.

Tożsamości agenta

Tożsamości agentów umożliwiają scenariusze, w których aplikacja agenta może działać autonomicznie lub w imieniu użytkownika z odpowiednią izolacją kontekstu i określaniem zakresu.

Co to są tożsamości agentów?

Tożsamości agenta umożliwiają scenariusze, w których aplikacja agenta działa:

Autonomicznie — we własnym kontekście aplikacji
Interactive — w imieniu użytkownika, który go nazwał

Zobacz Tożsamości agentów , aby uzyskać kompleksową dokumentację.

Kiedy należy używać trybu agenta autonomicznego?

Użyj trybu agenta autonomicznego dla:

Przetwarzanie wsadowe bez kontekstu użytkownika
Zadania w tle
Operacje między systemami
Zaplanowane zadania

Przykład:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>

Kiedy należy używać trybu agenta interaktywnego?

Użyj trybu agenta delegowanego dla:

Aplikacje agentów interaktywnych
Asystenci sztucznej inteligencji działający w imieniu użytkowników
Automatyzacja o zakresie użytkownika
Spersonalizowane przepływy pracy

Przykład:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

Dlaczego nie mogę użyć agentaUsername bez agentaIdentity?

AgentUsername jest modyfikatorem określającym, który użytkownik działa w imieniu agenta. Wymaga AgentIdentity określenia kontekstu agenta do użycia. Bez AgentIdentityparametru parametr nie ma znaczenia.

Dlaczego agentUsername i AgentUserId wykluczają się wzajemnie?

Są to dwa sposoby identyfikowania tego samego użytkownika:

AgentUsername - Główna nazwa użytkownika (UPN)
AgentUserId - Identyfikator obiektu (OID)

Umożliwianie obu tworzy niejednoznaczność. Wybierz ten, który pasuje do twojego scenariusza:

Użyj AgentUsername nazwy UPN użytkownika
Użyj AgentUserId polecenia , gdy masz identyfikator obiektu użytkownika

Użycie interfejsu API

Zestaw SDK uwidacznia kilka punktów końcowych HTTP na potrzeby uzyskiwania, walidacji i podrzędnych wywołań interfejsu API z obsługą zarówno uwierzytelnionych, jak i nieuwierzytelnionych przepływów.

Jakie punkty końcowe udostępnia zestaw SDK?

/Validate — Weryfikowanie tokenu i zwracanie oświadczeń
/AuthorizationHeader/{serviceName} - Pobieranie nagłówka autoryzacji z tokenem
/AuthorizationHeaderUnauthenticated/{serviceName} — Uzyskiwanie tokenu bez tokenu użytkownika przychodzącego
/DownstreamApi/{serviceName} - Bezpośrednie wywoływanie interfejsu API podrzędnego
/DownstreamApiUnauthenticated/{serviceName} - Wywoływanie podrzędnego interfejsu API bez tokenu przychodzącego użytkownika
/healthz - Sonda kondycji

Aby uzyskać szczegółowe informacje, zobacz Informacje o punktach końcowych .

Jaka jest różnica między uwierzytelnionymi i nieuwierzytelnionymi punktami końcowymi?

Uwierzytelnione: wymagaj tokenu elementu nośnego w Authorization nagłówku (w przypadku przepływów OBO) Nieuwierzytelnione: nie weryfikuj tokenu przychodzącego (w scenariuszach tylko dla aplikacji lub agenta)

Jak mogę zweryfikować token użytkownika?

GET /Validate
Authorization: Bearer <user-token>

Odpowiedź zawiera wszystkie oświadczenia z tokenu.

Jak uzyskać token dostępu dla podrzędnego interfejsu API?

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

Odpowiedź zawiera nagłówek autoryzacji gotowy do użycia z podrzędnym interfejsem API.

Czy mogę zastąpić metodę HTTP lub ścieżkę na żądanie?

Tak, używając parametrów zapytania:

# Override method
GET /DownstreamApi/Graph?optionsOverride.HttpMethod=POST

# Override path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

Buforowanie tokenów

Zestaw SDK automatycznie buforuje tokeny w pamięci, aby zoptymalizować wydajność i zmniejszyć nadmiarowe żądania pozyskiwania tokenów.

Czy tokeny pamięci podręcznej zestawu SDK?

Tak — zestaw SDK domyślnie buforuje tokeny w pamięci.

Jak długo są buforowane tokeny?

Tokeny są buforowane do momentu bliskiego wygaśnięcia, a następnie automatycznie odświeżone. Dokładny czas trwania zależy od okresu istnienia tokenu (zazwyczaj 1 godzina dla tokenów identyfikatora Entra).

Czy mogę wyłączyć buforowanie?

Buforowanie tokenów jest automatyczne i zoptymalizowane. Obecnie nie ma opcji jej wyłączenia.

Czy pamięć podręczna tokenu jest współdzielona między wystąpieniami zestawu SDK?

Nie — każde wystąpienie zestawu SDK zachowuje własną pamięć podręczną w pamięci. We wdrożeniach o wysokiej dostępności każdy zasobnik ma niezależne buforowanie.

Zabezpieczenia

Wdrożenia bezpiecznego zestawu SDK są zgodne z najlepszymi rozwiązaniami firmy Microsoft dotyczącymi tożsamości i ochrony danych, w tym użyciem tożsamości zarządzanej, izolacją sieci i odpowiednią obsługą poświadczeń.

Czy można bezpiecznie uruchomić zestaw SDK?

Tak — zobacz Najlepsze rozwiązania w zakresie zabezpieczeń dotyczące najlepszych rozwiązań w zakresie zabezpieczeń.

Czy należy uwidocznić zestaw SDK zewnętrznie?

Nigdy — zestaw SDK powinien być dostępny tylko z kontenera aplikacji. Aby uzyskać szczegółowe najlepsze rozwiązania w zakresie zabezpieczeń, zobacz Najlepsze rozwiązania w zakresie zabezpieczeń.

Jak zabezpieczyć zestaw SDK?

Zobacz Najlepsze rozwiązania dotyczące zabezpieczeń , aby uzyskać kompleksowe wskazówki.

Jakich poświadczeń należy użyć?

Kolejność preferencji:

Tożsamość zarządzana (Azure) — najbezpieczniejsze, bez poświadczeń
Certyfikaty — bezpieczne, można obracać
Wpisy tajne klienta — mniej preferowane , przechowywane w bezpiecznym magazynie

Czy zestaw SDK jest certyfikowany?

Sprawdź repozytorium GitHub , aby uzyskać bieżące informacje o zgodności.

Performance

Wydajność zestawu SDK zależy od skuteczności buforowania tokenów i opóźnienia rundy sieci z typowymi czasami odpowiedzi między 10–50 ms dla buforowanych tokenów.

Jaki jest wpływ na wydajność korzystania z zestawu SDK?

Typowa runda HTTP: 10-50 ms

Buforowanie tokenów minimalizuje powtarzające się pozyskiwanie. Pierwsze żądanie jest wolniejsze (pozyskiwanie tokenów), kolejne żądania używają buforowanych tokenów.

Jak wydajność zestawu SDK jest porównywana z bibliotekami procesów?

Biblioteki procesów są szybsze (bez rundy sieciowej), ale zestaw SDK zapewnia:

Niezależny dostęp do języka
Scentralizowana konfiguracja
Udostępniona pamięć podręczna tokenów między usługami
Uproszczone skalowanie

Aby uzyskać szczegółowe informacje, zobacz Przewodnik porównawczy .

Czy mogę skalować zestaw SDK w poziomie?

Tak. Wdrażanie wielu replik zestawu SDK przy użyciu wdrożenia platformy Kubernetes. Każdy zasobnik obsługuje niezależne buforowanie tokenów.

Migration

Przejście z witryny Microsoft.Identity.Web do zestawu SDK zapewnia zalety obsługi wielu języków, scentralizowanej konfiguracji i uproszczonego skalowania między usługami.

Czy mogę przeprowadzić migrację z witryny Microsoft.Identity.Web do zestawu Microsoft Entra SDK for AgentID?

Tak — zobacz Przewodnik porównawczy , aby uzyskać szczegółowe instrukcje migracji

Support

Uzyskaj pomoc dotyczącą problemów, znajdź dodatkową dokumentację i uzyskaj dostęp do zasobów społeczności za pośrednictwem oficjalnych kanałów.

Gdzie zgłaszam usterki?

Zgłoś problemy w repozytorium GitHub przy użyciu szablonu Entra ID.

Rozwiązywanie problemów

W przypadku napotkania problemów z zestawem SDK zapoznaj się z kompleksowym przewodnikiem rozwiązywania problemów, aby zapoznać się z krokami diagnostycznymi, typowymi problemami i rozwiązaniami w przewodniku rozwiązywania problemów.