Sichern Sie den Amazon Bedrock-Agenten mit der Microsoft Entra-Agent-ID.

In diesem Leitfaden erfahren Sie, wie Sie einen Amazon Bedrock-Agent mithilfe des Microsoft Entra Auth SDK (Sidecar) zur Authentifizierung bei downstream-APIs sichern. Das Sidecar wird als separater Container ausgeführt und übernimmt die Verwaltung der Anmeldeinformationen sowie den Austausch der Tokens mit Microsoft Entra ID. Ihr Agent fordert einen Autorisierungsheader vom Sidecar an und der Sidecar führt den OAuth 2.0-Austausch mit Microsoft Entra ID durch.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

• Ein Microsoft Entra-Mandant.
• Ein Azure-Abonnement.
• Docker Desktop (macOS/Windows) oder Docker Engine mit Compose v2 (Linux).
• PowerShell 7+.
• Azure CLI.
• AWS CLI v2.
• Ein AWS-Konto mit Bedrock-Modellzugriff, das für Anthropic Claude 3 Haiku (oder Ihr bevorzugtes Modell) aktiviert ist. Aktivieren Sie den Zugriff in der AWS Bedrock-Konsole unter "Modellzugriff>".
• Global Administrator Rolle für das erstmalige Microsoft Entra Setup. Verwenden Sie Privileged Identity Management (PIM), um diese Rolle just-in-time zu aktivieren.

Klonen des Beispiel-Repositorys

1. Klonen Sie das Repository, und wechseln Sie zum AWS-Beispielverzeichnis:

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

Architektur

Das Microsoft Entra Auth SDK (Sidecar) befindet sich zwischen Ihrem Agent und Microsoft Entra ID. Der Agent spricht nie direkt mit Microsoft Entra ID und verwaltet niemals Anmeldeinformationen. Es fordert das Sidecar auf, einen Authorization Header anzufordern, um eine Downstream-API aufzurufen. Amazon Bedrock verarbeitet LLM-Rückschlüsse separat, ohne sich gedanken über Identität zu machen.

Im Beispiel werden drei Container in einem Docker-Bridge-Netzwerk ausgeführt.

• llm-agent-aws: Flask-App mit einer Chat-Benutzeroberfläche und einem LangGraph ReAct-Agenten, der Amazon Bedrock (Claude) zur Begründung aufruft. Verfügbar gemacht am Port 3001.
• agent-id-sidecar-aws: Der offizielle Microsoft Entra Auth SDK-Container. Dient zum Abrufen und Zwischenspeichern von Token. Kein Hostport, erreichbar nur innerhalb des Docker-Netzwerks.
• weather-api-aws: Eine nachgelagerte API, die das JWT des Agenten (Signatur, Herausgeber, Ablauf, Zielgruppe) bei jeder Anfrage überprüft und Wetterdaten zurückgibt.

Die Anforderung fließt durch die folgenden Schritte:

1. Sie geben eine Abfrage in die Chat-UI ein unter http://localhost:3001.
2. Die Flask-App sendet die Abfrage über den LangGraph ReAct-Agent an AWS Bedrock (Claude).
3. Wenn Claude entscheidet, dass wetterdaten benötigt werden, ruft sie das get_weather Tool auf.
4. Das Tool fragt das Sidecar nach einem Autorisierungsheader, indem es GET /AuthorizationHeader?AgentIdentity={agentId} aufruft.
5. Der Sidecar authentifiziert sich bei Microsoft Entra ID mit OAuth 2.0 (Anmeldeinformationen des Clients oder OBO-Austausch).
6. Microsoft Entra ID gibt das angeforderte Token (TR) an das Sidecar zurück.
7. Der Agent ruft die Wetter-API mit Authorization: Bearer TR.
8. Die Wetter-API überprüft TR und gibt die JSON-Antwort des Wetters zurück.

Verständnis des Tokenflusses

Drei Token sind an dem Identitätsaustausch beteiligt:

Im autonomen Fluss ruft der Sidecar mithilfe der Anmeldeinformationen des Clients T1 ab und tauscht es dann gegen TR aus, das auf die Downstream-API ausgerichtet ist. Im OBO-Fluss empfängt der Sidecar auch Tc (das Token des Benutzers) und führt einen OBO-Austausch durch, um TR abzurufen, das im Namen des angemeldeten Benutzers handelt.

In diesem Setup wird nur die Chat-Ui (Port 3001) für Ihren Host verfügbar gemacht. Die Sidecar- und Wetter-API sind nur innerhalb des Docker-Netzwerks erreichbar, wodurch eine klare Sicherheitsgrenze festgelegt wird.

