Führen Sie das Sidecar für die lokale Entwicklung aus.

In diesem Artikel wird gezeigt, wie Sie das Microsoft Entra ID Auth SDK (Sidecar) in Ihrer lokalen Umgebung mithilfe von Docker Compose ausführen. Sie starten einen Stapel mit vier Containern – Chat-Agent, Sidecar, downstream Wetter-API und ein lokales großsprachliches Modell (LLM) wie (Ollama). Anschließend senden Sie eine Abfrage über die Chat-UI und beobachten den vollständigen Tokenfluss von Agent zu API. Bevor Sie beginnen, überprüfen Sie die Voraussetzungen für erforderliche Tools, Microsoft Entra Mandantenobjekte und die Einrichtung der lokalen Umgebung.

Im Beispiel werden zwei Ausführungsmodi und zwei Identitätsflüsse veranschaulicht:

Voraussetzungen

Dieses Beispiel funktioniert unter macOS, Linux und Windows 10/11.

Sie benötigen außerdem einen Microsoft Entra-Mandanten mit diesen Objekten:

• Ein Agentenidentitätsmodul mit einem Client-Geheimnis. Notieren Sie die Werte für BLUEPRINT_APP_ID und BLUEPRINT_CLIENT_SECRET.
• Eine agent-Identität, die aus diesem Blueprint erstellt wurde. Zeichnen Sie AGENT_CLIENT_ID auf.
• (nur OBO Flow) Eine SPA App Registrierung. Zeichnen Sie CLIENT_SPA_APP_ID auf.

Zum Erstellen dieser Objekte folgen Sie dem PowerShell-Workflow im Microsoft Entra-Agent-ID-Beispiel-Repository. Der Workflow erstellt die Blueprint-App, die Agentidentität und optional die SPA-App für die Anmeldung bei OBO.

Ollama ist keine Voraussetzung auf Ihrem Host - es wird innerhalb des Compose Stacks ausgeführt und qwen2.5:1.5bzieht automatisch.

Klonen des Beispiel-Repositorys

Führen Sie die folgenden Befehle aus, um das Beispielprojekt herunterzuladen und in das Sidecar-Verzeichnis zu wechseln, das den Docker Compose-Konfigurations- und Agent-Quellcode für diese exemplarische Vorgehensweise enthält:

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

Lokale Entwicklungsarchitektur von Sidecar

Der Stack umfasst vier Container in einem internen Docker-Netzwerk: llm-agent-dev (Flask-Chat-UI, offengelegt über Port 3003), agent-id-sidecar-dev (das Microsoft Entra ID Auth SDK-Sidecar), weather-api-dev (nachgelagerte API, die Agent-Tokens validiert) und ollama-dev (das lokale LLM). Nur die Chat-UI wird Ihrem Host offengelegt. Die Sidecar- und Wetter-API sind nur innerhalb des Docker-Netzwerks erreichbar.

Alle vier Container werden in einem freigegebenen Docker-Brücke-Netzwerk (agent-network-dev) ausgeführt. Nur die Chat-UI (Port 3003) wird Für Ihren Host verfügbar gemacht. Die Sidecar- und Wetter-API haben keinen Hostport, wodurch der Tokenendpunkt innerhalb einer Vertrauensgrenze bleibt.

Der Anforderungspfad funktioniert wie folgt:

1. Sie öffnen http://localhost:3003 in Ihrem Browser und senden eine Abfrage.
2. Der Agent (llm-agent-dev) empfängt die Abfrage und entscheidet, das get_weather Tool aufzurufen.
3. Das Tool fragt das Sidecar nach einem Autorisierungsheader bei GET /AuthorizationHeader...?AgentIdentity={agentId}.
4. Der Sidecar (agent-id-sidecar-dev) führt einen OAuth 2.0-Austausch mit Microsoft Entra ID durch und empfängt ein Token (TR).
5. Das Sidecar gibt den Authorization: Bearer TR Header an den Agent zurück.
6. Der Agent ruft die Wetter-API (weather-api-dev) mit diesem Header auf.
7. Die Wetter-API validiert TR (JSON Web Key Set (JWKS), RS256-Signaturalgorithmus, Aussteller, Ablaufzeit, Zielgruppe) und gibt Wetterdaten zurück.

