Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Il Microsoft Entra ID Auth SDK (sidecar) gestisce le operazioni di autenticazione e token per l'agente di intelligenza artificiale. Funziona come un secondo contenitore accanto all'agente, gestendo lo scambio delle credenziali client, i flussi delegati (on-behalf-of) e la gestione del ciclo di vita dei token. Questo articolo illustra il modello di progettazione Microsoft Entra ID Auth SDK (sidecar), il funzionamento e gli oggetti Identity coinvolti.
Perché usare Microsoft Entra ID Auth SDK (sidecar)?
Gli agenti di intelligenza artificiale necessitano di credenziali per chiamare le API downstream, ma gli approcci comuni all'autenticazione dell'agente sono brevi:
-
Segreti hard-coded nel codice agente: Ogni immagine dell'agente contiene una copia della tua app
client_secret. Eventuali compromissioni, perdite di log o file dimenticati.envdi cui è stato eseguito il commit in Git espongono il tenant completo. - Token utente delegati per tutti gli elementi: L'agente può agire solo quando un essere umano è presente. Si perde anche l'auditabilità individuale perché ogni chiamata appare come proveniente dallo stesso principale del servizio.
Microsoft Entra Agent ID assegna a ogni agente la propria identità. Il modello sidecar rende l'identità facile da gestire mantenendo tutta la gestione delle credenziali al di fuori del codice dell'agente.
Funzionamento di Microsoft Entra ID Auth SDK (sidecar)
Il Microsoft Entra ID Auth SDK (sidecar) viene eseguito come contenitore che espone gli endpoint HTTP nella rete locale dei pod. Gestisce le responsabilità seguenti:
- Scambia credenziali client con
login.microsoftonline.com. - Acquisisce i token tramite credenziali client o credenziali di identità federate (FIC) per l'identità dell'agente nei flussi autonomi.
- Gestisce i flussi "on-behalf-of" (OBO) per le chiamate nel contesto utente.
- Memorizza nella cache i token e gestisce l'aggiornamento e la scadenza.
- Astrae l'origine delle credenziali: usa
ClientSecretper lo sviluppo eSignedAssertionFromManagedIdentityper le distribuzioni di Azure tramite la stessa API.
La tabella seguente riepiloga il flusso di azioni di autenticazione tra l'agente e il sidecar:
| Agente (tuo codice) | Microsoft Entra ID SDK di autenticazione (sidecar) |
|---|---|
| Decidere quando chiamare l'API | Acquisire e memorizzare nella cache il token corretto |
| Compilare la richiesta HTTP | Eseguire lo scambio di credenziali client e OBO |
| Rilascio del token utente per conto di (OBO) | Convalidare e inoltrare l'asserzione utente |
| Gestire la logica di business | Comunicare con login.microsoftonline.com |
Il limite di sicurezza è esplicito: il sidecar non ha alcuna porta host. Solo i servizi all'interno della stessa rete, ad esempio il contenitore dell'agente, possono richiedere token.
Oggetti di identità nel modello sidecar
Nella tabella seguente vengono descritti gli oggetti Microsoft Entra nel modello sidecar:
| Oggetto | Ruolo | Location |
|---|---|---|
| Applicazione di progetto | Modello che crea ed emette identità dell'agente. Contiene le credenziali del client (segreto o federato). | Tenant di Microsoft Entra |
| Identità agente | Singolo agente di intelligenza artificiale. Ha un ID dell'app univoco, permessi concessi e una tracciabilità delle verifiche. | Tenant di Microsoft Entra |
| Applicazione a pagina singola client (solo OBO) | Interfaccia web utente che autentica l'utente ed effettua lo scambio del token dell'utente con un token dell'agente per suo conto. | Tenant di Microsoft Entra |
| Sidecar contenitore | Esegue le credenziali client e i flussi OBO. Contiene le credenziali del progetto. | Accanto all'agente |
| Contenitore dell'agente | Codice dell'applicazione. Richiede le intestazioni di autorizzazione dal sidecar. | Il tuo pod, servizio di composizione, o servizio app |
Per altre informazioni sui progetti e sulle identità dell'agente, vedere Progetti di identità dell'agente e identità dell'agente.
Astrazione dell'origine delle credenziali
Il sidecar astrae la fonte delle credenziali dal codice del tuo agente. Durante lo sviluppo, è possibile usare un oggetto ClientSecret per praticità. Nelle distribuzioni di Azure di produzione è possibile passare a SignedAssertionFromManagedIdentity, credenziali di identità federate supportate dall'identità gestita, senza modificare il codice dell'agente.
La configurazione del sidecar determina l'origine delle credenziali da usare. L'agente continua a chiamare lo stesso /AuthorizationHeader endpoint indipendentemente dal meccanismo di autenticazione.
Gli scenari di esempio sidecar
Gli esempi di sidecar di Microsoft Entra Agent ID illustrano i concetti seguenti:
- Differenze tra un progetto e un'identità dell'agente e il motivo per cui gli agenti necessitano della propria identità.
- Come il sidecar espone
/AuthorizationHeader(get token) e/DownstreamApi(token + chiamata proxy) endpoints. - Come il sidecar inoltra un token dell'utente connesso e ha il Microsoft Entra ID Auth SDK (sidecar) coniare un token agent-on-behalf-of-user tramite OBO.
- Come l'API downstream convalida i token dell'agente, tra cui la firma, l'emittente,
xms_par_app_azpe il gruppo di destinatari. - Come eseguire lo scambio da
ClientSecret(sviluppo) aSignedAssertionFromManagedIdentity(distribuzioni Azure) senza modificare il codice dell'agente.