Auswählen eines Ausführungsmodus und eines Identitätsflusses

Das Beispiel unterstützt zwei Ausführungsmodi und zwei Identitätsflüsse, die Sie kombinieren können:

Verwenden Sie den direkten Modus, um ihren Tokenfluss end-to-End zu überprüfen, ohne AWS Bedrock-Zugriff zu benötigen. Wechseln Sie zum Bedrock-Modus für die vollständige Agent-Erfahrung.

Auswählen einer AWS-Authentifizierungsstufe

Das Beispiel unterstützt drei Möglichkeiten zur Authentifizierung bei Amazon Bedrock. Wählen Sie die Ebene aus, die Ihrer Umgebung entspricht:

• Temporäre STS-Anmeldeinformationen: Am besten für die lokale Entwicklung mit AWS SSO. Legen Sie AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY und AWS_SESSION_TOKEN in Ihrer .env-Datei fest. Diese Anmeldeinformationen laufen nach ungefähr einer Stunde ab.
• Bedrock-API-Schlüssel: Am besten für Demos und Workshops. Legen Sie AWS_BEARER_TOKEN_BEDROCK in der Datei .env fest. Gilt nur für Bedrock mit einer konfigurierbaren Lebensdauer.
• OIDC federation: Am besten geeignet für Produktionsbereitstellungen auf Azure App Service. Verwendet AWS_ROLE_ARN und AWS_WEB_IDENTITY_TOKEN_FILE, die von der Plattform festgelegt werden. Keine geheimen Schlüssel werden überall gespeichert.

Auswählen eines Bedrock-Modells

Das Beispiel ist standardmäßig auf us.anthropic.claude-3-haiku-20240307-v1:0 festgelegt, da es das billigste Anthropic Modell auf Bedrock ist und Toolanrufe unterstützt. Das us.-Präfix gibt ein regionsübergreifendes Inferenzprofil an, das zwischen Regionen in den USA routet, um eine höhere Verfügbarkeit zu gewährleisten.

Andere unterstützte Modelle:

Überschreiben Sie die Standardeinstellungen, indem Sie BEDROCK_MODEL_ID auf .env setzen. Sie müssen jedes Modell im AWS Bedrock-Konsolenmodellzugriff> aktivieren, bevor es aufgerufen werden kann.

Erstellen der Entra-Objekte (erstmaliges Einrichten)

Wenn Sie schon über eine .env Datei aus einer vorherigen Ausführung verfügen, bei der BLUEPRINT_APP_ID ausgefüllt ist, fahren Sie mit Umgebungsvariablen konfigurieren fort.

Führen Sie die folgenden Befehle einmal pro Mandant aus, um die Blueprint-App, die Agent-ID und die SPA-App zu erstellen, die für die OBO-Anmeldung verwendet wird.

1. Erstellen Sie die Blueprint-App und die Agent-ID für den autonomen Fluss, indem Sie den PowerShell-Workflow in " Erstellen eines Agentidentitäts-Blueprints " und "Erstellen von Agentidentitäten" ausführen. Am Ende haben Sie:

   • TENANT_ID: Ihr Entra-Mandant.
   • BLUEPRINT_APP_ID: Blueprint-App-Registrierung.
   • BLUEPRINT_CLIENT_SECRET: Geheimer Clientschlüssel für den Blueprint.
   • AGENT_CLIENT_ID: Die agent-ID, die aus dem Blueprint erstellt wurde.

2. (Optional) Erstellen Sie die SPA-App, und konfigurieren Sie OBO. Dieser Schritt ist nur erforderlich, wenn Sie den OBO-Identitätsfluss verwenden möchten:

   Bash:

   bash ../../scripts/setup-obo-client-app.sh
   bash ../../scripts/setup-obo-blueprint.sh
   

   PowerShell:

   pwsh ../../scripts/setup-obo-client-app.ps1
   pwsh ../../scripts/setup-obo-blueprint.ps1 `
       -TenantId        '<TENANT_ID>' `
       -BlueprintAppId  '<BLUEPRINT_APP_ID>' `
       -AgentAppId      '<AGENT_CLIENT_ID>' `
       -ClientSpaAppId  '<CLIENT_SPA_APP_ID>'
   

Der SPA-Umleitungs-URI für dieses Beispiel lautet http://localhost:3001 (Port 3001, nicht 3003). Stellen Sie sicher, dass dieser URI registriert ist.

Umgebungsvariablen konfigurieren

Das Sidecar unterstützt mehrere Anmeldedatentypen über die AzureAd__ClientCredentials__0__SourceType Einstellungen in docker-compose.yml:

• ClientSecret: Nur lokale Entwicklung. Das Beispiel enthält diesen Typ.
• SignedAssertionFromManagedIdentity: Auf Azure bereitgestellt. Null Geheimnisse, empfohlen für die Produktion.
• KeyVault: Zertifikat von Azure Key Vault.
• StoreWithThumbprint: Zertifikat aus dem lokalen Computerspeicher.

1. Kopieren Sie die Umgebungsvorlage, und öffnen Sie sie in Ihrem Editor:

   Bash:

   cp .env.example .env
   

   PowerShell:

   Copy-Item .env.example .env
   

2. Legen Sie die folgenden Variablen in Ihrer .env Datei fest:

   • TENANT_ID: Ihre Entra-Mandanten-ID.
   • BLUEPRINT_APP_ID: Blueprint-App-Registrierung. Der Sidecar authentifiziert sich als diese App.
   • BLUEPRINT_CLIENT_SECRET: Geheimer Blueprint-Clientschlüssel (nur lokale Entwicklung).
   • AGENT_CLIENT_ID: Ihre Agent-ID. Wird als AgentIdentity Abfrageparameter angezeigt.
   • CLIENT_SPA_APP_ID: SPA-App-ID, die von MSAL.js für die Browseranmeldung verwendet wird (nur OBO).
   • AWS_REGION: AWS-Region für Bedrock, z. B. us-east-2.
   • BEDROCK_MODEL_ID: Modell-ID. Standardwert: us.anthropic.claude-3-haiku-20240307-v1:0.
   • VALIDATE_TOKEN_SIGNATURE: Standard true. Legen Sie false fest, um die JWKS-Signaturüberprüfung in der Wetter-API zu überspringen (nur Debugging).

3. Fügen Sie Ihre AWS-Anmeldeinformationen basierend auf der ausgewählten Ebene hinzu:

   • Ebene A (STS): auf AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY und AWS_SESSION_TOKEN gesetzt.
   • Stufe B (API-Schlüssel): Set AWS_BEARER_TOKEN_BEDROCK.
   • Stufe C (OIDC): Konfiguriert über Plattform-App-Einstellungen, nicht in .env.

Starten des Stacks

1. Stellen Sie sicher, dass Docker ausgeführt wird, und starten Sie dann alle Container:

   docker compose up --build -d
   

2. Überprüfen Sie, ob der Stapel bereit ist:

   Bash:

   curl http://localhost:3001/api/status
   

   PowerShell:

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

   Es wird eine Antwort angezeigt, die bedrock_available: true angibt (oder false wenn Sie den Direct-Modus ohne AWS-Anmeldeinformationen verwenden).

Senden einer Abfrage über die Chat-Ui

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

2. Verwenden Sie die Kopfzeile, um Ihre Demo zu konfigurieren:

   • Ausführungsmodus:Direct (LLM überspringen) oder Bedrock (LangChain ReAct-Agent auf Claude).
   • Identitätsfluss:Autonomous (nur App-Token) oder OBO (fungiert für einen angemeldeten Benutzer).

3. Wenn Sie OBO auswählen, wählen Sie "Anmelden " aus, um sich über das Popup MSAL.js zu authentifizieren.

4. Geben Sie eine Abfrage wie "Wetter in Dallas?" ein, und wählen Sie "Senden" aus.

5. Sehen Sie sich den Bereich "Identitätsablaufverfolgung " auf der rechten Seite für eine schrittweise Aufschlüsselung jedes Tokenaustauschs und API-Aufrufs an. Das Panel zeigt farbcodierte JWT-Karten für jedes Token (Tc, T1, TR) mit decodierten Ansprüchen.

Häufige Probleme beheben

Wenn etwas nicht wie erwartet funktioniert, überprüfen Sie die folgende Tabelle auf häufige Probleme und Korrekturen:

Anzeigen von Containerprotokollen zum Debuggen:

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

Bereinigen von Ressourcen

Stoppen Sie die Container und entfernen Sie sie, wenn Sie fertig sind.

# Stop containers but keep volumes and images
docker compose down

# Remove everything including volumes and images
docker compose down -v --rmi all

Die Entra-Objekte (Agenten-Blueprint, Agenten-ID, SPA-App-Registrierung) sind als mandantenseitiger Status gespeichert, sodass die Verwendung von docker compose down sie nicht entfernt. Entfernen Sie sie manuell im Microsoft Entra Admin Center, wenn sie nicht mehr benötigt werden.

Verwandte Inhalte

• Authentifizierung mit Microsoft Entra Auth SDK (Sidecar)
• Integrieren Sie Drittanbieter-Agenten mit Microsoft Entra-Agent-ID
• Microsoft Entra Auth SDK Sidecar-Containerimage