Uruchom sidecar do lokalnego rozwoju

W tym artykule pokazano, jak uruchomić Microsoft Entra Auth SDK sidecar w środowisku lokalnym przy użyciu narzędzia Docker Compose. Uruchamiasz czterokontenerowy stos — agent czatu, przyczepkę, podrzędny interfejs API pogody i lokalny moduł LLM (Ollama). Następnie wysyłasz zapytanie za pośrednictwem interfejsu użytkownika czatu i obserwujesz pełny przepływ tokenu z agenta do interfejsu API.

W przykładzie przedstawiono dwa tryby uruchamiania i dwa przepływy tożsamości.

Autonomiczny (tylko aplikacja) OBO (w imieniu użytkownika)
Bezpośredni (bez LLM) Agent pobiera token i bezpośrednio wywołuje API pogodowe. To samo, ale przyczepka wymienia token zalogowanego użytkownika.
Ollama + LangChain LangGraph ReAct agent decyduje, kiedy wywołać narzędzie get_weather. Analogicznie, agent przekazuje dalej token użytkownika.

Wymagania wstępne

Ten przykład działa w systemach macOS, Linux i Windows 10/11.

Wymóg macOS Linux Windows
Docker Docker Desktop Silnik Docker + Compose v2 Docker Desktop (zalecane jest zaplecze WSL 2)
PowerShell 7+ brew install --cask powershell Instalowanie programu PowerShell w systemie Linux Wbudowane (lub zainstaluj PowerShell 7 lub nowszy)
Azure CLI brew install azure-cli Zainstaluj Azure CLI winget install -e Microsoft.AzureCLI

Potrzebujesz również dzierżawy Microsoft Entra z wyszczególnionymi obiektami:

  • Szablon tożsamości agenta z tajnym kluczem klienta. Rejestruj wartości dla BLUEPRINT_APP_ID i BLUEPRINT_CLIENT_SECRET.
  • Tożsamość agenta utworzona na podstawie tej strategii. Zarejestruj element AGENT_CLIENT_ID.
  • (Tylko przepływ OBO) Rejestracja aplikacji SPA. Zarejestruj element CLIENT_SPA_APP_ID.

Aby utworzyć te obiekty, wykonaj przebieg pracy programu PowerShell w repozytorium przykładów Identyfikator agenta Microsoft Entra. Przepływ pracy tworzy aplikację strategii, tożsamość agenta i opcjonalnie aplikację SPA na potrzeby logowania OBO.

Ollama nie jest wymaganiem wstępnym na hoście — działa wewnątrz stosu Compose i pobiera qwen2.5:1.5b automatycznie.

Klonowanie przykładowego repozytorium

Sklonuj repozytorium i przejdź do sidecar/dev katalogu:

git clone https://github.com/microsoft/entra-agentid-samples.git
cd entra-agentid-samples/sidecar/dev

Architektura

Stos uruchamia cztery kontenery w wewnętrznej sieci Docker: llm-agent-dev (interfejs czatu Flask, dostępny na porcie 3003), agent-id-sidecar-dev (sidecar SDK uwierzytelniania Microsoft Entra), weather-api-dev (podrzędny interfejs API weryfikujący tokeny agenta) i ollama-dev (lokalny moduł LLM). Tylko interfejs użytkownika czatu jest udostępniany hostowi; interfejs API przyczepki i pogody jest dostępny tylko z poziomu sieci platformy Docker.

Diagram przedstawiający architekturę przyczepki: Microsoft Entra ID wystawia token TR do przyczepki, Agent pyta przyczepkę o nagłówek autoryzacji, a następnie wywołuje interfejs API pogody z elementem Bearer TR, który weryfikuje token i zwraca dane.

Wszystkie cztery kontenery działają w udostępnionej sieci typu bridge Docker (agent-network-dev). Dostępny dla hosta jest tylko interfejs użytkownika czatu (port 3003). Interfejs API przyczepki i pogody nie ma portu hosta, który przechowuje punkt końcowy tokenu wewnątrz granicy zaufania.

Ścieżka żądania działa następująco:

  1. Otworzysz http://localhost:3003 w przeglądarce i wyślesz zapytanie.
  2. Agent (llm-agent-dev) odbiera zapytanie i podejmuje decyzję o wywołaniu get_weather narzędzia.
  3. Narzędzie pyta przyczepkę o nagłówek autoryzacji pod adresem GET /AuthorizationHeader...?AgentIdentity={agentId}.
  4. Sidecar (agent-id-sidecar-dev) wykonuje wymianę OAuth 2.0 z Microsoft Entra ID i otrzymuje token (TR).
  5. Moduł pomocniczy zwraca Authorization: Bearer TR nagłówek do agenta.
  6. Agent wywołuje interfejs API pogody (weather-api-dev) z tym nagłówkiem.
  7. Interfejs API pogody weryfikuje TR (JWKS, RS256, wystawcę, wygaśnięcie, odbiorców) i zwraca dane pogodowe.

