Panoramica dell'SDK di Microsoft Entra per l'ID agente

Il Microsoft Entra SDK per ID agente è un servizio Web containerizzato che gestisce l'acquisizione di token, la convalida e le chiamate API downstream protette. 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 gestione delle identità nel Microsoft Entra SDK per l'ID agente, 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.

Se si esegue la compilazione con Kubernetes, servizi in contenitori con Docker o microservizi moderni in Azure, l'SDK di Microsoft Entra per l'ID agente offre un modo standardizzato per gestire l'autenticazione e l'autorizzazione nelle applicazioni native del cloud.

Che cos'è Microsoft Entra SDK per l'ID agente?

L'SDK di Microsoft Entra per l'ID agente comunica con l'applicazione tramite un'API HTTP per l'autenticazione e l'autorizzazione, fornendo modelli di integrazione coerenti indipendentemente dallo stack di tecnologie. Invece di incorporare la logica dell'identità direttamente nel codice dell'applicazione, l'SDK di Microsoft Entra per l'ID agente gestisce le chiamate di token, convalida e API tramite richieste HTTP standard.

Questo approccio consente architetture di microservizi poliglotta in cui è possibile scrivere servizi diversi in Python, Node.js, Go, Java e altri, mantenendo al contempo modelli di autenticazione coerenti.This approach enables polyglot microservices architectures where different services can be written in Python, Node.js, Go, Java, and others while maintaining consistent authentication patterns.

L'architettura tipica è la seguente:

Applicazione client → API Web → Microsoft Entra SDK per l'ID agente → Microsoft Entra ID

Per i tag di versione e dell'immagine del contenitore più recenti, vedere l'immagine del contenitore per iniziare.

Security

Assicurarsi che l'SDK di Microsoft Entra per la distribuzione dell'ID agente segua le procedure consigliate per l'operazione sicura. L'SDK deve essere eseguito in un ambiente in contenitori con accesso di rete limitato per impedire l'accesso non autorizzato. L'esposizione pubblica dell'API SDK può causare vulnerabilità di sicurezza, ad esempio l'acquisizione di token non autorizzate.

Consultare Procedure consigliate per la sicurezza per garantire le procedure consigliate per le raccomandazioni sulla sicurezza di rete, credenziali e runtime.

Avvio rapido

Per iniziare a usare Microsoft Entra SDK per l'ID agente, è consigliabile seguire questa procedura:

1. Scegliere la distribuzione : selezionare Kubernetes, Docker o AKS
2. Configurare le impostazioni - Configurare le variabili di ambiente
3. Selezionare uno scenario : seguire un esempio guidato
4. Eseguire la distribuzione nell'ambiente di produzione - Esaminare le procedure consigliate per la sicurezza

Vantaggi principali

L'architettura separa i problemi di identità dalla logica di business, offrendo i vantaggi seguenti:

Quando usare Microsoft Entra SDK per l'ID agente o Microsoft. Identity.Web

Vedere Comparison con Microsoft. Identity.Web per indicazioni dettagliate sulla scelta tra i due approcci.

Convalida dei token

L'SDK di Microsoft Entra per l'ID agente convalida sia i token di accesso che i token ID rilasciati da Microsoft Entra ID, verificando le firme rispetto alle chiavi pubbliche di Microsoft Entra ID, controllando i tempi di scadenza e assicurandosi che i token siano destinati all'applicazione. Dopo la convalida, è possibile estrarre attestazioni, ruoli e ambiti utente per prendere decisioni informate sull'autorizzazione all'interno della logica dell'applicazione.

Creazione dell'intestazione di acquisizione/autorizzazione dei token

• Flusso on-Behalf-Of OAuth 2.0 - Delegare il contesto utente alle API downstream
• Credenziali del client - Autenticazione tra applicazioni
• Managed Identity - Autenticazione del servizio Azure nativa
• Identità agente - Modelli di agenti autonomi o delegati

Chiamate API downstream

• Acquisire e collegare automaticamente i token
• Override delle richieste facoltative (ambiti, metodo, intestazioni)
• Supporto di richieste HTTP firmate (PoP/SHR)

Scenari e esercitazioni

Le guide seguenti sono esercitazioni dettagliate complete con esempi di codice pratici che illustrano come integrare Microsoft Entra SDK per l'ID agente nelle applicazioni. Ogni scenario fornisce esempi completi di richiesta/risposta, frammenti di codice e modelli di implementazione personalizzati per linguaggi e framework di programmazione diversi.

Modelli di architettura

Un flusso tipico in cui il client chiama un'API Web, l'API delega le operazioni di identità al Microsoft Entra SDK per l'ID agente tramite endpoint HTTP. L'SDK convalida i token in ingresso usando l'endpoint /Validate , acquisisce i token usando /AuthorizationHeader e /AuthorizationHeaderUnauthenticatede può richiamare direttamente le API downstream usando /DownstreamApi e /DownstreamApiUnauthenticated.

Interagisce con Microsoft Entra ID per il rilascio di token e il recupero dei metadati open ID Connect, con l'architettura illustrata nel frammento di codice seguente:

%%{init: {
  "theme": "base",
  "themeVariables": {
    "background": "#121212",
    "primaryColor": "#1E1E1E",
    "primaryBorderColor": "#FFFFFF",
    "primaryTextColor": "#FFFFFF",
    "textColor": "#FFFFFF",
    "lineColor": "#FFFFFF",
    "labelBackground": "#000000"
  }
}}%%
flowchart LR
    classDef dnode fill:#1E1E1E,stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF
    linkStyle default stroke:#FFFFFF,stroke-width:2px,color:#FFFFFF

    client[Client Application]:::dnode -->| Bearer over HTTP | webapi[Web API]:::dnode
    subgraph Pod / Host
        webapi -->|"/Validate<br/>/AuthorizationHeader/{name}<br/>/DownstreamApi/{name}"| sidecar[Microsoft Entra SDK for Agent ID]:::dnode
    end
    sidecar -->|Token validation & acquisition| entra[Microsoft Entra ID]:::dnode

Supporto e risorse

Le risorse seguenti forniscono indicazioni complete e consentono di risolvere i problemi e le risposte alle domande comuni.

Per altre informazioni:

• Segnalare i problemi relativi al repository Microsoft-identity-web
• Consulta le guide di risoluzione dei problemi di Microsoft Entra ID

Contenuti correlati

• Guida all'installazione
• Informazioni di riferimento sulla configurazione
• Confronto con Microsoft.Identity.Web
• Procedure consigliate per la sicurezza