Der Agent kontaktiert Microsoft Entra ID nie direkt und bekommt keine Anmeldeinformationen zu sehen. Er fragt das Sidecar nach einer Authorization Kopfzeile, empfängt ein Bearer Token und übergibt dieses Token an die Wetter-API. Nur das Sidecar kommuniziert mit login.microsoftonline.com.

Verständnis des Tokenflusses

Der autonome Fluss verwendet zwei Token: T1 (Blueprint-App-Token aus den Anmeldeinformationen des Clients) und TR (Agent-Token für die Downstream-API). Der OBO-Fluss fügt ein Drittes hinzu: Tc (Benutzerzugriffstoken von der MSAL.js-Browser-Anmeldung). Das Sidecar übernimmt den gesamten Token-Erwerb und die Zwischenspeicherung, sodass Ihr Agent-Code Anmeldeinformationen nie direkt verwaltet.

Verstehen Sie den autonomen Token-Fluss

Es ist keine Benutzeranmeldung erforderlich. Der Agent authentifiziert sich selbst, indem er die Anmeldeinformationen des Blueprints verwendet.

1. Der Benutzer sendet eine Abfrage über die Chat-Ui.
2. Der Agent (oder LangGraph ReAct-Agent) entscheidet, das get_weather Tool aufzurufen.
3. Das Tool fordert einen Autorisierungs-Header vom Sidecar bei GET /AuthorizationHeaderUnauthenticated/graph-app?AgentIdentity={agentAppId} an.
4. Das Sidecar führt einen Austausch von Anmeldeinformationen des Clients mit Microsoft Entra ID durch und erhält TR (nur App, idtyp=app).
5. Das Tool ruft die Wetter-API mit Authorization: Bearer TR.
6. Die Wetter-API überprüft TR (Signatur, Aussteller, Ablaufdatum, Zielgruppe) und gibt Wetterdaten zurück.

Grundlegendes zum On-Behalf-Of-Tokenfluss (OBO)

Der Agent fungiert im Namen eines angemeldeten Benutzers. Das Sidecar führt einen dreistufigen Tokenaustausch durch.