Agent nigdy nie kontaktuje się z Microsoft Entra ID bezpośrednio, i nigdy nie widzi poświadczeń. Zwraca się do sidecar o nagłówek Authorization, otrzymuje token Bearer i przekazuje ten token do interfejsu API pogody. Tylko przyczepka komunikuje się z login.microsoftonline.com.

Omówienie przepływu tokenu

Przepływ autonomiczny używa dwóch tokenów: T1 (token aplikacji wzorcowej uzyskany z poświadczeń klienta) i TR (token agenta dla interfejsu API usługi zależnej). Przepływ OBO dodaje trzeci: Tc (token dostępu użytkownika z logowania MSAL.js przeglądarki). Przyczepka obsługuje wszystkie pozyskiwanie i buforowanie tokenów, dzięki czemu kod agenta nigdy nie zarządza poświadczeniami bezpośrednio.

Przepływ autonomiczny

Logowanie użytkownika nie jest wymagane. Agent uwierzytelnia się jako siebie, używając poświadczeń klienta planu.

Diagram przedstawiający autonomiczną sekwencję przepływu od agenta do komponentu pomocniczego (sidecar), przez Microsoft Entra ID, do interfejsu API pogody.

  1. Użytkownik wysyła zapytanie za pośrednictwem interfejsu użytkownika czatu.
  2. Agent (lub agent LangGraph ReAct) decyduje się użyć narzędzia get_weather.
  3. Narzędzie żąda nagłówka autoryzacji z przyczepki pod adresem GET /AuthorizationHeaderUnauthenticated/graph-app?AgentIdentity={agentAppId}.
  4. Sidecar wykonuje wymianę poświadczeń klienta z Microsoft Entra ID i odbiera TR (tylko do aplikacji, idtyp=app).
  5. Narzędzie wywołuje interfejs API pogody za pomocą polecenia Authorization: Bearer TR.
  6. Interfejs API pogody sprawdza token (podpis, wystawca, wygaśnięcie, odbiorca) i zwraca dane pogodowe.

przepływ OBO

Agent działa w imieniu zalogowanego użytkownika. Moduł boczny wykonuje trzyetapową wymianę tokenów.

