Guida introduttiva: Accedere agli utenti e chiamare le API downstream con l'SDK di Microsoft Entra per l'ID agente in Python

In questa guida introduttiva si usa un'app Web di esempio per informazioni su come accedere a utenti o agenti e chiamare le API downstream usando la propria identità. L'app di esempio usa l'SDK di Microsoft Entra per l'ID agente per convalidare i token utente per l'accesso delegato e usa l'identità dell'applicazione per la comunicazione da servizio a servizio con API downstream come Microsoft Graph.

Prerequisiti

Installare il gestore di pacchetti UV. UV è un programma di installazione rapido di pacchetti Python e risolutore, scritto in Rust.
Installare Docker Desktop.
Un account Azure con una sottoscrizione attiva. Se non ne hai già uno, crea gratuitamente un account.
Questo account Azure deve disporre delle autorizzazioni per gestire le applicazioni. Uno dei ruoli di Microsoft Entra seguenti include le autorizzazioni necessarie:
- Amministratore di applicazioni
- Sviluppatore di applicazioni
Inquilino della forza lavoro. Puoi utilizzare la directory predefinita oppure configurare un nuovo tenant.

Creare e configurare l'applicazione Microsoft Entra

Per completare il resto dell'avvio rapido, è necessario prima registrare un'applicazione in Microsoft Entra ID.

Creare la registrazione dell'applicazione

Per creare la registrazione dell'app, seguire questa procedura:

Accedere al Interfaccia di amministrazione di Microsoft Entra almeno come Application Developer.
Se si ha accesso a più tenant, usare l'icona Impostazioni nel menu in alto per passare al tenant in cui si vuole registrare l'applicazione.
Passare a Entra ID>Registrazioni app e selezionare Nuova registrazione.
Immettere un nome significativo per l'app, ad esempio identity-client-app. Gli utenti dell'app visualizzano questo nome e possono essere modificati in qualsiasi momento. È possibile avere più registrazioni dell'app con lo stesso nome.

In Tipi di account supportatispecificare chi può usare l'applicazione. Selezionare Solo account in questa directory organizzativa per la maggior parte delle applicazioni. Per altre informazioni su ogni opzione, vedere la tabella .

Tipi di conto supportati	Description
Solo gli account in questa directory organizzativa	Per app a singolo tenant per l'uso esclusivo da parte di utenti (o ospiti) nel tuo tenant .
Account in qualsiasi directory organizzativa	Per le app multitenant e si vuole che gli utenti in qualsiasi tenant di Microsoft Entra possano usare l'applicazione. Ideale per applicazioni SaaS (Software-as-a-Service) che si intende fornire a più organizzazioni.
Account in qualsiasi directory organizzativa e account personali di Microsoft	Per le app multitenant che supportano account di Microsoft aziendali e personali (ad esempio, Skype, Xbox, Live, Hotmail).
account Personale Microsoft	Per le app usate solo dagli account Microsoft personali (ad esempio, Skype, Xbox, Live, Hotmail).

Selezionare Registra per completare la registrazione dell'app.
Viene visualizzata la pagina panoramica dell'applicazione. Registrare i valori seguenti dalla pagina Panoramica dell'applicazione per usarli in un secondo momento:
- ID applicazione (cliente)
- ID della directory (cliente)

Aggiungere un URI di reindirizzamento

L'app di esempio Python usa l'autenticazione interattiva con un flusso di accesso basato su browser. Configurare un URI di reindirizzamento per gestire la risposta di autenticazione:

Nella registrazione dell'app, in Gestisci selezionare Autenticazione.
Selezionare Aggiungi una piattaforma.
Selezionare Applicazioni per dispositivi mobili e desktop.
In URI di reindirizzamento personalizzati immettere http://localhost.
Seleziona Configura.

Aggiungere le credenziali client

L'SDK di Microsoft Entra per l'ID agente usa le credenziali client per autenticare e ottenere token per le API downstream. Per lo sviluppo e il test locali, usare un certificato autofirmato per l'autenticazione.

Generare un certificato autofirmato

Eseguire PowerShell come amministratore e usare i comandi seguenti per generare un certificato autofirmato:

# Generate a self-signed certificate
$cert = New-SelfSignedCertificate `
    -Subject "CN=AgentID-Client-Certificate" `
    -CertStoreLocation "Cert:\CurrentUser\My" `
    -KeyExportPolicy Exportable `
    -KeySpec Signature `
    -KeyLength 2048 `
    -KeyAlgorithm RSA `
    -HashAlgorithm SHA256 `
    -NotAfter (Get-Date).AddDays(7)

# Export public key (CER) for upload to Azure
$cerPath = "agentid-client-certificate.cer"
Export-Certificate -Cert $cert -FilePath $cerPath

# Export private key (PFX) for the Agent ID SDK container
# Replace <your-pfx-password> with a strong password and store it securely (for example, in a secret store).
$pfxPath = "agentid-client-certificate.pfx"
$certPassword = ConvertTo-SecureString -String "<your-pfx-password>" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath $pfxPath -Password $certPassword

Write-Host "Certificate generated successfully!"
Write-Host "CER file (public key): $cerPath"
Write-Host "PFX file (private key): $pfxPath"
Write-Host "Certificate Thumbprint: $($cert.Thumbprint)"

Registrare l'impronta digitale del certificato visualizzata nell'output di PowerShell. È necessario verificare che il certificato nel Interfaccia di amministrazione di Microsoft Entra corrisponda a quello installato in locale.

Caricare il certificato in Microsoft Entra ID

Seguire questa procedura per caricare il file .cer creato nella directory corrente nel Interfaccia di amministrazione di Microsoft Entra:

Aprire la registrazione dell'app nel Interfaccia di amministrazione di Microsoft Entra
In Gestisci, selezionare Certificati e segreti.
Nella scheda Certificati selezionare Carica certificato.
Selezionare il .cer file generato, ad esempio agentid-client-cert.cer.
Specificare una descrizione, ad esempio "AgentID Local Development Certificate".
Seleziona Aggiungi.
Registrare l'impronta digitale del certificato visualizzata (deve corrispondere a quella generata con il certificato).

Annotazioni

Per gli ambienti di produzione, usare i certificati rilasciati da un'autorità di certificazione (CA) attendibile e archiviarli in Azure Key Vault con accesso all'identità gestita. Usate certificati autofirmati solo per lo sviluppo e il test locali.

Configurare le autorizzazioni dell'API

Seguire questa procedura per configurare le autorizzazioni delegate per Microsoft Graph. Con queste autorizzazioni, l'applicazione client può eseguire operazioni per conto dell'utente connesso, ad esempio la lettura del messaggio di posta elettronica.

Nella registrazione dell'app, in Manage, selezionare Autorizzazioni API>Aggiungi un'autorizzazione>Microsoft Graph.
Seleziona Autorizzazioni delegate. Microsoft Graph espone molte autorizzazioni, con il più comunemente usato nella parte superiore dell'elenco.
In Seleziona autorizzazioni selezionare e aggiungere User.Read.

Configurare le autorizzazioni dell'applicazione

Per testare i flussi solo applicazione in cui Agent ID SDK chiama le API usando la propria identità (senza un contesto utente), configurare le autorizzazioni dell'applicazione:

Nella pagina Accesso API selezionare Aggiungi un'autorizzazione>Microsoft Graph.
Seleziona Autorizzazioni applicazione.
In Seleziona autorizzazioni cercare e selezionare User.Read.All.
Selezionare Aggiungi autorizzazioni.
Selezionare Concedi consenso amministratore per [Tenant] e confermare.

Annotazioni

Le autorizzazioni dell'applicazione richiedono il consenso dell'amministratore. Senza questo passaggio, gli endpoint solo applicativi nella sezione di test falliscono.

Esporre un'API (per i test di convalida dei token)

