Guida introduttiva: Autenticare gli utenti e chiamare le API downstream con l'SDK di Microsoft Entra per l'ID dell'agente in TypeScript

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 Node.js 18.x o versione successiva.
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 TypeScript 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 acquisire i 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. I certificati autofirmati devono essere usati 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 l'esecuzione in background affinché tutte le chiamate API e di autenticazione dall'app di esempio TypeScript funzionino correttamente.

Eseguire l'app di esempio TypeScript

L'app di esempio TypeScript illustra come usare Microsoft Entra SDK per l'ID agente per convalidare i token utente. L'app è un server Express.js che convalida le richieste in ingresso tramite Agent ID SDK. Agent ID SDK può anche chiamare API downstream come Microsoft Graph per conto dell'utente.

Clonare o scaricare l'app di esempio

Scaricare l'app di esempio TypeScript 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

Dopo aver clonato il repository, passare all'app di esempio TypeScript:

cd microsoft-identity-web/tests/DevApps/SidecarAdapter/typescript

L'app di esempio TypeScript è costituita da tre file principali che interagiscono per illustrare i modelli di autenticazione con Microsoft Entra SDK per AgentID.

sidecar.ts: fornisce la SidecarClient classe , ovvero un client TypeScript che comunica con il contenitore AGENT ID SDK. Invia token di connessione all'endpoint dell'SDK /Validate dell'ID agente, riceve il token convalidato insieme alle attestazioni utente e gestisce gli errori di convalida dei token.

app.ts: un server Web Express.js che autentica tutte le richieste in ingresso. Estrae i token di connessione dall'intestazione dell'autorizzazione e li convalida usando SidecarClient. Se la convalida non riesce, il server restituisce una risposta non autorizzata 401. Quando la convalida ha esito positivo, allega le attestazioni dell'utente all'oggetto richiesta tramite req.sidecarValidation, per l'uso nei gestori di route downstream.

sidecar.test.ts: contiene test di integrazione automatizzati che verificano il flusso di autenticazione completo. Il gruppo di test inizia avviando il server Express, quindi usa il nodo MSAL per eseguire l'autenticazione interattiva del browser e acquisire un token di accesso con gli ambiti necessari. Effettua quindi una richiesta HTTP al server con il token acquisito e verifica che Agent ID SDK convalide il token correttamente prima di restituire le attestazioni utente previste.

Installa le dipendenze

Passare alla directory di esempio TypeScript e installare i pacchetti necessari:

cd d:\SDKs\microsoft-identity-web\tests\DevApps\SidecarAdapter\typescript
npm install

Configurare l'app di esempio

Prima di eseguire l'app di esempio, configurarla con i dettagli dell'applicazione come indicato di seguito:

Aprire sidecar.test.ts e aggiornare l'ID client, l'ID tenant e gli ambiti in modo che corrispondano alla registrazione dell'app.
Creare un .env file nella directory per le typescript variabili di ambiente:
```
# Create .env file
New-Item -ItemType File -Path ".env" -Force
```
Aggiungere la configurazione seguente a .env:
```
PORT=5555
SIDECAR_BASE_URL=http://localhost:5178
```

Avviare il server Express

Avviare l'app di esempio TypeScript eseguendo npm start. Il server viene avviato http://localhost:5555 ed è pronto per accettare le richieste autenticate. L'output dovrebbe essere simile al seguente:

Server listening on port 5555
Sidecar base URL: http://localhost:5178

Mantenere aperta questa finestra del terminale. Il server Express deve continuare l'esecuzione per gestire le richieste di test nella sezione successiva.

Testare l'app di esempio TypeScript

Ora che sia il contenitore AGENT ID SDK che il server Express sono in esecuzione, è possibile testare gli scenari di autenticazione e chiamata API.

Testare con autorizzazioni delegate dall'utente

Questo scenario illustra come accedere a un utente, acquisire un token e chiamare il server Express con tale token.

Acquisire un token utente

L'esempio include un test automatizzato che acquisisce un token utente usando MSAL. Aprire una nuova finestra di PowerShell (mantenere il server Express in esecuzione) ed eseguire:

cd d:\SDKs\microsoft-identity-web\tests\DevApps\SidecarAdapter\typescript
npm test

Questo comando esegue il test di integrazione che:

Apre una finestra del browser per l'autenticazione interattiva
Acquisisce un token di accesso con l'ambito api://<your-client-id>/access_as_user
Chiama il server Express con il token
Verifica che Agent ID SDK convaliderà correttamente il token

Alla prima esecuzione viene richiesto di accedere con le credenziali di Microsoft Entra. La finestra del browser viene aperta automaticamente. Dopo aver completato l'autenticazione, è possibile chiudere il browser.

Esecuzione di test manuali con curl

Se si preferisce il test manuale, è possibile acquisire un token e chiamare direttamente il server Express:

# First, get a token (you'll need to implement token acquisition or extract from test output)
$token = "YOUR_ACCESS_TOKEN_HERE"

# Call the Express server
Invoke-RestMethod -Uri "http://localhost:5555/api/protected" `
    -Headers @{ Authorization = "Bearer $token" } `
    -Method Get

La risposta prevista è:

message                                                  protocol token          claims
-------                                                  -------- -----          ------
Request authenticated via Microsoft Identity Web Sidecar Bearer   ***redacted*** @{aud=api://"Your client ID"; iss=https://sts.win…

Testare l'autenticazione solo per applicazioni

Questo scenario illustra come chiamare le API downstream usando la propria identità dell'applicazione senza contesto utente.

Dalla finestra di PowerShell chiamare direttamente Agent ID SDK per testare il flusso di sola applicazione:

# Call Microsoft Graph using application identity
Invoke-RestMethod -Uri "http://localhost:5178/DownstreamApiUnauthenticated/me" `
    -Method Get

Questo endpoint:

Esegue l'autenticazione usando il certificato dell'applicazione (configurato in appsettings.json)
Acquisisce un token di accesso solo app per Microsoft Graph
Chiama l'endpoint API Graph /me
Restituisce le informazioni sull'entità servizio

Annotazioni

Questo scenario richiede l'autorizzazione dell'applicazione User.Read.All con il consenso dell'amministratore (configurata in precedenza nella guida introduttiva).

Testare chiamate API downstream personalizzate

È possibile testare le configurazioni dell'API downstream personalizzate aggiungendole all'SDK dell'ID agente appsettings.json.

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

Riavviare quindi il contenitore AGENT ID SDK e testare il nuovo endpoint:

# Restart container to reload configuration
docker restart agentid-sdk

# Test the new endpoint
Invoke-RestMethod -Uri "http://localhost:5178/DownstreamApiUnauthenticated/users" `
    -Method Get

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-19

Autenticare gli utenti e chiamare le API downstream con l'SDK di Microsoft Entra per l'ID dell'agente in TypeScript

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 TypeScript

Clonare o scaricare l'app di esempio

Installa le dipendenze

Configurare l'app di esempio

Avviare il server Express

Testare l'app di esempio TypeScript

Testare con autorizzazioni delegate dall'utente

Acquisire un token utente

Esecuzione di test manuali con curl

Testare l'autenticazione solo per applicazioni

Testare chiamate API downstream personalizzate

Contenuti correlati

Commenti e suggerimenti

Risorse aggiuntive