Eseguire il sidecar per lo sviluppo locale

Questo articolo illustra come eseguire Microsoft Entra ID Auth SDK (sidecar) nell'ambiente locale usando Docker Compose. Si avvia uno stack di quattro contenitori: agente di chat, sidecar, API meteo downstream e un modello LLM (Local Large Language Model), ad esempio (Ollama). Inviare quindi una query tramite l'interfaccia utente della chat e osservare il flusso completo del token dall'agente all'API. Prima di iniziare, esaminare i prerequisiti per gli strumenti necessari, Microsoft Entra oggetti tenant e la configurazione dell'ambiente locale.

L'esempio illustra due modalità di esecuzione e due flussi di identità:

Prerequisiti

Questo esempio funziona in macOS, Linux e Windows 10/11.

È anche necessario un tenant Microsoft Entra con questi oggetti:

• Uno schema di identità agente con un segreto del client. Registrare i valori per BLUEPRINT_APP_ID e BLUEPRINT_CLIENT_SECRET.
• Identità dell'agente creata da tale progetto. Registrare l'elemento AGENT_CLIENT_ID.
• (solo flusso OBO) Registrazione di un’applicazione SPA. Registrare l'elemento CLIENT_SPA_APP_ID.

Per creare questi oggetti, seguire il flusso di lavoro di PowerShell nel repository degli esempi Microsoft Entra Agent ID. Il flusso di lavoro crea l'app di progetto, l'identità dell'agente e, facoltativamente, l'app SPA per l'accesso OBO.

Ollama non è un prerequisito per l'host: si esegue all'interno dello stack di compose ed effettua automaticamente il qwen2.5:1.5b pull.

Clonare il repository di esempio:

Eseguire i comandi seguenti per scaricare il progetto di esempio e passare alla directory sidecar, che contiene la configurazione di Docker Compose e il codice sorgente dell'agente per questa procedura dettagliata:

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

Architettura di sviluppo locale sidecar

Lo stack esegue quattro contenitori in una rete Docker interna: llm-agent-dev (interfaccia utente della chat Flask, esposta sulla porta 3003), agent-id-sidecar-dev (sidecar dell'SDK di autenticazione Microsoft Entra ID), weather-api-dev (API downstream che convalida i token dell'agente) e ollama-dev (LLM locale). Solo l'interfaccia utente della chat è esposta all'host; l'API sidecar e meteo è raggiungibile solo dall'interno della rete Docker.

Tutti e quattro i contenitori sono eseguiti in una rete Docker Bridge condivisa (agent-network-dev). Solo l'interfaccia utente della chat (porta 3003) è esposta all'host. L'API sidecar e l'API del meteo non hanno una porta host, mantenendo l'endpoint del token all'interno di un confine di attendibilità.

Il percorso della richiesta è simile al seguente:

1. Si apre http://localhost:3003 nel browser e si invia una query.
2. L'agente (llm-agent-dev) riceve la query e decide di chiamare il get_weather strumento.
3. Lo strumento chiede al sidecar un'intestazione di autorizzazione in GET /AuthorizationHeader...?AgentIdentity={agentId}.
4. Il sidecar (agent-id-sidecar-dev) esegue uno scambio OAuth 2.0 con Microsoft Entra ID e riceve un token (TR).
5. Il sidecar restituisce l'intestazione Authorization: Bearer TR all'agente.
6. L'agente chiama l'API meteo (weather-api-dev) con tale intestazione.
7. L'API meteo convalida TR (JSON Web Key Set (JWKS), algoritmo di firma RS256, autorità di certificazione, scadenza, gruppo di destinatari) e restituisce i dati meteo.

L'agente non contatta mai Microsoft Entra ID direttamente e non vede mai credenziali. Chiede al sidecar un'intestazione Authorization , riceve un Bearer token e passa tale token all'API meteo. Solo il sidecar comunica con login.microsoftonline.com.

Comprendere il flusso del token

Il flusso autonomo usa due token: T1 (token dell'app di progetto dalle credenziali client) e TR (token agente per l'API downstream). Il flusso OBO aggiunge un terzo: Tc (token di accesso utente da MSAL.js accesso al browser). Il sidecar gestisce tutte le acquisizioni e la memorizzazione nella cache dei token in modo che il codice dell'agente non gestisca mai direttamente le credenziali.

Comprendere il flusso di token autonomo

Non è necessario alcun accesso utente. L'agente si autentica come se stesso utilizzando le credenziali del client del blueprint.

1. L'utente invia una query tramite l'interfaccia utente della chat.
2. L'agente (o l'agente LangGraph ReAct) decide di chiamare lo get_weather strumento.
3. Lo strumento richiede un'intestazione di autorizzazione dal sidecar in GET /AuthorizationHeaderUnauthenticated/graph-app?AgentIdentity={agentAppId}.
4. Il sidecar esegue uno scambio di credenziali del client con Microsoft Entra ID e riceve TR (solo app, idtyp=app).
5. Lo strumento chiama l'API meteo con Authorization: Bearer TR.
6. L'API meteo convalida TR (firma, autorità emittente, scadenza, destinatari) e restituisce i dati meteo.

Comprendere il flusso dei token per conto di (OBO)