Per chiamare l'endpoint di /validate Agent ID SDK con token rilasciati specificamente per l'applicazione (usando l'ambito api://<application-client-id>/access_as_user ), è necessario completare questo passaggio. Se si testano solo gli scenari Microsoft Graph con autorizzazioni delegate, è possibile ignorare questa sezione. Seguire questa procedura per esporre un'API contenente gli ambiti necessari:

In Gestisci selezionare Esporre un'API.
Nella parte superiore della pagina, selezionare Aggiungi accanto a URI ID applicazione. Per impostazione predefinita, questo valore è api://<application-client-id>. L'URI dell'ID applicazione funge da prefisso per gli ambiti a cui verrà fatto riferimento nel codice dell'API e deve essere univoco a livello globale. Seleziona Salva.
Selezionare Aggiungi un ambito come illustrato:
Specificare quindi gli attributi dell'ambito nel riquadro Aggiungi un ambito , come indicato di seguito:
- Nome ambito: access_as_user
- Chi può fornire il consenso: amministratori e utenti
- Nome visualizzato del consenso amministratore: Accedi allo SDK dell'ID agente come utente
- Descrizione del consenso amministratore: consentire l'accesso alle API dell'SDK dell'ID agente come utente autenticato
- Stato: Attivato
Seleziona Aggiungi ambito.

Avvia Microsoft Entra SDK per AgentID

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.

Creare un file di configurazione

Agent ID SDK richiede un file di configurazione per connettersi all'applicazione Microsoft Entra. Creare una nuova directory per la configurazione e creare un appsettings.json file:

# Create a directory for the Agent ID SDK configuration
New-Item -ItemType Directory -Path "agentid-config" -Force
cd agentid-config

# Create the appsettings.json file
New-Item -ItemType File -Path "appsettings.json"

Aprire appsettings.json nell'editor di testo preferito e aggiungere la configurazione seguente, sostituendo i valori segnaposto con i dettagli dell'applicazione Microsoft Entra:

{
    "AzureAd": {
        "Instance": "https://login.microsoftonline.com/",
        "TenantId": "YOUR_TENANT_ID_HERE",
        "ClientId": "YOUR_CLIENT_ID_HERE",
        "ClientCredentials": [
            {
                "SourceType": "Path",
                "CertificateStorePath": "agentid-client-certificate.pfx",
                "CertificateDistinguishedName": "<your-pfx-password>"
            }
        ]
    },
    "DownstreamApis": {
        "me": {
            "BaseUrl": "https://graph.microsoft.com/v1.0/",
            "RelativePath": "me",
            "Scopes": [ "User.Read" ]
        }
    },
    "Logging": {
        "LogLevel": {
            "Default": "Information",
            "Microsoft.AspNetCore": "Warning"
        }
    },
    "AllowedHosts": "*"
}

Eseguire il pull e l'esecuzione del contenitore AGENT ID SDK

Agent ID SDK è disponibile come immagine del contenitore predefinita dall'Microsoft Container Registry (MCR). Prima di eseguire il pull dell'immagine del contenitore, verificare che Docker Desktop sia in esecuzione. Se Docker non è in esecuzione, aprire Docker Desktop e attendere che lo stato visualizzi "Docker Desktop è in esecuzione".

Passare alla directory di configurazione ed eseguire i comandi seguenti:

# Navigate to your config directory
cd agentid-config

# Pull the Agent ID SDK container image from MCR
docker pull mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-azurelinux3.0-distroless

# Run the container
docker run -d `
    --name agentid-sdk `
    -p 5178:8080 `
    -e ASPNETCORE_ENVIRONMENT=Development `
    mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-azurelinux3.0-distroless

# Copy configuration files into the container
docker cp appsettings.json agentid-sdk:/app/appsettings.json
docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx

# Restart the container to apply the configuration
docker restart agentid-sdk

Annotazioni

Per gli host Windows, usare la variante del contenitore Windows: mcr.microsoft.com/entra-sdk/auth-sidecar:1.0.0-rc.2-windows

È possibile gestire il contenitore AGENT ID SDK usando i comandi Docker seguenti:

Visualizzare i log dei contenitori: docker logs agentid-sdk
Visualizzare i log in tempo reale: docker logs -f agentid-sdk
Arrestare il contenitore: docker stop agentid-sdk
Avviare di nuovo il contenitore: docker start agentid-sdk
Rimuovere il contenitore: docker rm agentid-sdk

Verificare che il contenitore sia in esecuzione

È possibile verificare se il contenitore SDK ID Agente è in esecuzione correttamente chiamando l'endpoint di controllo di integrità,/healthz :

Invoke-RestMethod -Uri "http://localhost:5178/healthz" -ErrorAction SilentlyContinue

Questo endpoint restituisce Healthy, che conferma che Agent ID SDK è in esecuzione correttamente e pronto per gestire le richieste. Non terminare l'Agent ID SDK durante il test. Il contenitore deve continuare a funzionare in background affinché tutte le chiamate API e di autenticazione dall'app Python possano funzionare.

Eseguire l'app di esempio Python

L'app di esempio Python illustra come usare Microsoft Entra SDK per l'ID agente per le chiamate api e di autenticazione. Agent ID SDK viene eseguito come servizio Web locale e funge da proxy di autenticazione. Convalida i token utente e chiama API downstream come Microsoft Graph per conto dell'utente.

L'esempio include Python script che mostrano due modelli di autenticazione:

Autorizzazioni delegate: Agent ID SDK convalida il token utente e chiama le API per conto dell'utente connesso.
Autorizzazioni dell'applicazione: Agent ID SDK usa la propria identità per chiamare le API senza un contesto utente.

Questo approccio centralizza la gestione dei token e l'accesso api in un singolo servizio che le applicazioni possono utilizzare tramite semplici richieste HTTP.

Clonare o scaricare l'app di esempio Python

Scaricare l'app di esempio di Python ed estrarla in una directory locale. In alternativa, clona il repository aprendo un prompt dei comandi, passando al percorso del progetto desiderato e eseguendo il comando seguente:

git clone https://github.com/AzureAD/microsoft-identity-web.git
cd microsoft-identity-web/tests/DevApps/SidecarAdapter/python

L'app di esempio contiene gli script di Python seguenti:

get_token.py: acquisisce i token di accesso utente tramite il Libreria di Autenticazione Microsoft (MSAL).
main.py : interfaccia della riga di comando che chiama gli endpoint di Agent ID SDK e visualizza le risposte JSON.
MicrosoftIdentityWebSidecarClient.py – wrapper client HTTP per gli endpoint /Validate, /AuthorizationHeader e /DownstreamApi dell'SDK ID agente.

Gli script Python usano il parametro me quando si chiamano gli endpoint di Agent ID SDK. Questo parametro fa riferimento alla configurazione dell'API a valle denominata "me" negli SDK dell'ID agenteappsettings.json:

"DownstreamApis": {
    "me": {
        "BaseUrl": "https://graph.microsoft.com/v1.0/",
        "RelativePath": "me",
        "Scopes": [ "User.Read" ]
    }
}

Quando si chiama un endpoint di Agent ID SDK con il parametro me, l'SDK usa l'URL di base e il percorso relativo dalla configurazione per costruire l'endpoint API completo, richiede gli ambiti specificati e chiama l'endpoint Microsoft Graph /me per recuperare il profilo dell'utente connesso. È possibile aggiungere altre configurazioni api downstream a appsettings.json con nomi ed endpoint diversi per chiamare API aggiuntive.

Testare l'interazione tra l'SDK di Microsoft Entra per l'ID agente e l'app Python

Questa guida introduttiva illustra un modello di autenticazione a tre livelli:

Autenticazione utente: si ottiene un token di accesso utente utilizzando MSAL per Python. Questo token dimostra l'identità dell'utente.
Convalida dei token: Agent ID SDK convalida il token utente per assicurarsi che sia autenticato ed emesso per l'applicazione.
Token exchange: L'SDK Agent ID utilizza il flusso On-Behalf-Of (OBO) per ottenere un nuovo token destinato a Microsoft Graph, sostituendo il token utente esistente, e poi chiama l'API.

Per gli scenari di sola applicazione, Agent ID SDK ignora l'autenticazione utente e usa le proprie credenziali client per acquisire direttamente i token. L'SDK centralizza questa logica di autenticazione, pertanto l'applicazione Python deve eseguire richieste HTTP semplici senza gestire flussi OAuth complessi.

Acquisire un token di accesso utente

Prima di testare gli endpoint di Agent ID SDK, ottenere un token di accesso valido. Lo script get_token.py usa MSAL per Python per acquisire i token in modo interattivo tramite un flusso di accesso basato su browser.

Ambiti e gruppi di destinatari dei token:

L'ambito richiesto determina il gruppo di destinatari del token (aud attestazione), che deve corrispondere all'endpoint che si sta chiamando:

Per i test di convalida dei token, usare api://<client-id>/access_as_user per testare l'endpoint /validate
Per il test di Microsoft Graph, acquisire un nuovo token con ambito User.Read per testare gli endpoint /authorizationheader e /downstreamapi.

Usare i comandi seguenti per impostare le variabili di configurazione e acquisire un token:

# Set your configuration
$clientId = "YOUR_CLIENT_ID_HERE"
$tenantId = "YOUR_TENANT_ID_HERE"
$authority = "https://login.microsoftonline.com/$tenantId"

# For testing Agent ID SDK APIs (if you exposed the API)
$scope = "api://$clientId/access_as_user"

# Or for testing Microsoft Graph directly
# $scope = "User.Read"

# Acquire token
$token = uv run --with msal get_token.py --client-id $clientId --authority $authority --scope $scope

Quando si esegue il comando acquire token, lo script avvia un flusso di accesso interattivo basato su browser. Questa autenticazione del browser si verifica solo alla prima esecuzione. Al termine dell'autenticazione, il token viene memorizzato nella cache in locale per un uso successivo. Il token di accesso viene quindi stampato nella console e archiviato nella $token variabile di PowerShell per l'uso nei comandi successivi.

Testare il Microsoft Entra SDK per gli endpoint di Agent ID con autorizzazioni delegate

Dopo aver ottenuto un token utente valido, è possibile testare gli endpoint principali di Agent ID SDK. Queste operazioni usano autorizzazioni delegate, quindi l'SDK agisce per conto dell'utente connesso.

Prima di tutto, impostare l'URL di base dell'SDK:

$side_car_url = "http://localhost:5178"

1. Convalidare il token utente

L'endpoint /validate richiede un token emesso specificamente per l'applicazione usando l'ambito api://<client-id>/access_as_user . Prima di testare la convalida dei token, assicurarsi di completare i passaggi nella sezione "Esporre un'API". Usare il comando seguente per chiamare l'endpoint /validate .

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" validate

Risposta prevista:

L'endpoint /validate verifica che il token sia valido ed estrae le informazioni sulle attestazioni:

{
  "protocol": "Bearer",
  "token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6...",
  "claims": {
    "aud": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "iss": "https://login.microsoftonline.com/...",
    "name": "Your Name",
    "upn": "your.email@domain.com"
  }
}

Questa risposta conferma che:

Il formato del token è corretto (token di tipo Bearer)
Il token viene emesso dall'autorità prevista
Il gruppo di destinatari (aud) corrisponde all'applicazione
Le attestazioni di identità utente sono presenti e valide

2. Ottenere un'intestazione di autorizzazione per Microsoft Graph

L'endpoint /authorizationheader recupera un'intestazione di autorizzazione formattata correttamente per chiamare le API downstream:

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" get-auth-header me

Questo endpoint:

Convalida il token utente in ingresso
Acquisisce un nuovo token per Microsoft Graph per conto dell'utente
Restituisce l'intestazione di autorizzazione formattata

3. Chiamare Microsoft Graph tramite il Microsoft Entra SDK per l'AgentID

L'endpoint /downstreamapi chiama direttamente Microsoft Graph e restituisce la risposta:

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" invoke-downstream me

Risposta prevista:

{
  "statusCode": 200,
  "headers": {...},
  "content": {
    "displayName": "Your Name",
    "mail": "your.email@domain.com",
    "userPrincipalName": "your.email@domain.com"
  }
}

Il me parametro corrisponde alla configurazione dell'API downstream definita in appsettings.json. The Agent ID SDK:

Convalida il token utente
Acquisisce un nuovo token per Microsoft Graph usando il flusso OBO (on-behalf-of)
Chiama l'endpoint /me in Microsoft Graph
Restituisce i dati del profilo utente

4. Eseguire l'override degli ambiti predefiniti e fornire un corpo della richiesta

È possibile personalizzare le chiamate API eseguendo l'override degli ambiti predefiniti configurati in appsettings.json o fornendo un corpo della richiesta per le operazioni di scrittura.

uv run --with requests main.py --base-url $side_car_url --authorization-header "Bearer $token" --scope <scopes> invoke-downstream <api-name> --body-file <path-to-file>

Questo approccio è utile quando:

Test di livelli di autorizzazione diversi. Ad esempio, è possibile specificare ambiti diversi come --scope User.Read Mail.Read per richiedere autorizzazioni aggiuntive
L'API downstream richiede ambiti non configurati per impostazione predefinita
È necessario richiedere autorizzazioni aggiuntive in modo dinamico
Quando si chiamano le API che richiedono un corpo della richiesta ,ad esempio la creazione o l'aggiornamento delle risorse, si aggiunge il parametro facoltativo --body-file usato per le operazioni POST/PUT

Testare gli endpoint solo per applicazioni

Lo SDK di Microsoft Entra per l'ID agente supporta anche i flussi solo applicazione. In questi flussi, Agent ID SDK usa la propria identità dell'app anziché agire per conto di un utente. Questi endpoint non richiedono un'intestazione di autorizzazione utente.

Annotazioni

I flussi solo per applicazioni richiedono che la registrazione dell'applicazione abbia autorizzazioni delle applicazioni (ad esempio User.Read.All) non solo autorizzazioni delegate in Microsoft Entra ID. Un amministratore deve concedere il consenso a queste autorizzazioni prima di poter testare questi endpoint.

Ottenere l'intestazione di autorizzazione senza contesto utente

Usare questo endpoint per recuperare un'intestazione di autorizzazione per chiamare Microsoft Graph con l'identità propria dell'SDK di Agent ID.

uv run --with requests main.py --base-url $side_car_url get-auth-header-unauth me

Questo endpoint:

Usa le credenziali del client dell'SDK Agent ID (identità dell'app) per l'autenticazione.
Acquisisce un token di accesso solo app per Microsoft Graph
Restituisce l'intestazione dell'autorizzazione