Diagram przedstawiający sekwencję przepływów w imieniu z logowania przeglądarki za pośrednictwem wymiany tokenów przyczepki do interfejsu API pogody.

  1. Użytkownik loguje się za pośrednictwem MSAL.js w przeglądarce i otrzymuje token dostępu użytkownika (audience = api://{BlueprintAppId}).
  2. Użytkownik wysyła zapytanie. Agent otrzymuje Tc razem z żądaniem.
  3. Narzędzie żąda nagłówka autoryzacji z sidecar pod adresem GET /AuthorizationHeader/graph, przekazując Authorization: Bearer Tc i ?AgentIdentity={agentAppId}.
  4. Sidecar weryfikuje Tc, wykonuje wymianę poświadczeń klienta w celu uzyskania T1, a następnie wykonuje wymianę OBO w celu uzyskania TR (delegowane, idtyp=user). Giełda OBO używa assertion=Tc, client_assertion=T1 i grant_type=jwt-bearer.
  5. Narzędzie wywołuje interfejs API pogody za pomocą polecenia Authorization: Bearer TR.
  6. API pogody weryfikuje TR i zwraca dane pogodowe. Tr działa w imieniu zalogowanego użytkownika.

Konfigurowanie zmiennych środowiskowych

Tip

Jeśli masz .env już plik z poprzedniego przebiegu, w którym elementy TENANT_ID, BLUEPRINT_APP_ID, BLUEPRINT_CLIENT_SECRET i AGENT_CLIENT_ID są wypełnione, przejdź do sekcji Uruchom stos. Obiekty Microsoft Entra przetrwają ponowne uruchomienie kontenera i docker compose down.

Skopiuj przykładowy plik środowiska i dodaj wartości Microsoft Entra:

cp .env.example .env

Otwórz .env plik w edytorze i ustaw następujące wartości:

Zmienna Description
TENANT_ID Twój identyfikator dzierżawy Microsoft Entra.
BLUEPRINT_APP_ID Identyfikator klienta rejestracji aplikacji szablonu. Przyczepka uwierzytelnia się jako ta aplikacja.
BLUEPRINT_CLIENT_SECRET Sekret klienta blueprintu. Służy tylko do programowania lokalnego.
AGENT_CLIENT_ID Identyfikator klienta tożsamości agenta. Przekazano jako AgentIdentity parametr zapytania do przyczepki.
CLIENT_SPA_APP_ID Identyfikator klienta rejestracji aplikacji SPA. Wymagany tylko dla przepływu OBO.
OLLAMA_MODEL Model Ollama do użycia. Wartość domyślna to qwen2.5:1.5b.

Przepływ autonomiczny wymaga TENANT_ID, BLUEPRINT_APP_ID, BLUEPRINT_CLIENT_SECRET, i AGENT_CLIENT_ID. Przepływ OBO wymaga również CLIENT_SPA_APP_ID.

W tym przykładzie użyto ClientSecret jako typu źródła poświadczeń. Przyczepka obsługuje następujące typy poświadczeń za pomocą ustawienia w pliku AzureAd__ClientCredentials__0__SourceTypedocker-compose.yml:

  • ClientSecret: Tylko lokalny rozwój. Ten typ jest domyślny dla tego przykładu.
  • SignedAssertionFromManagedIdentity: Wdrożono na Azure. Zero tajemnic, zalecane do użycia w środowisku produkcyjnym.
  • KeyVault: Certyfikat z Azure Key Vault.
  • StoreWithThumbprint: Certyfikat z magazynu komputerów lokalnych.

Konfigurowanie logowania OBO (opcjonalnie)

Aby przetestować przepływ wykonywany w imieniu użytkownika, utwórz aplikację SPA i skonfiguruj zgodę OBO. Uruchom jedną z następujących par skryptów z katalogu głównego repozytorium:

# Create the SPA app registration for MSAL.js browser sign-in
bash ../../scripts/setup-obo-client-app.sh
# → prints CLIENT_SPA_APP_ID

# Wire up the OBO scope + admin consent on the Blueprint
bash ../../scripts/setup-obo-blueprint.sh

CLIENT_SPA_APP_ID Dodaj wartość do .env pliku po uruchomieniu skryptów.

Uruchamianie stosu

Uruchom wszystkie cztery kontenery:

docker compose up --build -d

Pierwsze uruchomienie trwa około 30 sekund, podczas gdy Ollama ściąga qwen2.5:1.5b model. Aby sprawdzić, czy stos jest gotowy:

curl http://localhost:3003/api/status

Odpowiedź jest wyświetlana ollama_available: true , gdy stos jest gotowy.

Wysyłanie zapytania za pośrednictwem interfejsu użytkownika czatu

  1. Otwórz http://localhost:3003 w przeglądarce.

  2. Na pasku nagłówka sprawdź, czy jest wyświetlany identyfikator dzierżawy i identyfikator agenta .

  3. Użyj dwóch przycisków, aby wybrać konfigurację demonstracyjną:

    • Tryb wykonywania: wybierz Bezpośredni, aby pominąć LLM i wywołać interfejs API pogody bezpośrednio, lub wybierz Ollama, aby użyć agenta ReAct LangChain.
    • Przepływ tożsamości: wybierz Autonomiczny dla tokenu tylko aplikacji lub OBO, aby wykonywać działania w imieniu zalogowanego użytkownika. W przypadku aplikacji OBO wybierz pozycję Zaloguj się, aby uwierzytelnić się za pomocą okna MSAL.js.

  4. Wyślij wstępnie wypełnione zapytanie "Pogoda w Dallas?" i sprawdź wynik.

  5. W panelu po prawej stronie rozwiń pozycję Identity Trace (Śledzenie tożsamości), aby sprawdzić każdy krok przepływu tokenu:

    • Żądanie tokenu do sidecaru, w tym parametr AgentIdentity.
    • Zdekodowane oświadczenia JWT dla każdego tokenu (Tc, T1, TR dla OBO; T1 i TR dla autonomicznego).
    • Wyniki walidacji interfejsu API podrzędnego, w tym sygnatury (JWKS, RS256), wystawcy, wygaśnięcia i kontroli odbiorców.

Rozwiązywanie typowych problemów

Objaw Prawdopodobna przyczyna Napraw
/api/status Zwraca ollama_available: false Model jest nadal pobierany. Poczekaj około 30 sekund. Sprawdź dzienniki przy użyciu polecenia docker logs ollama-dev.
Interfejs API pogody zwraca 401 Unauthorized Niezgodność dla najemcy tokenu, wygasły klucz tajny lub weryfikacja podpisu nie powiodła się. Sprawdź, czy TENANT_ID jest zgodny z najemcą szablonu. Sprawdź dzienniki sidecar za pomocą docker logs agent-id-sidecar-dev.
LLM zwraca informacje o pogodzie bez uruchamiania narzędzia Model qwen2.5:1.5b jest zbyt mały do niezawodnego wywoływania narzędzi. Zmień OLLAMA_MODEL wartość na qwen2.5:7b lub llama3.1:8b w .env pliku.
Logowanie OBO — okienko jest zablokowane Blokowanie wyskakujących okienek przeglądarki jest aktywne. Zezwalaj na wyskakujące okienka dla localhost:3003.
4xx błąd z przyczepki podczas OBO CLIENT_SPA_APP_ID jest brakujący lub identyfikator URI przekierowania SPA nie jest zgodny. Uruchom ponownie skrypty konfiguracji OBO. Sprawdź, czy http://localhost:3003 jest na liście URI przekierowań dla SPA.

Aby wyświetlić dzienniki kontenera dla dowolnej usługi:

docker logs llm-agent-dev
docker logs agent-id-sidecar-dev
docker logs weather-api-dev

Uprzątnij zasoby

Po zakończeniu zatrzymaj kontenery.

# Stop containers, keep volumes and images
docker compose down

# Stop containers and remove the Ollama model cache
docker compose down -v

# Remove containers, volumes, and images
docker compose down -v --rmi all

Treści powiązane

  • Last updated on