Uwierzytelnianie przy użyciu zestawu SDK uwierzytelniania Microsoft Entra ID (przyczepka)

Zestaw MICROSOFT ENTRA ID Auth SDK (przyczepka) obsługuje operacje uwierzytelniania i tokenu dla agenta sztucznej inteligencji. Działa jako drugi kontener obok agenta, który obsługuje wymianę poświadczeń klienta, przepływy w imieniu użytkownika oraz zarządzanie cyklem życia tokenu. W tym artykule opisano wzorzec projektu zestawu SDK uwierzytelniania (przyczepki) Microsoft Entra ID, sposób jego działania i zaangażowane obiekty tożsamości.

Dlaczego warto używać zestawu SDK uwierzytelniania Microsoft Entra ID (przyczepki)?

Agenci sztucznej inteligencji potrzebują poświadczeń do wywoływania podrzędnych interfejsów API, ale typowe podejścia do uwierzytelniania agenta są niewystarczające.

  • Tajne dane zakodowane w kodzie agenta: Każdy plik agenta zawiera kopię aplikacji client_secret. Wszelkie naruszenia zabezpieczeń, wyciek dziennika lub zapomniany plik zatwierdzony .env w usłudze Git uwidaczniają pełną dzierżawę.
  • Delegowane tokeny użytkownika dla wszystkich elementów: Agent może działać tylko wtedy, gdy człowiek jest obecny. Utracisz również indywidualną audytowalność, ponieważ każde wywołanie wygląda jak ta sama główna zasada usługi.

Identyfikator agenta Microsoft Entra daje każdemu agentowi własną tożsamość. Wzorzec przyczepki ułatwia korzystanie z tej tożsamości przez utrzymywanie całej obsługi poświadczeń poza kodem agenta.

Jak działa zestaw SDK uwierzytelniania Microsoft Entra ID (przyczepka)

Zestaw MICROSOFT ENTRA ID Auth SDK (przyczepka) jest uruchamiany jako kontener, który uwidacznia punkty końcowe HTTP w sieci lokalnej zasobnika. Zajmuje się on następującymi obowiązkami:

  • Wymienia poświadczenia klienta za pomocą polecenia login.microsoftonline.com.
  • Uzyskuje tokeny dla tożsamości agenta w przepływach autonomicznych, korzystając z poświadczeń klienta lub federacyjnych poświadczeń tożsamości (FIC).
  • Obsługuje przepływy w imieniu (OBO) dla wywołań kontekstu użytkownika.
  • Buforuje tokeny i zarządza odświeżaniem i wygaśnięciem.
  • Abstrakt źródła poświadczeń — używa ClientSecret do rozwoju i SignedAssertionFromManagedIdentity dla wdrożeń Azure za pośrednictwem tego samego interfejsu API.

Poniższa tabela zawiera podsumowanie przepływu akcji uwierzytelniania między agentem a przyczepą:

Agent (twój kod) zestaw SDK uwierzytelniania Microsoft Entra ID (sidecar)
Zdecyduj, kiedy wywołać interfejs API Uzyskiwanie i buforowanie odpowiedniego tokenu
Kompilowanie żądania HTTP Wykonywanie poświadczeń klienta i wymiany OBO
Przekazywanie tokenu użytkownika dla OBO Weryfikowanie i przekazywanie asercji użytkowników
Obsługa logiki biznesowej Komunikacja z login.microsoftonline.com

Granica zabezpieczeń jest jawna: przyczepka nie ma portu hosta. Tylko usługi w tej samej sieci, takie jak kontener agenta, mogą żądać tokenów.

Obiekty tożsamości we wzorcu przyczepki

W poniższej tabeli opisano obiekty Microsoft Entra we wzorcu przyczepki:

Obiekt Rola Lokalizacja
Aplikacja strategii Szablon, który tworzy tożsamości agentów i wystawia je. Przechowuje poświadczenia klienta (sekretne lub federacyjne). Twoja dzierżawa Microsoft Entra
Tożsamość agenta Pojedynczy agent sztucznej inteligencji. Ma unikatowy identyfikator aplikacji, przyznane uprawnienia i rejestr audytu. Twoja dzierżawa Microsoft Entra
Aplikacja jednostronicowa (SPA) klienta ( tylko OBO) Interfejs Web, który loguje użytkownika i zamienia token użytkownika na token agenta w jego imieniu. Twoja dzierżawa Microsoft Entra
Kontener przyczepki Uruchamia poświadczenia klienta i przepływy OBO. Przechowuje poświadczenia schematu. Obok agenta
Agent kontenera Kod aplikacji. Żąda nagłówków autoryzacji z przyczepki. Pod, usługi Compose lub usługi App Service

Aby uzyskać więcej informacji na temat strategii i tożsamości agentów, zobacz Strategie tożsamości agenta i tożsamości agenta.

Abstrakcja źródła poświadczeń

Sidecar abstrakcyjnie oddziela źródło poświadczeń od kodu agenta. Podczas programowania można użyć elementu ClientSecret dla wygody. W wdrożeniach Azure produkcyjnych można przełączyć się na SignedAssertionFromManagedIdentity, poświadczenie tożsamości federacyjnej wspierane przez tożsamość zarządzaną bez zmiany kodu agenta.

Konfiguracja przyczepki określa, które źródło poświadczeń ma być używane. Agent nadal wywołuje ten sam /AuthorizationHeader punkt końcowy niezależnie od mechanizmu uwierzytelniania.

Przykładowe scenariusze Sidecar

Przykłady Identyfikator agenta Microsoft Entra sidecar przedstawiają następujące pojęcia:

  • Czym różni się strategia od tożsamości agenta i dlaczego agenci potrzebują własnej tożsamości.
  • Jak moduł boczny udostępnia punkty końcowe /AuthorizationHeader (pobierz token) i /DownstreamApi (token + wywołanie przez serwer pośredniczący).
  • Jak przyczepka przekazuje token zalogowanego użytkownika i ma Microsoft Entra ID Auth SDK (przyczepka) wybija token agenta w imieniu użytkownika za pośrednictwem OBO.
  • Jak interfejs API podrzędny weryfikuje tokeny agenta, w tym podpis, wystawcę, xms_par_app_azpi odbiorców.
  • Jak zamienić z ClientSecret (programowanie) na SignedAssertionFromManagedIdentity (wdrożenia Azure) bez zmiany kodu agenta.

Treści powiązane

  • Ostatnia aktualizacja o