Chiamare Microsoft Graph senza contesto utente

Usare questo endpoint per chiamare Microsoft Graph direttamente usando l'identità di Agent ID SDK.

uv run --with requests main.py --base-url $side_car_url invoke-downstream-unauth me

In questo esempio viene illustrata la comunicazione da servizio a servizio in cui:

Nessun utente è coinvolto nel flusso di autenticazione
Agent ID SDK esegue l'autenticazione usando il proprio ID client e il proprio certificato
La chiamata API usa le autorizzazioni dell'applicazione, non le autorizzazioni delegate
Questo modello è ideale per i servizi in background, l'elaborazione batch o le attività automatizzate

Comprendere le risposte

Struttura della risposta di convalida dei token

La risposta di convalida fornisce informazioni dettagliate sul token:

Campo	Description
`protocol`	Schema di autenticazione (sempre "Bearer" per i token OAuth 2.0)
`token`	Token di accesso originale (troncato negli esempi)
`claims`	Coppie chiave-valore estratte dal payload del token
`claims.aud`	Destinatari desiderati (ID cliente)
`claims.iss`	Emittente del token (Microsoft Entra ID)
`claims.name`	Nome visualizzato dell'utente connesso
`claims.upn`	Nome principale utente (indirizzo di posta elettronica)