1. Der Benutzer meldet sich über MSAL.js im Browser an und empfängt Tc (Benutzerzugriffstoken, Zielgruppe = api://{BlueprintAppId}).
2. Der Benutzer sendet eine Abfrage. Der Agent erhält Tc mit der Anfrage.
3. Das Tool fordert einen Autorisierungs-Header vom Sidecar bei GET /AuthorizationHeader/graph an und übergibt Authorization: Bearer Tc und ?AgentIdentity={agentAppId}.
4. Das Sidecar validiert Tc, führt einen Client Anmeldeinformationen Exchange durch, um T1 zu erhalten, und führt dann einen OBO Exchange durch, um TR zu erhalten (delegiert, idtyp=user). Der OBO-Austausch verwendet assertion=Tc, client_assertion=T1und grant_type=jwt-bearer.
5. Das Tool ruft die Wetter-API mit Authorization: Bearer TR.
6. Die Wetter-API überprüft TR und gibt Wetterdaten zurück. TR fungiert im Namen des angemeldeten Benutzers.

Umgebungsvariablen konfigurieren

Kopieren Sie die Beispielumgebungsdatei, und fügen Sie Ihre Microsoft Entra Werte hinzu:

cp .env.example .env

Copy-Item .env.example .env

Öffnen Sie den Editor .env und setzen Sie die folgenden Werte auf.

Der autonome Fluss erfordert TENANT_ID, BLUEPRINT_APP_ID, BLUEPRINT_CLIENT_SECRET, und AGENT_CLIENT_ID. Der OBO Flow erfordert ebenfalls CLIENT_SPA_APP_ID.

In diesem Sidecar-Beispiel wird ClientSecret als Typ der Anmeldeinformationsquelle verwendet. Das Sidecar unterstützt die folgenden Anmeldeinformationen über die AzureAd__ClientCredentials__0__SourceType-Einstellung in docker-compose.yml:

• ClientSecret: Nur lokale Entwicklung. Dieser Typ ist die Standardeinstellung für dieses Beispiel.
• SignedAssertionFromManagedIdentity: Auf Azure bereitgestellt. Null Geheimnisse, empfohlen für die Produktion.
• KeyVault: Zertifikat von Azure Key Vault.
• StoreWithThumbprint: Zertifikat aus dem lokalen Computerspeicher.

Einrichten der OBO-Anmeldung (optional)

Um den On-Behalf-of Flow zu testen, erstellen Sie die SPA App und konfigurieren Sie die OBO Zustimmung. Führen Sie eines der folgenden Skriptpaare aus dem Repositorystamm aus:

# 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

# Create the SPA app registration for MSAL.js browser sign-in
pwsh ../../scripts/setup-obo-client-app.ps1
# → prints CLIENT_SPA_APP_ID (and writes it to .env)

# Wire up the OBO scope + admin consent on the Blueprint
pwsh ../../scripts/setup-obo-blueprint.ps1 `
    -TenantId        '<TENANT_ID>' `
    -BlueprintAppId  '<BLUEPRINT_APP_ID>' `
    -AgentAppId      '<AGENT_CLIENT_ID>' `
    -ClientSpaAppId  '<CLIENT_SPA_APP_ID>'

Fügen Sie der CLIENT_SPA_APP_ID Datei nach dem Ausführen der Skripts den .env Wert hinzu.

Starten des Stacks

Erstellen Sie die Containerimages, und starten Sie alle vier Dienste im getrennten Modus, indem Sie den folgenden Befehl ausführen:

docker compose up --build -d

Die erste Ausführung dauert etwa 30 Sekunden, während Ollama das qwen2.5:1.5b Modell lädt. Um zu überprüfen, ob der lokale Beispiel-Stack läuft und ob Komponenten wie das Sidecar und Ollama bereit sind, rufen Sie den Statusendpunkt ab:

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

Invoke-RestMethod http://localhost:3003/api/status

Die Antwort zeigt ollama_available: true, wenn der Stapel bereit ist.

Senden einer Abfrage über die Chat-Ui

Führen Sie die folgenden Schritte aus, um eine Testabfrage über die Chat-UI zu senden und den Tokenfluss zu beobachten:

1. Öffnen Sie http://localhost:3003 in Ihrem Browser.

2. Überprüfen Sie in der Kopfzeile, ob Ihre Mandanten-ID und Die Agent-ID angezeigt werden.

3. Verwenden Sie die beiden Umschaltfläche, um Ihre Demokonfiguration auszuwählen:

   • Ausführungsmodus: Wählen Sie "Direkt " aus, um die LLM zu überspringen und die Wetter-API direkt aufzurufen, oder wählen Sie "Ollama " aus, um einen LangChain ReAct-Agent zu verwenden.
   • Identitätsfluss: Wählen Sie "Autonom" für ein Nur-App-Token oder OBO aus, um im Namen eines angemeldeten Benutzers zu handeln. Wählen Sie für OBO die Option "Anmelden " aus, um sich über ein MSAL.js-Popup zu authentifizieren.

4. Senden Sie die vorab aufgefüllte Abfrage "Wetter in Dallas?", und überprüfen Sie das Ergebnis.

5. Erweitern Sie im rechten Bereich Identity Trace, um jeden Schritt des Tokenflusses zu überprüfen.

   • Die Token-Anfrage an den Sidecar, einschließlich des Parameters AgentIdentity.
   • Decodierte JWT-Ansprüche für jedes Token (Tc, T1, TR für OBO; T1 und TR für autonom).
   • Nachgeschaltete API-Validierungsergebnisse, einschließlich Signatur- (JWKS, RS256), Aussteller-, Ablauf- und Zielgruppenprüfungen.

Häufige Probleme beheben

Um Start-, Authentifizierungs- oder Downstream-API-Probleme zu diagnostizieren, zeigen Sie die Protokolle von jedem Container an, indem Sie die folgenden Befehle ausführen:

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

Bereinigen von Ressourcen

Stoppen Sie die Container, wenn Sie fertig sind. Wählen Sie die Bereinigungsstufe aus, die Ihren Anforderungen entspricht. Mit dem ersten Befehl werden die Democontainer beendet, während Volumes und Bilder für einen schnelleren Neustart später beibehalten werden:

# 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

Verwandte Inhalte

• Authentifizierung mit Auth SDK (Sidecar)
• dokumentation zum Microsoft Entra ID Auth SDK (Sidecar)
• Abrufen von Token und Aufrufen von downstream-APIs mit Microsoft Entra ID Auth SDK (Sidecar)
• Überprüfen von Agentidentitätstoken in einer downstream-API
• Microsoft Entra Agent-ID-Beispiel-Repository