Microsoft Entra SDK per AgentID: Panoramica

Microsoft Entra SDK per AgentID è un servizio web containerizzato che gestisce l'acquisizione e la convalida dei token, oltre a effettuare le chiamate API downstream in modo sicuro. 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à in Microsoft Entra SDK per AgentID, 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 sta costruendo con Kubernetes, servizi containerizzati con Docker o moderni microservizi su Azure, il Microsoft Entra SDK per AgentID offre un modo standardizzato per gestire l'autenticazione e l'autorizzazione nelle applicazioni native cloud.

Che cos'è Microsoft Entra SDK per AgentID?

Microsoft Entra SDK per AgentID 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 di identità direttamente nel codice dell'applicazione, Microsoft Entra SDK per AgentID gestisce la gestione dei token, la convalida e le chiamate 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 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 → la tua API Web → Microsoft Entra SDK per AgentID → ID Microsoft Entra

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

Security

Assicurarsi che la distribuzione di Microsoft Entra SDK per AgentID segua le procedure consigliate per il funzionamento sicuro. 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 AgentID, è 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 AgentID o Microsoft.Identity.Web

Per indicazioni dettagliate sulla scelta tra i due approcci, vedere Confronto con Microsoft.Identity.Web .

Convalida dei token

Microsoft Entra SDK per AgentID convalida sia i token di accesso che i token ID emessi da Microsoft Entra ID, verificando le firme rispetto alle chiavi pubbliche di Microsoft Entra ID, controllando le ore 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 del token

• Flusso on-Behalf-Of OAuth 2.0 - Delegare il contesto utente alle API downstream
• Credenziali del client - Autenticazione tra applicazioni
• Identità gestita - Autenticazione del servizio di 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 AgentID 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à a Microsoft Entra SDK per AgentID 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 AgentID]:::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 nel repository Microsoft-Identity-Web
• Consultare le guide alla risoluzione dei problemi relativi all'ID Entra di Microsoft

Risorse aggiuntive

• Documentazione di Microsoft Entra ID
• Documentazione di Microsoft Identity Platform
• Repository Web di Microsoft Identity
• Documentazione di Kubernetes
• Documentazione di Docker