Microsoft Graph struttura di risposta alle chiamate

Campo	Description
`statusCode`	Codice di stato HTTP da Microsoft Graph (200 = esito positivo)
`headers`	Intestazioni di risposta dalla chiamata API
`content`	Dati effettivi restituiti da Microsoft Graph
`content.displayName`	Nome visualizzato dell'utente nella directory
`content.mail`	Indirizzo di posta elettronica dell'utente
`content.userPrincipalName`	UPN dell'utente

Risoluzione dei problemi comuni

Se si verificano errori durante il test dell'SDK di Microsoft Entra per gli endpoint ID agente, verificare le soluzioni seguenti ai problemi comuni:

Problema	Soluzione
Errori di "Connessione rifiutata"	Verificare che il contenitore AGENT ID SDK sia in esecuzione: `docker ps -a`. Se lo stato del contenitore è "Exited", controllare i log: `docker logs agentid-sdk`. Riavviare il contenitore: `docker start agentid-sdk` e verificare l'endpoint di integrità: `Invoke-RestMethod -Uri "http://localhost:5178/healthz"`.
Il contenitore restituisce un errore interno del server 500	Visualizza il log del contenitore per errori dettagliati: `docker logs agentid-sdk`. Cause comuni: JSON non valido in `appsettings.json`, percorso del certificato non corretto, password del certificato errata o valori TenantId/ClientId mancanti.
Errori relativi al certificato non trovato	Verificare che il file PFX sia stato copiato correttamente: `docker exec agentid-sdk ls -la /app/agentid-client-certificate.pfx`. Se mancante, copiarlo di nuovo: `docker cp agentid-client-certificate.pfx agentid-sdk:/app/agentid-client-certificate.pfx` e riavviare: `docker restart agentid-sdk`.
Errori di "Token non valido" o "Convalida del gruppo di destinatari non riuscita"	Verifica che l'audience (claim `aud`) del token corrisponda all'ID cliente. Per l'endpoint `/validate` , usare l'ambito `api://<client-id>/access_as_user` . Per le chiamate Microsoft Graph, usare `User.Read`. Cancellare la cache dei token: `Remove-Item -Path "$env:USERPROFILE\.msal_token_cache.bin" -ErrorAction SilentlyContinue`.
appsettings.json non viene caricato	Verificare che il file sia stato copiato nel contenitore: `docker exec agentid-sdk cat /app/appsettings.json`. Verificare che il codice JSON sia valido (nessun commento, sintassi corretta). Se il file è mancante o errato, copiarlo di nuovo e riavviare il contenitore.
Il contenitore non verrà avviato dopo le modifiche alla configurazione	Arrestare e rimuovere il contenitore: `docker stop agentid-sdk && docker rm agentid-sdk`. Esegui di nuovo il contenitore con i file di configurazione aggiornati seguendo la sezione "Pull e eseguire il contenitore SDK ID agente".

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-19

