Domande frequenti su Microsoft Entra SDK per AgentID

Domande generali

Che cos'è Microsoft Entra SDK per AgentID?

Microsoft Entra SDK per AgentID è un servizio Web in contenitori che gestisce le chiamate API downstream, convalida e acquisizione di token. Viene eseguito come contenitore complementare insieme all'applicazione, consentendo di eseguire l'offload della logica di identità in un servizio dedicato. Centralizzando le operazioni di identità nell'SDK, si elimina la necessità di incorporare una logica di gestione dei token complessa in ogni servizio, riducendo la duplicazione del codice e potenziali vulnerabilità di sicurezza.

Perché usare Microsoft Entra SDK per AgentID anziché Microsoft.Identity.Web?

Caratteristica / Funzionalità	Microsoft.Identity.Web	Microsoft Entra SDK per AgentID
Supporto per la lingua	Solo C# / .NET	Qualsiasi linguaggio (HTTP)
Deployment	Libreria in-process	Contenitore separato
Acquisizione di token	✅ MSAL.NET diretta	✅ Tramite l'API HTTP
Memorizzazione nella cache dei token	✅ In memoria, ✅ distribuita	✅ In memoria, ❌distribuita
Flusso OBO	✅ Supporto nativo	✅ Tramite endpoint HTTP
Credenziali Client	✅ Supporto nativo	✅ Tramite endpoint HTTP
Identità gestita	✅ Supporto diretto	✅ Supporto diretto
Identità agente	✅ Tramite estensioni	✅ Parametri di query
Convalida dei token	✅ Middleware	✅ /Punto finale di convalida
Downstream API	✅ IDownstreamApi	✅ Endpoint /DownstreamApi
Microsoft Graph	✅ Integrazione di Graph SDK	⚠️ Tramite DownstreamApi
Prestazioni	⚡ In-process (più veloce)	🔄 Overhead HTTP
Configuration	`appsettings.json` e codice	`appsettings.json` e Variabili di ambiente
Debug	✅ Debug .NET standard	⚠️ Debug dei contenitori
Ricaricamento rapido	✅ Ricaricamento rapido di .NET	❌ Riavvio del contenitore
Aggiornamenti dei pacchetti	📦 Pacchetti NuGet	🐳 Immagini del contenitore
Licenza	MIT	MIT

Per indicazioni dettagliate, vedere La Guida al confronto .

Microsoft Entra SDK per AgentID è pronto per la produzione?

Sì, l'SDK è pronto per la produzione. Vedere le versioni di GitHub per le linee guida più recenti per lo stato di rilascio e l'idoneità per la produzione.

Sono disponibili immagini del contenitore?

Sì: fare riferimento alla Guida all'installazione per le immagini e i tag di versione disponibili.

È possibile eseguire l'SDK all'esterno di Kubernetes?

Sì: fare riferimento alla Guida all'installazione per istruzioni sull'esecuzione dell'SDK in Docker Compose o in altri ambienti contenitore (Docker Compose, Istanze di Azure Container, AWS ECS/Fargate, Docker autonomo).

Quali porte di rete vengono usate dall'SDK?

Porta predefinita: 5000 (configurabile)

L'SDK deve essere accessibile solo dal contenitore dell'applicazione, mai esposto esternamente.

Distribuzione

Informazioni sulle opzioni di distribuzione, i requisiti delle risorse e l'integrazione con piattaforme contenitore come Docker Compose e Kubernetes.

Quali sono i requisiti delle risorse?

Sì: vedere la Guida all'installazione per i requisiti delle risorse.

È possibile usare l'SDK con Docker Compose?

Sì: vedere la Guida all'installazione per gli esempi di Docker Compose.

Come si esegue la distribuzione nel servizio Azure Kubernetes con identità gestita?

Sì: seguire la Guida all'installazione nella sezione Servizio Azure Kubernetes con identità gestita .

Configurazione

Configurare le impostazioni dell'SDK, incluse le credenziali, le API downstream e le sostituzioni delle richieste per soddisfare i requisiti di distribuzione.

È disponibile un riferimento alla configurazione?

Sì: vedere Le informazioni di riferimento sulla configurazione per le opzioni di configurazione dettagliate.

È consigliabile usare segreti client o certificati?

Preferisce i certificati rispetto ai segreti client:

Maggiore sicurezza
Più facile ruotare
Consigliato da Microsoft

Migliore: usare l'identità gestita in Azure (nessuna credenziale necessaria)

Per indicazioni, vedere Procedure consigliate per la sicurezza.

È possibile configurare più API downstream?

Sì. Configurare ognuno con la propria sezione:

DownstreamApis__Graph__BaseUrl: "https://graph.microsoft.com/v1.0"
DownstreamApis__Graph__Scopes: "User.Read"

DownstreamApis__MyApi__BaseUrl: "https://api.contoso.com"
DownstreamApis__MyApi__Scopes: "api://myapi/.default"

Come si esegue l'override della configurazione per richiesta?

Usare i parametri di query sugli endpoint:

# Override scopes
GET /AuthorizationHeader/Graph?optionsOverride.Scopes=User.Read

# Request app token instead of OBO
GET /AuthorizationHeader/Graph?optionsOverride.RequestAppToken=true

# Override relative path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

Per tutte le opzioni, vedere Informazioni di riferimento sulla configurazione .

Identità agente

Le identità dell'agente consentono scenari in cui un'applicazione agente può operare in modo autonomo o per conto di un utente, con isolamento del contesto e ambito appropriati.

Che cosa sono le identità dell'agente?

Le identità dell'agente consentono scenari in cui un'applicazione agente agisce:

In modo autonomo : nel proprio contesto applicativo
Interattivo : per conto dell'utente che lo ha chiamato

Per una documentazione completa, vedere Identità agente .

Quando è consigliabile usare la modalità agente autonomo?

Usare la modalità agente autonomo per:

Elaborazione batch senza contesto utente
Attività in background
Operazioni da sistema a sistema
Processi pianificati

Esempio:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>

Quando è consigliabile usare la modalità agente interattivo?

Usare la modalità agente delegato per:

Applicazioni dell'agente interattivo
Assistenti di intelligenza artificiale che agiscono per conto degli utenti
Automazione con ambito utente
Flussi di lavoro personalizzati

Esempio:

GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>&AgentUsername=user@contoso.com

Perché non è possibile usare AgentUsername senza AgentIdentity?

AgentUsername è un modificatore che specifica l'utente di cui opera l'agente per conto di . È necessario AgentIdentity specificare il contesto dell'agente da usare. Senza AgentIdentity, il parametro non ha alcun significato.

Perché AgentUsername e AgentUserId si escludono a vicenda?

Sono due modi per identificare lo stesso utente:

AgentUsername - Nome entità utente (UPN)
AgentUserId - ID oggetto (OID)

Consentire a entrambi di creare ambiguità. Scegliere quello più adatto allo scenario:

Usare AgentUsername quando si dispone dell'UPN dell'utente
Usare AgentUserId quando si dispone dell'ID oggetto dell'utente

Utilizzo API

L'SDK espone diversi endpoint HTTP per l'acquisizione, la convalida e le chiamate API downstream con supporto per i flussi autenticati e non autenticati.

Quali endpoint espone l'SDK?

/Validate - Convalidare il token e restituire le attestazioni
/AuthorizationHeader/{serviceName} - Ottenere l'intestazione dell'autorizzazione con token
/AuthorizationHeaderUnauthenticated/{serviceName} - Ottenere il token senza token utente in ingresso
/DownstreamApi/{serviceName} - Chiamare direttamente l'API downstream
/DownstreamApiUnauthenticated/{serviceName} - Chiamare l'API downstream senza token utente in ingresso
/healthz - Probe di integrità

Per informazioni dettagliate, vedere Informazioni di riferimento sugli endpoint .

Qual è la differenza tra endpoint autenticati e non autenticati?

Autenticato: richiedere il token di connessione nell'intestazione Authorization (per i flussi OBO) Non autenticato: non convalidare il token in ingresso (solo app o scenari di agente)

Come si convalida un token utente?

GET /Validate
Authorization: Bearer <user-token>

La risposta include tutte le attestazioni del token.

Come si ottiene un token di accesso per un'API downstream?

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

La risposta include l'intestazione di autorizzazione pronta per l'uso con l'API downstream.

È possibile eseguire l'override del metodo HTTP o del percorso per richiesta?

Sì, usando i parametri di query:

# Override method
GET /DownstreamApi/Graph?optionsOverride.HttpMethod=POST

# Override path
GET /DownstreamApi/Graph?optionsOverride.RelativePath=me/messages

Memorizzazione nella cache dei token

L'SDK memorizza automaticamente nella cache i token in memoria per ottimizzare le prestazioni e ridurre le richieste di acquisizione di token ridondanti.

I token della cache dell'SDK sono?

Sì: l'SDK memorizza nella cache i token in memoria per impostazione predefinita.

Quanto tempo vengono memorizzati nella cache dei token?

I token vengono memorizzati nella cache fino alla scadenza, quindi aggiornati automaticamente. La durata esatta dipende dalla durata del token (in genere 1 ora per i token ENTRA ID).

È possibile disabilitare la memorizzazione nella cache?

La memorizzazione nella cache dei token è automatica e ottimizzata. Attualmente non è disponibile alcuna opzione per disabilitarla.

La cache dei token è condivisa tra le istanze dell'SDK?

No: ogni istanza dell'SDK mantiene la propria cache in memoria. Nelle distribuzioni a disponibilità elevata ogni pod ha una memorizzazione nella cache indipendente.

Security

Le distribuzioni secure SDK seguono le procedure consigliate per l'identità e la protezione dei dati di Microsoft Entra, tra cui l'utilizzo delle identità gestite, l'isolamento della rete e la corretta gestione delle credenziali.

È sicuro eseguire l'SDK?

Sì: vedere Le procedure consigliate per la sicurezza per le procedure consigliate per la sicurezza.

È necessario esporre l'SDK esternamente?

Mai : l'SDK deve essere accessibile solo dal contenitore dell'applicazione. Per procedure consigliate per la sicurezza dettagliate, vedere Procedure consigliate per la sicurezza.

Come proteggere l'SDK?

Per indicazioni complete, vedere Procedure consigliate per la sicurezza .

Quali credenziali è necessario usare?

Ordine di preferenza:

Identità gestita (Azure) - Più sicuro, nessuna credenziale
Certificati : è possibile ruotare secure,
Segreti client - Meno preferito, mantenere l'insieme di credenziali sicuro

L'SDK è certificato per la conformità?

Controllare il repository GitHub per informazioni sulla conformità correnti.

Performance

Le prestazioni dell'SDK dipendono dall'efficacia della memorizzazione nella cache dei token e dalla latenza di round trip di rete, con tempi di risposta tipici compresi tra 10 e 50 ms per i token memorizzati nella cache.

Qual è l'impatto sulle prestazioni dell'SDK?

Round trip HTTP tipico: 10-50 ms

La memorizzazione nella cache dei token riduce al minimo le acquisizioni ripetute. La prima richiesta è più lenta (acquisizione di token), le richieste successive usano token memorizzati nella cache.

In che modo le prestazioni dell'SDK vengono confrontate con le librerie in-process?

Le librerie in-process sono più veloci (senza round trip di rete), ma l'SDK fornisce:

Accesso indipendente dalla lingua
Configurazione centralizzata
Cache dei token condivisi tra servizi
Scalabilità semplificata

Per informazioni dettagliate, vedere La Guida al confronto .

È possibile ridimensionare l'SDK orizzontalmente?

Sì. Distribuire più repliche SDK usando la distribuzione di Kubernetes. Ogni pod gestisce la memorizzazione nella cache dei token indipendenti.

Migration

Il passaggio da Microsoft.Identity.Web all'SDK offre vantaggi nel supporto multilingue, nella configurazione centralizzata e nella scalabilità semplificata tra i servizi.

È possibile eseguire la migrazione da Microsoft.Identity.Web a Microsoft Entra SDK per AgentID?

Sì: vedere la Guida al confronto per i passaggi dettagliati della migrazione

Support

Ottenere assistenza sui problemi, trovare documentazione aggiuntiva e accedere alle risorse della community tramite canali ufficiali.

Dove si segnalano i bug?

Segnalare i problemi nel repository GitHub usando il modello Entra ID.

Risoluzione dei problemi

Quando si verificano problemi con l'SDK, vedere la guida completa alla risoluzione dei problemi per i passaggi di diagnostica, i problemi comuni e le soluzioni nella Guida alla risoluzione dei problemi.