L'agente agisce per conto di un utente connesso. Il sidecar esegue uno scambio di token in tre passaggi.

Diagramma che mostra il flusso del protocollo "on-behalf-of" dall'autenticazione nel browser fino allo scambio di token con sidecar e all'API meteo.

1. L'utente accede tramite MSAL.js nel browser e riceve Tc (token di accesso utente, audience = api://{BlueprintAppId}).
2. L'utente invia una query. L'agente riceve Tc con la richiesta.
3. Lo strumento richiede dal sidecar un'intestazione di autorizzazione a GET /AuthorizationHeader/graph, passando Authorization: Bearer Tc e ?AgentIdentity={agentAppId}.
4. Il sidecar convalida Tc, esegue uno scambio di credenziali client per ottenere T1, quindi esegue uno scambio OBO per ottenere TR (delegato, idtyp=user). Lo scambio OBO usa assertion=Tc, client_assertion=T1e grant_type=jwt-bearer.
5. Lo strumento chiama l'API meteo con Authorization: Bearer TR.
6. L'API meteo convalida TR e restituisce i dati meteo. TR agisce per conto dell'utente connesso.

Configurare le variabili di ambiente

Copiare il file di ambiente di esempio e aggiungere i valori di Microsoft Entra:

cp .env.example .env

Copy-Item .env.example .env

Aprire .env nell'editor e impostare i valori seguenti:

Il flusso autonomo richiede TENANT_ID, BLUEPRINT_APP_ID, BLUEPRINT_CLIENT_SECRETe AGENT_CLIENT_ID. Il flusso OBO richiede anche CLIENT_SPA_APP_ID.

Questo esempio sidecar usa ClientSecret come tipo di origine delle credenziali. Il sidecar supporta i tipi di credenziali seguenti tramite l'impostazione AzureAd__ClientCredentials__0__SourceType in docker-compose.yml:

• ClientSecret: solo sviluppo locale. Questo tipo è l'impostazione predefinita per questo esempio.
• SignedAssertionFromManagedIdentity: Distribuito in Azure. Zero segreti, consigliato per la produzione.
• KeyVault: Certificato da Azure Key Vault.
• StoreWithThumbprint: Certificato dall'archivio del computer locale.

Configurare l'accesso OBO (facoltativo)

Per testare il flusso on-behalf-of, creare l'app SPA e configurare il consenso OBO. Eseguire una delle coppie di script seguenti dalla radice del repository:

# 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>'

Aggiungi il CLIENT_SPA_APP_ID valore al .env file dopo l'esecuzione degli script.

Avvia lo stack

Compilare le immagini del contenitore e avviare tutti e quattro i servizi in modalità scollegata eseguendo il comando seguente:

docker compose up --build -d

La prima esecuzione richiede circa 30 secondi mentre Ollama scarica il modello qwen2.5:1.5b. Per verificare che lo stack locale di esempio sia in esecuzione e che componenti come sidecar e Ollama siano pronti, interrogare l'endpoint di stato:

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

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

La risposta viene visualizzata ollama_available: true quando lo stack è pronto.

Inviare una query tramite l'interfaccia utente della chat

Eseguire la procedura seguente per inviare una query di test tramite l'interfaccia utente della chat e osservare il flusso del token:

1. Aprire http://localhost:3003 nel browser.

2. Nella barra dell'intestazione, verificare che siano visualizzati l'ID Tenant e l'ID Agente.

3. Usare i due interruttori per selezionare la configurazione demo:

   • Modalità di esecuzione: selezionare Direct per ignorare l'LLM e chiamare direttamente l'API meteo oppure selezionare Ollama per usare un agente LangChain ReAct.
   • Flusso di identità: selezionare Autonomo per un token solo app o OBO per agire per conto di un utente connesso. Per OBO scegliere Accedi per eseguire l'autenticazione tramite un popup di MSAL.js.

4. Invia la query prepopolata "Meteo a Dallas?" ed esamina il risultato.

5. Nel pannello destro espandere Identity Trace (Traccia identità ) per esaminare ogni passaggio del flusso del token:

   • Richiesta di token al sidecar, compreso il parametro AgentIdentity.
   • Attestazioni JWT decodificate per ogni token (Tc, T1, TR per OBO; T1 e TR per autonomo).
   • Risultati della convalida dell'API downstream, tra cui la firma (JWKS, RS256), l'autorità emittente, la scadenza e i controlli del gruppo di destinatari.

Risolvere i problemi comuni

Per diagnosticare i problemi di avvio, autenticazione o API downstream, visualizzare i log da ogni contenitore eseguendo i comandi seguenti:

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

Pulire le risorse

Arresta i contenitori quando hai finito. Scegliere il livello di pulizia più adatto alle proprie esigenze. Il primo comando arresta i contenitori demo mantenendo i volumi e le immagini per un riavvio più rapido in un secondo momento:

# 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

Contenuti correlati

• Autenticazione con Auth SDK (sidecar)
• documentazione di Microsoft Entra ID Auth SDK (sidecar)
• Acquisire token e chiamare API downstream con Microsoft Entra ID Auth SDK (sidecar)
• Convalidare i token di identità dell'agente in un'API downstream
• Microsoft Entra Agent ID repository di esempi