Accedere agli utenti e chiamare le API downstream con l'SDK di Microsoft Entra per l'ID agente in Python

Prerequisiti

Creare e configurare l'applicazione Microsoft Entra

Creare la registrazione dell'applicazione

Aggiungere un URI di reindirizzamento

Aggiungere le credenziali client

Generare un certificato autofirmato

Caricare il certificato in Microsoft Entra ID

Configurare le autorizzazioni dell'API

Configurare le autorizzazioni dell'applicazione

Esporre un'API (per i test di convalida dei token)

Avvia Microsoft Entra SDK per AgentID

Creare un file di configurazione

Eseguire il pull e l'esecuzione del contenitore AGENT ID SDK

Verificare che il contenitore sia in esecuzione

Eseguire l'app di esempio Python

Clonare o scaricare l'app di esempio Python

Testare l'interazione tra l'SDK di Microsoft Entra per l'ID agente e l'app Python

Acquisire un token di accesso utente

Testare il Microsoft Entra SDK per gli endpoint di Agent ID con autorizzazioni delegate

1. Convalidare il token utente

2. Ottenere un'intestazione di autorizzazione per Microsoft Graph

3. Chiamare Microsoft Graph tramite il Microsoft Entra SDK per l'AgentID

4. Eseguire l'override degli ambiti predefiniti e fornire un corpo della richiesta

Testare gli endpoint solo per applicazioni

Ottenere l'intestazione di autorizzazione senza contesto utente

Chiamare Microsoft Graph senza contesto utente

Comprendere le risposte

Struttura della risposta di convalida dei token

Microsoft Graph struttura di risposta alle chiamate

Risoluzione dei problemi comuni

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive